The Amp Devcenter Test Developer Hub

Welcome to the Amp Devcenter Test developer hub. You'll find comprehensive guides and documentation to help you start working with Amp Devcenter Test as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Identify API

Use the Identify API to set the User ID for a particular Device ID or update user properties of a particular user without sending an event. You can modify Amplitude default user properties as well as custom user properties that you have defined. However, these updates will only affect events going forward. 

IMPORTANT NOTE: Property values will not apply or appear in the platform until the user's next event. More details here.

Request Format - Identify

Send a POST or GET request to https://api.amplitude.com/identify with two request parameters:

Required ArgumentDescription
api_keyAPI Key from your project's Settings page. 040062a5d38552315b98302ba4f2f
identificationEither a single JSON identification object (see below for fields) or an array of JSON objects, each of which represents one identification.
See below for examples.

Note: Amplitude will throttle requests for device_ids or user_ids that exceed a certain threshold of events per second. When we throttle a request, the response will have HTTP status code 429. You should pause sending events for any devices in that request for a period of 15 seconds before retrying and then continue retrying until you no longer receive status code 429. If the same user_id is sending events from multiple devices simultaneously, then all of those devices would be throttled.

All throttling and status code guidance from Amplitude's HTTP API applies to the Identify API

Example Request

curl --data 'api_key=API_KEY' --data 'identification=[{"user_id":"[email protected]", "user_properties":{"Age":"35"}, "country":"United States"}]' https://api.amplitude.com/identify

Example Request with Groups

curl --data 'api_key=API_KEY' --data 'identification=[{"user_id":"[email protected]", "user_properties":{"Age":"35"}, "groups":{"company_id":"1234"}, "country":"United States"}]' https://api.amplitude.com/identify 

Keys for the Identification Argument

The following keys can be sent within the JSON identification object. Note that one of user_id or device_id is required.

Example Request

curl --data 'api_key=040062a5d38552315b98302ba4f2f' --data 'identification=[{"user_id":"[email protected]", "user_properties":{"Cohort":"Test A"}, "country":"United States"}]' https://api.amplitude.com/identify
KeyTypeDescription
user_idstring(required unless device_id is present) A UUID (unique user ID) specified by you. Note: If you send a request with a user_id that is not in the Amplitude system yet, then the user tied to the user_id will not be marked new until their first event.
device_idstring(required unless user_id is present) A device specific identifier, such as the Identifier for Vendor (IDFV) on iOS.
user_propertiesdictionaryA dictionary of key-value pairs that represent additional data tied to the user. Each distinct value will show up as a user segment on the Amplitude dashboard. Object depth may not exceed 40 layers. Note: You can store property values in an array and date values are transformed into string values.0
groupsstring(Enterprise only) This feature is only available to Enterprise customers who have purchased the Accounts add-on. A dictionary of key-value pairs that represent groups of users. See this excerpt in our Javascript SDK for more information on groups. Setting groups will allow you to use our account-level reporting feature. Note: You can only track up to 5 groups. Any groups past that threshold will not be tracked.
app_versionstringWhat version of the app the user is on.
platform1stringWhat platform is sending the data.
os_name1stringWhat mobile operating system or browser the user is on.
os_version1stringWhat version of the mobile operating system or browser the user is on.
device_brand1stringWhat device brand the user is on.
device_manufacturer1stringWhat device manufacturer the user is on.
device_model1stringWhat device model the user is on.
carrier1stringWhat carrier the user has.
country2stringWhat country the user is in.
region2stringWhat geographical region the user is in.
city2stringWhat city the user is in.
dma2stringThe Designated Market Area of the user.
languagestringWhat language the user has set.
payingstringWhether the user is paying or not.
start_versionstringWhat version of the app the user was first on.

0 This field supports the following user property operations: "$set" (set the value of a property), "$setOnce" (set the value of a property, prevent overriding the property value), $add (add a numeric value to a numeric property), $append and $prepend (append and prepend the value to a user property array), and $unset (remove a property), $preInsert: this functionality will add the specified values to the beginning of the list of properties for the user property if the values do not already exist in the list. Can give a single value or an array of values. If a list is sent, the order of the list will be maintained, $postInsert: this functionality will add the specified values to the end of the list of properties for the user property if the values do not already exist in the list. Can give a single value or an array of values. If a list is sent, the order of the list will be maintained and $remove: this functionality will remove all instances of the values specified from the list. Can give a single value or an array of values. These should be keys in the dictionary where the values are the corresponding properties that you want to operate on.
Note: You cannot mix user property operations with actual top-level user properties; instead, include them inside the "$set" operation. If you are using one of these operators then this dictionary can only contain user property operations and cannot be combined with the above format e.g. you cannot do {"$append":{"interests":"Music"}, "subscription type":"paid"} in the same request.
{"$set": {"cohort": "Test A"}, "$setOnce": {"startDate": "2015-10-01"}, "$add": {"friendCount": 3}, "$append": {"interests": "Music"}, "$prepend":{"sports": "Tennis"}, "$unset": {"oldProperty": "-"}}

1 These fields (platform, os_name, os_version, device_brand, device_manufacturer, device_model, and carrier) must all be updated together. Setting any of these fields will automatically reset all of the other property values to null if they are not also explicitly set on the same identify call. All property values will otherwise persist to a subsequent event if the values are not changed to a different string or if all values are passed as null. Amplitude will attempt to use device_brand, device_manufacturer, and device_model to map the corresponding device type.

2 These fields (country, region, city, DMA) must all be updated together. Setting any of these fields will automatically reset all of the others if they are not also set on the same identify call.

Setting Date Values

Amplitude compares dates as strings, so it is recommended to use the ISO 8601 format (YYYY-MM-DDTHH:mm:ss), which will allow you to perform date comparisons in the platform (e.g. '2016-01-31' > '2016-01-01'). This will also work for datetime values (e.g. '2017-08-07T10:09:08' > '2017-08-07T01:07:00').

Status Codes

Code

Message

200

Success

414

A 414 error code, you might be using GET HTTP which has a limit on the URL. We recommend using HTTP POST instead of HTTP GET so the data is not in the URL.

429

Amplitude will throttle requests for device_ids or user_ids that exceed a certain threshold of events per second. When we throttle a request, the response will have HTTP status code 429.

FAQ - Identify

Can I update a user property that I haven't tracked yet?
Yes, you can update existing users with new properties, even if these properties do not exist in our system yet.

Will I see these updates in the raw data?
No, these updates will not show up in Redshift as they will not count as events but instead as updates to the user property table we keep on our backend.

Will these updates apply retroactively?
No, using the Identify API to update user properties will only affect data going forward.

Will making Identify API calls affect active and new user counts?
No. Since these calls are not counted as events, there is no effect on "active user" or "new user" definitions.

Will the Identify API calls add to my monthly event count in Amplitude?
No, because these calls are not counted as events.

What is the impact of changing the user_id field?
If you are changing the user_id field from an existing value, then a new Amplitude user will be generated. We will not create a new Amplitude user if the current value of user_id is null.

How are user properties applied to events?
Read our detailed support article here.

I'm getting a 414 error status code. What am I doing wrong?
If you're getting a 414 error code, you're probably using GET HTTP which has a limit on the URL. We recommend using HTTP POST instead of HTTP GET so the data is not in the URL.

Updated 3 months ago


Identify API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.