MARKETING ATTRIBUTION API overview

What is the IHC API?

The IHC marketing attribution API allows you to compute IHC attribution results of your customer journeys via a simple Web API. Thereby, IHC attribution can be used for adhoc analyses of your customer journeys as well as for integration into any existing ETL process.

The following sections will explain what the usage requirements are and how you can get started using IHC attribution on your data.

Getting started

Register

Please register here and make an account, we will contact you upon registration to discuss the usage plan that fits best for you.

Upload Training Data

After granting you access to the Webservice, you will have the option to upload a training set of customer journeys (csv or json file) that we will use to tailer the IHC model to your business case. You also need to specify a “Conv_Type_ID” for this training set, thereby you can tailor the IHC model to different types of conversions in your business context (e.g. new and returning customers).

Making your first API Call

Endpoint Type

POST Request

Endpoint URL

https://api.ihc-attribution.com/v1/compute_ihc

URL Parameters

conv_type_id (str: specifying which conversion type the customer journeys belong to, same as specified during training)

Request Header

API Key under x-api-key

Request Body

customer_journeys: list of sessions making up customer journeys

(optional) redistribution_parameter: dictionary of redistribution parameters defining how channel results are “redistributed” to other channels (e.g. direct channel attribution)

Request Body

customer_journeys

Required Fields

Field	Type	Description	Example Values
conversion_id	str	unique identifier of the customer journey	'conversion_id_1'
session_id	str	unique identifier of the session within the customer journey	‘session_id_567’
timestamp	str	timestamp of the session, can include timezone information (see example values)	'2021-03-20 18:49:31' (format: '%Y-%m-%d %H:%M:%S') (alternatively) with timezone information: '2021-03-20 18:49:31 +0400' (format: '%Y-%m-%d %H:%M:%S %z')
channel_label	str	information about the channel of the given session	‘Social Paid’, ‘SEO’...
holder_engagement	int	1 if session counts for holder phase, 0 if not	0 or 1
closer_engagement	int	1 if session counts for closer phase, 0 if not	0 or 1
conversion	int	1 if conversion happens during this session, 0 if not	0 or 1

Optional Fields

Field	Type	Description	Example Values	Default Value
impression_interaction	int	1 if session is an ad impression, 0 if not	0 or 1	0

Holder & Closer Engagement Classification

The IHC model requires some session-level classification, if the session contained some Holder or Closer phase related customer engagement.

Recap:

Holder phase: is a period of continued customer attention, product orientation and interest being kept,
Closer phase is where the action is taken, the homestretch and the checkout process.

Of course, you best know your products, your platform steps in the conversion funnel. Hence, you need to quantify if the customer’s session engagement is eligible for the Holder or Closer phase.

Example classifications rules:

holder_engagement = 1 , so session is eligible for Holder phase, if at least one of the following conditions is fulfilled in the session:
- 3 or more general views
- 2 or more product detail views or product searches
closer_engagement = 1, so the session is eligible for Closer phase, if at least one of the conditions is fulfilled in the session:
- 3 or more general views AND at least 1 or more checkout related steps
- conversion happened in the session

We highly recommend not to try to over-engineer these engagement classifications. The idea is to simply give the IHC algorithm some indication that the user was e.g. actively pursuing the product orientation for Holder engagement, or e.g. actively starting the checkout process for Closer engagement.

(optional) redistribution_parameter

Field	Type	Description	Example Values
direction	str	defining in which direction the attribution results from the channels in "redistribution_channel_labels" can be redistributed	"earlier_sessions_only", "later_sessions_only" or "any_session"
receive_threshold	float	minimum attribution value a session needs to have in the given phase in order to receive redistribution attribution	[0,1]
redistribution_channel_labels	list	list of channels whose attribution results should be redistributed	['direct', 'email']

With the redistribution_parameter setting you are able to tweak the attribution results even further. Imagine you would like to lower the amount of attribution that your “direct” channel receives, with the redistibution settings you can create a similar behaviour to for instance Google Analytics. Staying with the example of direct redistribution, this only works if there are other channels part of the customer journeys which are not direct. The redistribution parameter work separately for each phase of the I-H-C model and allow you to set the minimum value a session needs to receive (pre-redistribution) to receive redistribution via the “receive_threshold” setting. Meanwhile, the “direction” setting allows you to set in which time direction the redistribution should be allowed to happen. For instance, if you want to redistribute your direct traffic to other channels but only if there are non-direct channels in the customer journey before the direct touchpoint, you would set direction to “earlier_sessions_only”.

