Attribution API

The Attribution API is for sending attribution campaign events (identified by idfa, idfv, or adid) that contain attribution information.

Authentication

This API uses your API key passed as a query parameter in the URL of the request:

https://api2.amplitude.com/attribution?api_key=API_KEY

For more information, see Find your API Credentials

Endpoints

Region	Endpoint
Standard server	`https://api2.amplitude.com/attribution`
EU residency server	`https://api.eu.amplitude.com/attribution`

Considerations

When Amplitude can't match attribution events to an existing user, they're held for up to 72 hours for potential user matching. If an event isn't logged for a matching user within 72 hours of receiving the attribution data, then Amplitude drops the attribution data.
For most of Amplitude's partners, Amplitude uses Advertising ID (IDFA or ADID) or vendor ID (IDFV or App Set ID) for attribution to users and events. Therefore, you must send these identifiers for attribution requests and you must set the idfa, idfv, adid and android_app_set_id fields in Amplitude as the Attribution ID.
If you are using the iOS SDK or Android SDK, you can enable tracking of the Advertising ID by following the instructions here. If you are using a JavaScript SDK or React Native, these don't have the functionality to collect Advertising ID automatically due to Google's and Apple's privacy rules around advertising ID and web tracking. You have to send the Advertising ID through the HTTP API endpoint so that Amplitude can match attribution data/events. See keys in the HTTP API V2 doc.

Send an attribution event

Send a POST request to https://api2.amplitude.com/attribution with two arguments: api_key and event.

Required arguments

Name	Description	Example
`api_key`	Required. The project's API key.	`api_key`
`event`	Required. A request parameter representing the event, in JSON format.	`{"event_type":"[YOUR COMPANY] Install", "idfa": "AEBE52E7-03EE-455A-B3C4-E57283966239", "user_properties": {"[YOUR COMPANY] media source": "facebook", "[YOUR COMPANY] campaign": "refer-a-friend"}, "platform": "ios"}`

Event argument keys

These keys are available for the Event argument.

Key	Description	Example
`event_type`	Required. String. The event info. Prefix with brackets `[YOUR COMPANY]`.	`[YOUR COMPANY] Install`
`platform`	Required. String. Either `ios` or `android`.	`ios`
`idfa` or `idfv`	Required for iOS. String. The Identifier for Advertiser or the Identifier for Vendor. You must include at least one for iOS devices.	AEBE52E7-03EE-455A-B3C4-E57283966239
`adid` or `android_app_set_id`	Required for Android. String. The Google ADID or App Set ID, or Amazon Advertising ID for Amazon devices. You must include at least one for Android devices.	AEBE52E7-03EE-455A-B3C4-E57283966239
`android_id`	Optional. String. (Android) The Android ID	AEBE52E7-03EE-455A-B3C4-E57283966239
`android_app_set_id`	Optional. String. (Android) The Android App Set ID	AEBE52E7-03EE-455A-B3C4-E57283966239
`user_properties`	Optional. Dictionary. A dictionary of attribution properties prefixed with brackets `[YOUR COMPANY]`.	`{"[YOUR COMPANY] media source": "Facebook"}`
`time`	Optional. Long. Timestamp of the event in milliseconds since epoch.	1396381378123. It's set to the upload time by default

Example request

The following code illustrates attribution for iOS.

curl --location --request POST 'https://api.amplitude.com/attribution' \
--data-urlencode 'api_key=123456789' \
--data-urlencode 'event={"event_type":"[YOUR COMPANY] Install", "idfa": "AEBE52E7-03EE-455A-B3C4-E57283966239", "user_properties": {"[YOUR COMPANY] media source": "facebook", "[YOUR COMPANY] campaign": "refer-a-friend"}, "platform": "ios"}'

curl --location --request POST 'https://api.amplitude.com/attribution' \
--data-urlencode 'api_key=123456789' \
--data-urlencode 'event={"event_type":"[YOUR COMPANY] Install", "idfa": "AEBE52E7-03EE-455A-B3C4-E57283966239", "user_properties": {"[YOUR COMPANY] media source": "facebook", "[YOUR COMPANY] campaign": "refer-a-friend"}, "platform": "ios"}'

POST /attribution HTTP/1.1
Host: api.amplitude.com
Content-Length: 365
 
api_key=&event=%7B%22event_type%22%3A%22%5BYOUR%20COMPANY%5D%20Install%22%2C%20%22idfa%22%3A%20%22AEBE52E7-03EE-455A-B3C4-E57283966239%22%2C%20%22user_properties%22%3A%20%7B%22%5BYOUR%20COMPANY%5D%20media%20source%22%3A%20%22facebook%22%2C%20%22%5BYOUR%20COMPANY%5D%20campaign%22%3A%20%22refer-a-friend%22%7D%2C%20%22platform%22%3A%20%22ios%22%7D

POST /attribution HTTP/1.1
Host: api.amplitude.com
Content-Length: 365
api_key=&event=%7B%22event_type%22%3A%22%5BYOUR%20COMPANY%5D%20Install%22%2C%20%22idfa%22%3A%20%22AEBE52E7-03EE-455A-B3C4-E57283966239%22%2C%20%22user_properties%22%3A%20%7B%22%5BYOUR%20COMPANY%5D%20media%20source%22%3A%20%22facebook%22%2C%20%22%5BYOUR%20COMPANY%5D%20campaign%22%3A%20%22refer-a-friend%22%7D%2C%20%22platform%22%3A%20%22ios%22%7D

The following example illustrates attribution on Android.

curl --location -g --request POST 'https://api2.amplitude.com/attribution?api_key=123456789&event={"event_type":"[YOUR COMPANY] Install","adid": "AEBE52E7-03EE-455A-B3C4-E57283966239", "user_properties": {"[YOUR COMPANY] media source": "facebook", "[YOUR COMPANY] campaign": "refer-a-friend"}, "platform": "android"}'

curl --location -g --request POST 'https://api2.amplitude.com/attribution?api_key=123456789&event={"event_type":"[YOUR COMPANY] Install","adid": "AEBE52E7-03EE-455A-B3C4-E57283966239", "user_properties": {"[YOUR COMPANY] media source": "facebook", "[YOUR COMPANY] campaign": "refer-a-friend"}, "platform": "android"}'

POST /attribution?api_key=api_key&event="{event_type":"[YOUR COMPANY] Install","adid": "AEBE52E7-03EE-455A-B3C4-E57283966239", "user_properties": {"[YOUR COMPANY] media source": "facebook", "[YOUR COMPANY] campaign": "refer-a-friend"}, "platform": "android"} HTTP/1.1
Host: api2.amplitude.com

POST /attribution?api_key=api_key&event="{event_type":"[YOUR COMPANY] Install","adid": "AEBE52E7-03EE-455A-B3C4-E57283966239", "user_properties": {"[YOUR COMPANY] media source": "facebook", "[YOUR COMPANY] campaign": "refer-a-friend"}, "platform": "android"} HTTP/1.1
Host: api2.amplitude.com

Responses

Code	Message
200	Success
400	The expected JSON is formatted incorrectly.