Attribution API

Use the Attribution API to send attribution campaign events from your mobile measurement partner or marketing platform to Amplitude. Each event identifies a user with an idfa, idfv, adid, or android_app_set_id so Amplitude can match the attribution data to the correct user and surface it across your analyses.

Matching and identifier requirements

When Amplitude can't match an attribution event to an existing user, Amplitude holds the event for up to 72 hours. If no event is logged for a matching user within 72 hours, Amplitude drops the attribution data.
For most Amplitude partners, Amplitude uses Advertising ID (IDFA or ADID) or vendor ID (IDFV or App Set ID) to attribute users and events. Send these identifiers in attribution requests, and set the idfa, idfv, adid, and android_app_set_id fields in Amplitude as the Attribution ID.
If you use the iOS SDK or Android SDK, enable Advertising ID tracking by following the iOS Swift SDK instructions. The JavaScript SDK and React Native SDK can't collect Advertising ID automatically because of Google's and Apple's privacy rules for advertising ID and web tracking. Send the Advertising ID through the HTTP API endpoint so Amplitude can match attribution events. Refer to the keys in the HTTP API V2 doc.

Send an attribution event

Send a POST request to {{standard_endpoint}} 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

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. 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. 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. Defaults to the upload time.

Example request

The following code shows attribution for iOS.

curl

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

The following code shows attribution for Android.

curl

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

Responses

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

Was this helpful?