In case of questions, please contact us. We are happy to support you in the IHC setup.

import json
import requests


customer_journeys = [{'conversion_id': 'EU02785522',
  'session_id': '2020-12-27_0001_DE_82a8917d-d9cb-a665-a1ce-34e9a279445c',
  'timestamp': '2020-12-27 18:04:24',
  'channel_label': 'Shopping - Brand',
  'holder_engagement': 0,
  'closer_engagement': 0,
  'conversion': 0,
  'impression_interaction': 0},
 {'conversion_id': 'EU02785522',
  'session_id': '2021-01-05_0001_DE_82a8917d-d9cb-a665-a1ce-34e9a279445c',
  'timestamp': '2021-01-05 13:10:14',
  'channel_label': 'Affiliate',
  'holder_engagement': 1,
  'closer_engagement': 0,
  'conversion': 0,
  'impression_interaction': 0},
 {'conversion_id': 'EU02785522',
  'session_id': '2021-01-10_0001_DE_82a8917d-d9cb-a665-a1ce-34e9a279445c',
  'timestamp': '2021-01-10 16:58:36',
  'channel_label': 'SEA - Brand',
  'holder_engagement': 1,
  'closer_engagement': 0,
  'conversion': 0,
  'impression_interaction': 0},
 {'conversion_id': 'EU02785522',
  'session_id': '2021-01-10_0002_DE_82a8917d-d9cb-a665-a1ce-34e9a279445c',
  'timestamp': '2021-01-10 17:09:33',
  'channel_label': 'Email',
  'holder_engagement': 1,
  'closer_engagement': 1,
  'conversion': 1,
  'impression_interaction': 0}]
  
  
redistribution_parameter = {
    'initializer' : {
        'direction' : 'earlier_sessions_only',
        'receive_threshold' : 0,
        'redistribution_channel_labels' : ['Direct', 'Email_Newsletter'],
    },
    'holder' : {
        'direction' : 'any_session',
        'receive_threshold' : 0,
        'redistribution_channel_labels' : ['Direct', 'Email_Newsletter'],
    },
    'closer' : {
        'direction' : 'later_sessions_only',
        'receive_threshold' : 0.1,
        'redistribution_channel_labels' : ['SEO - Brand'],
    }
}

## Insert API Key here
api_key = '{api_key}'

## Insert Conversion Type ID here
conv_type_id = '{conv_type_id}'

api_url = "https://api.ihc-attribution.com/v1/compute_ihc?conv_type_id={conv_type_id}".format(conv_type_id = conv_type_id)

body = {
    'customer_journeys': customer_journeys,
    'redistribution_parameter': redistribution_parameter
}

response = requests.post(
        api_url, 
        data=json.dumps(body), 
        headers= {
            'Content-Type': 'application/json',    
            'x-api-key': api_key
        }
    )

results = response.json()

print(f"Status Code: {results['statusCode']}")

print("-"*30)

print(f"Partial Failure Errors: {results['partialFailureErrors']}")

print("-"*30)

display(results['value'])

