Attribution API


Important Notes

  1. If attribution events cannot be matched to an existing user then they are held for up to 72 hours for potential user matching. If an event is not logged for a matching user within 72 hours of receiving the attribution data, then the attribution data will be dropped.

  2. For most of our partners, attribution is matched to Amplitude users/events via the Advertising ID (IDFA/IDFV or ADID). Therefore, you must send the Advertising ID for attribution requests and you must set the idfa, idfv, and adid fields in Amplitude as the Advertising ID.

  3. 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 JS SDK or React Native, these do not have the functionality to collect Advertising ID automatically due to Google's and Apple's privacy rules around advertising ID and web tracking. You will have to send the Advertising ID through our HTTP API endpoint so that Amplitude can match attribution data/events. See keys in our HTTP API V2 doc.

Differences between HTTP API and Attribution API

The HTTP API is for sending event data to Amplitude. These events must have a user id or a device id, and are ingested immediately.
The Attribution API, on the other hand, is for sending attribution campaign events (identified by idfa/idfv/adid) that contain attribution information. The big difference between this and the HTTP API is that if we can't match the user when an attribution event is received, it is held for up to 72 hours. If we receive regular events with user information that matches the attribution events, the attribution events will be ingested into Amplitude. Otherwise, they will be discarded. This allows attribution information to be sent without worrying about polluting Amplitude with events from people who never actually use the app.

Request Format - Attribution

Send a POST or GET request to with two request parameters:

Required ArgumentDescriptionExample
api_keyAPI key from the website.040062a5d38552315b98302ba4f2f
eventA request parameter representing the event which is a JSON key.

Sample iOS Request

curl --data 'api_key=040062a5d38552315b98302ba4f2f' \
--data '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"}'

Sample Android Request

curl --data 'api_key=040062a5d38552315b98302ba4f2f' \
--data '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"}'

Required Keys for the Event Argument

You must include the following keys within the event argument:

Required KeyTypeDescriptionExample
event_typestringPrefix with brackets "[YOUR COMPANY]"."[YOUR COMPANY] Install"
platformstringEither "ios" or "android"."ios"
idfa or idfvstring(required for iOS) The Identifier for Advertiser or the Identifier for Vendor.AEBE52E7-03EE-455A-B3C4-E57283966239
adidstring(required for Android) The Google AdID, or Amazon Advertising ID for Amazon devices.AEBE52E7-03EE-455A-B3C4-E57283966239

Note: For iOS devices, you can send either the IDFA or the IDFV but you must send at least one.

Optional Keys - Attribution

It would be helpful to include the following keys within the event argument in addition to the required event_type, and platform keys.

Additional KeyTypeDescriptionExample
android_idstring(Android) The Android IDAEBE52E7-03EE-455A-B3C4-E57283966239
user_propertiesdictionaryA dictionary of attribution properties prefixed with brackets "[YOUR COMPANY]".{"[YOUR COMPANY] media source": "Facebook"}
timelongTimestamp of the event in milliseconds since epoch.1396381378123, will be set to the upload time by default

Example iOS Request

curl --data 'api_key=040062a5d38552315b98302ba4f2f' --data '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"}'

Example Android Request

curl --data 'api_key=040062a5d38552315b98302ba4f2f' --data '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"}'

Status Codes






The expected JSON is formatted incorrectly. Check the Attribution API developers center article for formatting information.

Did this page help you?