After registering, this guide will be customized for your account; please do not install the snippets below.

API

Introduction

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.

Authentication

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&param1=abc

Versions

The API is versioned and all breaking changes will include a version bump to avoid breaking integrations.

Response Format

API Responses will always be in JSON format, see the individual API endpoint definitions for more information about their structure.

Response Status Codes

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.


Customer API

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.

Request Structure

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=true
Customize the parameters as desired, see below for more information.

Request Format

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.

Response

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"]
		}]
	}
}