curl --location --request POST 'https://api.ihc-attribution.com/v1/compute_ihc?conv_type_id={conv_type_id}' \
--header 'Accept: */*' \
--header 'Accept-Encoding: gzip, deflate' \
--header 'Connection: keep-alive' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {api_key}' \
--data-raw '{
    "customer_journeys": [
        {
            "conversion_id": "EU02785522",
            "session_id": "2020-12-27_0001_DE_82a8917d-d9cb-a665-a1ce-34e9a279445c",
            "timestamp": "2020-12-27 18:04:24",
            "channel_label": "Shopping - Brand",
            "holder_engagement": 0,
            "closer_engagement": 0,
            "conversion": 0,
            "impression_interaction": 0
        },
        {
            "conversion_id": "EU02785522",
            "session_id": "2021-01-05_0001_DE_82a8917d-d9cb-a665-a1ce-34e9a279445c",
            "timestamp": "2021-01-05 13:10:14",
            "channel_label": "Affiliate",
            "holder_engagement": 1,
            "closer_engagement": 0,
            "conversion": 0,
            "impression_interaction": 0
        },
        {
            "conversion_id": "EU02785522",
            "session_id": "2021-01-10_0001_DE_82a8917d-d9cb-a665-a1ce-34e9a279445c",
            "timestamp": "2021-01-10 16:58:36",
            "channel_label": "SEA - Brand",
            "holder_engagement": 1,
            "closer_engagement": 0,
            "conversion": 0,
            "impression_interaction": 0
        },
        {
            "conversion_id": "EU02785522",
            "session_id": "2021-01-10_0002_DE_82a8917d-d9cb-a665-a1ce-34e9a279445c",
            "timestamp": "2021-01-10 17:09:33",
            "channel_label": "Email",
            "holder_engagement": 1,
            "closer_engagement": 1,
            "conversion": 1,
            "impression_interaction": 0
        }
    ],
    "redistribution_parameter":
        {
            "initializer": {
                "direction" : "earlier_sessions_only",
                "receive_threshold" : 0,
                "redistribution_channel_labels" : ["Direct", "Email_Newsletter"],
            },
            "holder" : {
                "direction" : "any_session",
                "receive_threshold" : 0,
                "redistribution_channel_labels" : ["Direct", "Email_Newsletter"],
            },
            "closer" : {
                "direction" : "later_sessions_only",
                "receive_threshold" : 0.1,
                "redistribution_channel_labels" : ["SEO - Brand"],
            }
    }
}'

var myHeaders = new Headers();
myHeaders.append("Accept", "*/*");
myHeaders.append("Accept-Encoding", "gzip, deflate");
myHeaders.append("Connection", "keep-alive");
myHeaders.append("Content-Type", "application/json");
myHeaders.append("x-api-key", "{api_key}");

