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 change Amplitude default user properties and custom user properties that you have defined.

Authentication

This API uses your API key passed in the body of the request:

For more information, see Find your API Credentials

Endpoints

Considerations

• You can update user properties that you haven't tracked yet. However, property values don't apply or appear in the platform until the user's next event. Learn more about applying user properties.
• Updates aren't retroactive, and only apply to future events.
• Amplitude throttles requests for device_ids or user_ids that exceed a certain threshold of events per second. When Amplitude throttles a request, the request returns a HTTP status code 429. Pause sending events for any devices in that request for 15 seconds before retrying. Continue retrying until you no longer receive status code 429. If the same user_id is sending events from multiple devices simultaneously, then all the devices would be throttled. All throttling and status code guidance from Amplitude's HTTP V2 API applies to the Identify API.
• Amplitude compares dates as strings, so Amplitude recommends that you use the ISO 8601 format (YYYY-MM-DDTHH:mm:ss). This lets you perform date comparisons in the web app. For example, '2016-01-31' > '2016-01-01'). This also applies to datetime values like '2017-08-07T10:09:08' > '2017-08-07T01:07:00'.
• Updates don't appear Redshift because they don't count as events.
• Because these calls aren't counted as events, this API has no effect on "active user" or "new user" definitions.
• Because these calls aren't counted as events, Identify API calls don't add to your monthly event count in Amplitude.
• If you change the user_id field from an existing value, then Amplitude creates a new user. Amplitude doesn't create a new Amplitude user if the current value of user_id is null.

Request

POST https://api2.amplitude.com/identify

1curl --location --request POST 'https://api2.amplitude.com/identify' \
2--header 'Content-Type: application/x-www-form-urlencoded' \
3--data-urlencode 'api_key=<API-KEY>' \
4--data-urlencode 'identification=[{"user_id":"value", "user_properties":{"propertyNameToUpdate":"newValue"}}]'

Required parameters

You can send these parameters as query parameter in a GET request. In a POST request, send them as body parameters. The body must be form-data or x-www-form-urlencoded.

Identification parameter keys

user_properties supported operations

The user_properties field supports these operations:

 1{
 2    "$set": {
 3        "cohort": "Test A"
 4    },
 5    "$setOnce": {
 6        "startDate": "2015-10-01"
 7    },
 8    "$add": {
 9        "friendCount": 3
10    },
11    "$append": {
12        "interests": "Music"
13    },
14    "$prepend": {
15        "sports": "Tennis"
16    },
17    "$unset": {
18        "oldProperty": "-"
19    }
20}

Status codes