Identify API

Regions

The base URL depends on your project's data residency. In all examples on this page, use the default base URL unless your project uses Amplitude's EU data center—in that case use the EU base URL in this table.

This API uses the event ingestion host api2.amplitude.com (default) or api.eu.amplitude.com (EU). Other Amplitude APIs use different hostnames (for example api.amplitude.com, core.amplitude.com, data-api.amplitude.com, or experiment.amplitude.com). The https://analytics.amplitude.com hostname is the Analytics web app (browser UI), not an ingestion endpoint.

Considerations

• You can update user properties that you haven't tracked yet. Property values don't apply or appear in the platform until the user's next event. For more information, refer to 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 threshold of events per second. A throttled request returns 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 sends events from multiple devices at the same time, Amplitude throttles all the devices. All throttling and status code guidance from Amplitude's HTTP V2 API applies to the Identify API.
• Amplitude compares dates as strings, so use the ISO 8601 format (YYYY-MM-DDTHH:mm:ss). This format lets you perform date comparisons in the web app. For example, '2016-01-31' > '2016-01-01'. This format also applies to datetime values such as '2017-08-07T10:09:08' > '2017-08-07T01:07:00'.
• Updates don't appear in Redshift because they don't count as events.
• Because Identify API calls don't count as events, the API has no effect on "active user" or "new user" definitions, and the calls don't add to your monthly event count in Amplitude.
• If you change the user_id field from an existing value, 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

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

Required parameters

Send these parameters as query parameters in a GET request, or as body parameters in a POST request. 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:

{
  "$set": {
    "cohort": "Test A"
  },
  "$setOnce": {
    "startDate": "2015-10-01"
  },
  "$add": {
    "friendCount": 3
  },
  "$append": {
    "interests": "Music"
  },
  "$prepend": {
    "sports": "Tennis"
  },
  "$unset": {
    "oldProperty": "-"
  }
}

Status codes