var raw = JSON.stringify({
  "customer_journeys": [
    {
      "conversion_id": "EU02785522",
      "session_id": "2020-12-27_0001_DE_82a8917d-d9cb-a665-a1ce-34e9a279445c",
      "timestamp": "2020-12-27 18:04:24",
      "channel_label": "Shopping - Brand",
      "holder_engagement": 0,
      "closer_engagement": 0,
      "conversion": 0,
      "impression_interaction": 0
    },
    {
      "conversion_id": "EU02785522",
      "session_id": "2021-01-05_0001_DE_82a8917d-d9cb-a665-a1ce-34e9a279445c",
      "timestamp": "2021-01-05 13:10:14",
      "channel_label": "Affiliate",
      "holder_engagement": 1,
      "closer_engagement": 0,
      "conversion": 0,
      "impression_interaction": 0
    },
    {
      "conversion_id": "EU02785522",
      "session_id": "2021-01-10_0001_DE_82a8917d-d9cb-a665-a1ce-34e9a279445c",
      "timestamp": "2021-01-10 16:58:36",
      "channel_label": "SEA - Brand",
      "holder_engagement": 1,
      "closer_engagement": 0,
      "conversion": 0,
      "impression_interaction": 0
    },
    {
      "conversion_id": "EU02785522",
      "session_id": "2021-01-10_0002_DE_82a8917d-d9cb-a665-a1ce-34e9a279445c",
      "timestamp": "2021-01-10 17:09:33",
      "channel_label": "Email",
      "holder_engagement": 1,
      "closer_engagement": 1,
      "conversion": 1,
      "impression_interaction": 0
    }
  ],
  "redistribution_parameter": {
    'initializer' : {
        'direction' : 'earlier_sessions_only',
        'receive_threshold' : 0,
        'redistribution_channel_labels' : ['Direct', 'Email_Newsletter'],
    },
    'holder' : {
        'direction' : 'any_session',
        'receive_threshold' : 0,
        'redistribution_channel_labels' : ['Direct', 'Email_Newsletter'],
    },
    'closer' : {
        'direction' : 'later_sessions_only',
        'receive_threshold' : 0.1,
        'redistribution_channel_labels' : ['SEO - Brand'],
    }
} 
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://api.ihc-attribution.com/v1/compute_ihc?conv_type_id={conv_type_id}", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

output

The response object is a dictionary with following keys:

value [list of dicts]
partialFailureErrors [list of dicts]
statusCode [int]

value

List of dictionaries with computed IHC results.

Similar to the input format, you receive a list of dictionaries whereas each dictionary makes up one session that includes the fields:

Field	Type	Description	Example Values
conversion_id	str	unique identifier of the customer journey (user input)	‘conversion_id_1’
session_id	str	unique identifier of the session within the customer journey (user input)	‘session_id_567’
initializer	numeric	intializer attribution of this session in range [0-1] (sum up to 1 within customer journey)	0.2
holder	numeric	holder attribution of this session in range [0-1] (sum up to 1 within customer journey as long as there is at least one holder engagement session in the customer journey)	0.15
closer	numeric	closer attribution of this session in range [0-1] (sum up to 1 within customer journey)	0.25
ihc	numeric	overall ihc attribution of this session in range [0-1] (sum up to 1 within customer journey)	0.18

[{'conversion_id': 'EU02785522',
  'session_id': '2020-12-27_0001_DE_82a8917d-d9cb-a665-a1ce-34e9a279445c',
  'initializer': 0.4723,
  'holder': 0.0,
  'closer': 0.0,
  'ihc': 0.2537},
 {'conversion_id': 'EU02785522',
  'session_id': '2021-01-05_0001_DE_82a8917d-d9cb-a665-a1ce-34e9a279445c',
  'initializer': 0.3635,
  'holder': 0.4067,
  'closer': 0.0,
  'ihc': 0.2524},
 {'conversion_id': 'EU02785522',
  'session_id': '2021-01-10_0001_DE_82a8917d-d9cb-a665-a1ce-34e9a279445c',
  'initializer': 0.1642,
  'holder': 0.4659,
  'closer': 0.0,
  'ihc': 0.1537},
 {'conversion_id': 'EU02785522',
  'session_id': '2021-01-10_0002_DE_82a8917d-d9cb-a665-a1ce-34e9a279445c',
  'initializer': 0.0,
  'holder': 0.1274,
  'closer': 1.0,
  'ihc': 0.3402}]

partialFailureErrors

List of dictionaries with partial errors.

In case you sent multiple customer journeys in the request, this object can be either an empty list or a list of dictionaries with partial errors specifying for which conversion_id or session_id there was an error. These are the fields:

field	type	description	example values
trigger	dictionary	indication which conversion_id and/or session_id caused the error	{'conversion_id': 'EU02785523', 'session_id': '2021-01-10_0002_DE_82a8917d-d9cb-a665-a1ce-34e9a279445c'}
reason	str	text description of what the error is	"Wrongly Formatted 'timestamp' field: 2021-01-10 17:09:71"
statusCode	int	status code of the error (in development)	406

[
   {
      "trigger":{
         "conversion_id":"EU02785523",
         "session_id":"2021-01-10_0002_DE_82a8917d-d9cb-a665-a1ce-34e9a279445c"
      },
      "reason":"Wrongly Formatted 'timestamp' field: 2021-01-10 17:09:71",
      "statusCode":406
   }
]

statusCode

Integer value with status code of the overall request and also for partial failures.

The error handling is still in development, below you can find the current status codes:

status Code	Description
200	The request has succeeded without errors
206	The request has succeeded but there are partial errors
400	Request Failure due to invalid input
406	(in partial failures object) error in parsing customer journey

Limits and Quotas

The following API limits are currently in place. Note that the maximum number of monthly requests depends on the agreement upon registration.

Limit	Description	Value
Maximum Monthly Requests	maximum number of monthly requests that can be made with the provided API Key (resets on first day of each month)	depending on agreement
Maximum Number of Customer Journeys in Single Request	number of customer journeys for which IHC can be computed with a single request call	100
Maximum Number of Sessions in Single Request	number of sessions that can be sent in a single request call	3000

MARKETING ATTRIBUTION API overview

What is the IHC API?

Getting started

Register

Upload Training Data

Making your first API Call

Endpoint Type

Endpoint URL

URL Parameters

Request Header

Request Body

Request Body

customer_journeys

Required Fields

Optional Fields

Holder & Closer Engagement Classification

(optional) redistribution_parameter

output

value

partialFailureErrors

statusCode

Limits and Quotas

Contact Us

Contact Us

REQUEST A DEMO

Get a free demo of IHC Web Service

SUCCESS!

Let's meet! Book an appointment: