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.
Table of Contents
- Request Format
- Example Request
- Semantics Functionality for User Properties for the Identify and Group Identify APIs
- Keys for the Identification Argument
- Setting Date Values
- FAQ
IMPORTANT NOTE: Property values will not apply or appear in the platform until the user's next event. More details here.
Request Format
Send a POST or GET request to https://api.amplitude.com/identify with two request parameters:
| Required Argument | Description |
|---|---|
| api_key |
API Key from your project's Settings page. "040062a5d38552315b98302ba4f2f" |
| identification |
Either 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=040062a5d38552315b98302ba4f2f' --data 'identification=[{"user_id":"datamonster@gmail.com", "user_properties":{"Cohort":"Test A"}, "country":"United States"}]' https://api.amplitude.com/identify
Example Request with Groups
curl --data 'api_key=040062a5d38552315b98302ba4f2f' --data 'identification=[{"user_id":"datamonster@gmail.com", "user_properties":{"Cohort":"Test A"}, "groups":{"company_id":"1234"}, "country":"United States"}]' https://api.amplitude.com/identify
Semantics Functionality for User Properties for the Identify and Group Identify APIs
- $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 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.
- $remove: this functionality will remove all instances of the values specified from the list. Can give a single value or an array of values.
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.
| Key | Description |
|---|---|
| user_id
string |
(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. "12345" |
| device_id
string |
(required unless user_id is present) A device specific identifier, such as the Identifier for Vendor (IDFV) on iOS.
"C8F9E604-F01A-4BD9-95C6-8E5357DF265D" |
| user_properties
dictionary |
A 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. Note: You can store property values in an array and date values are transformed into string values. {"cohort": "Test A", "gender": "female", "interests": ["chess", "football"]} Additionally, 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). 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. You cannot drop a specific value inside of an array, you must re-set the array to contain the correct values {"$set": {"cohort": "Test A"}, "$setOnce": {"startDate": "2015-10-01"}, "$add": {"friendCount": 3}, "$append": {"interests": "Music"}, "$prepend":{"sports": "Tennis"}, "$unset": {"oldProperty": "-"}} |
| groups
string |
(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 pass that threshold will not be tracked. {"company_id": "1", "company_name":["Amplitude", "DataMonster"]} |
| app_version
string |
What version of the app the user is on.
"2.1.3" |
| platform1
string |
What platform is sending the data.
"iOS", "Android", "Web" |
| os_name1
string |
What mobile operating system or browser the user is on.
"iOS", "Android", "Chrome" |
| os_version1
string |
What version of the mobile operating system or browser the user is on.
"8.1", "4.2.2", "37" |
| device_brand1
string |
What device brand the user is on.
"Samsung", "Verizon" |
| device_manufacturer1
string |
What device manufacturer the user is on.
"Samsung", "Asus", "Apple" |
| device_model1
string |
What device model the user is on.
"Mac", "iphone 9,1", "sm-g30f" |
| carrier1
string |
What carrier the user has.
"Verizon" |
| country2
string |
What country the user is in.
"United States" |
| region2
string |
What geographical region the user is in.
"California" |
| city2
string |
What city the user is in.
"San Francisco" |
| dma2
string |
The Designated Market Area of the user.
"San Francisco-Oakland-San Jose, CA" |
| language
string |
What language the user has set.
"English" |
| paying
string |
Whether the user is paying or not.
"true" |
| start_version
string |
What version of the app the user was first on.
"2.1.1" |
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').
FAQ
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 and Amplitude event raw data as they will not count as events but instead as updates to the user property table we keep on our backend and update the User Profile top section.
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.