After registering, this guide will be customized for your account; please do not install the snippets below.
The Attribution.io API allows you to programatically interact with your account and extract data into your private and 3rd party systems. This API is unrelated to the integrations between your account and 3rd party services like Google Adwords, Facebook Ads or Shopify.
The API is in beta and is rolling out one endpoint at a time. Contact us if you would like specific API functionality.
Jakob at //Seibert/Media was kind enough to open source his Python SDK for the Attribution.io APIs.
All requests made to the api must be made with your accounts public key in the request and your accounts secret as a param, for example:
https://attribution.io/api/v1/PUBLIC-KEYcustomers/sample-customer-id?secret=SECRET¶m1=abc
The API is versioned and all breaking changes will include a version bump to avoid breaking integrations.
API Responses will always be in JSON format, see the individual API endpoint definitions for more information about their structure.
The API will indicate status via HTTP status codes:
| Code | Meaning |
|---|---|
| 200 | Response processed as normal. |
| 401 | Request is unauthorized: check your secret and public key. |
| 403 | Your account is disabled, please check payment status or contact us for help. |
| 404 | Your request was processed correctly, but the resource was not found. |
The Customer API endpoint lets you programatically extract the activity and attribution results for your customers. This allows you to export timeline and attribution data into your core platforms or 3rd party systems like Highrise or Salesforce.
Customer requests take the following format, using the same CUSTOMERID that you use in your identity calls:
https://attribution.io/api/v1/REPLACE_THIS_VALUE/customers/CUSTOMERID?secret=PUBLISHER_SECRET&show_all=trueCustomize the parameters as desired, see below for more information.
The customer API takes the client_id of a single customer as part of the URL and a few optional parameters to help you control what is returned.
| Param | Default | Meaning |
|---|---|---|
| show_all | false | Set to true to include pageviews, touchpoints, events and identities in the customer timeline. |
| show_pageviews | false | Set to true to include pageviews in the customer timeline. |
| show_touchpoints | false | Set to true to include touchpoints in the customer timeline. |
| show_events | false | Set to true to include events and event attribution information in the customer timeline. |
| show_identities | false | Set to true to include identities in the customer timeline. |
The API will find the specified customer and return a JSON object showing the summary and any specified activity. A sample reply is included below:
{
"customer": {
"id": 17,
"client_id": "MrSmith",
"is_anonymous": false,
"created_at": "2017-09-10T14:49:02.462-04:00",
"updated_at": "2017-09-10T14:49:02.487-04:00",
"meta": {
"first_name": "John"
},
"summary": {
"35_count": 1,
"35_attrib": [{
"medium_id": 1066,
"source_id": 3247,
"total_weight": 50.0
}, {
"medium_id": 1063,
"source_id": 3374,
"total_weight": 50.0
}],
"last_seen": "2017-09-11T19:22:00.328Z",
"events_count": 1,
"total_amount": "100.0",
"pageviews_count": 0,
"touchpoints_count": 3,
"PurchaseEventType_count": 1
},
"link": "https://attribution.io/customers/17",
"events": [{
"id": 17,
"amount": "100.0",
"location": "examplesite.com/page6",
"created_at": "2017-09-11T15:22:50.328-04:00",
"updated_at": "2017-09-10T14:49:05.363-04:00",
"event_public_key": "b5b5085e605450bb",
"client_customer_id": 17,
"event_type_id": 35,
"lifecycleStatus": 3,
"meta": null,
"is_informational": false,
"transaction_id": null,
"retry_count": null,
"aliases": null,
"event_type_name": "PurchaseEventType",
"attribution_model_outputs": [{
"id": 33,
"traffic_type": 2,
"weight": 50.0,
"event_weighted_amount": "50.0",
"event_amount": "100.0",
"event_id": 17,
"touchpoint_id": 52,
"link_id": 18,
"campaign_id": null,
"source_id": 3247,
"medium_id": 1066,
"event_type_id": 35,
"attribution_model_id": 3,
"elapsed_seconds": 88440,
"medium_name": "Referral",
"source_name": "bechtelar.io",
"link_name": null,
"traffic_type_name": "Referral",
"attribution_model_name": "Linear"
}, {
"id": 34,
"traffic_type": 1,
"weight": 50.0,
"event_weighted_amount": "50.0",
"event_amount": "100.0",
"event_id": 17,
"touchpoint_id": 54,
"link_id": null,
"campaign_id": 8,
"source_id": 3374,
"medium_id": 1063,
"event_type_id": 35,
"attribution_model_id": 3,
"elapsed_seconds": 240,
"medium_name": "Paid",
"source_name": "adnetwork",
"campaign_name": "myCampaign",
"traffic_type_name": "Paid",
"attribution_model_name": "Linear"
}]
}],
"pageviews": [{
"id": 67,
"url": "examplesite.com/page1",
"created_at": "2017-09-10T14:48:52.328-04:00",
"aliases": ["b8e42821-3ca1-474d-a2d5-def9f6ac74fc"]
}, {
"id": 68,
"url": "examplesite.com/page2",
"created_at": "2017-09-10T14:48:55.328-04:00",
"aliases": ["b8e42821-3ca1-474d-a2d5-def9f6ac74fc"]
}, {
"id": 69,
"url": "examplesite.com/page3",
"created_at": "2017-09-10T14:49:00.328-04:00",
"aliases": ["b8e42821-3ca1-474d-a2d5-def9f6ac74fc"]
}, {
"id": 70,
"url": "examplesite.com/page4",
"created_at": "2017-09-10T15:19:00.328-04:00",
"aliases": ["b8e42821-3ca1-474d-a2d5-def9f6ac74fc"]
}, {
"id": 71,
"url": "examplesite.com/page5",
"created_at": "2017-09-10T15:20:20.328-04:00",
"aliases": ["b8e42821-3ca1-474d-a2d5-def9f6ac74fc"]
}, {
"id": 72,
"url": "examplesite.com/page6",
"created_at": "2017-09-11T15:22:00.328-04:00",
"aliases": ["b8e42821-3ca1-474d-a2d5-def9f6ac74fc"]
}],
"touchpoints": [{
"id": 52,
"client_id": null,
"ip_address": "192.168.1.250",
"referrer": "http://bechtelar.io",
"url": "http://example-link.com/potato",
"created_at": "2017-09-10T14:48:50.328-04:00",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_3) AppleWebKit/537.75.14 (KHTML, like Gecko) Version/7.0.3 Safari/7046A194A",
"aliases": ["b8e42821-3ca1-474d-a2d5-def9f6ac74fc"]
}, {
"id": 53,
"client_id": null,
"ip_address": "192.168.1.250",
"referrer": null,
"url": "http://example-link.com/potato",
"created_at": "2017-09-10T15:18:50.328-04:00",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_3) AppleWebKit/537.75.14 (KHTML, like Gecko) Version/7.0.3 Safari/7046A194A",
"aliases": ["b8e42821-3ca1-474d-a2d5-def9f6ac74fc"]
}, {
"id": 54,
"client_id": null,
"ip_address": "192.168.1.250",
"referrer": "http://lebsack.info",
"url": "examplesite.com/?utm_medium=paid&utm_source=adnetwork&utm_campaign=myCampaign",
"created_at": "2017-09-11T15:18:50.328-04:00",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_3) AppleWebKit/537.75.14 (KHTML, like Gecko) Version/7.0.3 Safari/7046A194A",
"aliases": ["b8e42821-3ca1-474d-a2d5-def9f6ac74fc"]
}],
"identities": [{
"client_id": "MrSmith",
"is_anonymous": false,
"meta": {
"first_name": "John"
},
"ip_address": null,
"data_source": null,
"aliases": ["b8e42821-3ca1-474d-a2d5-def9f6ac74fc"]
}]
}
}