## 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. | Data residency | Base URL | | -------------- | ------------------------------ | | Default | `https://api2.amplitude.com` | | EU | `https://api.eu.amplitude.com` | ## Considerations {% callout type="note" heading="Rate limiting" %} Amplitude rate limits individual users (by Amplitude ID) that update their user properties more than 1800 times per hour. This limit applies to user property syncing and not event ingestion. Amplitude continues to ingest events, but may drop user property updates for that user. {% /callout %} - 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](/docs/data/user-properties-and-events). - 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](/docs/apis/analytics/http-v2) 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` ```bash curl --location --request POST 'https://api2.amplitude.com/identify' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode '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`. | Name | Description | | ---------------- | -------------------------------------------------------------------------------------------------------------------- | | `api_key` | Your project API key. | | `identification` | Either a single JSON identification object or an array of JSON objects, each of which represents one identification. | #### Identification parameter keys | Name | Description | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | Required unless `device_id` is present. String. A UUID (unique user ID) that you specify. If you send a request with a `user_id` that's not in the Amplitude system yet, the user tied to that `user_id` isn't marked new until their first event. | | `device_id` | Required unless `user_id` is present. String. A device specific identifier, such as the Identifier for Vendor (IDFV) on iOS. | | `user_properties` | Optional. Dictionary. A dictionary of key-value pairs that represent data tied to the user. Each distinct value appears as a user segment on the Amplitude dashboard. Object depth must not exceed 40 layers. You can store property values in an array, and Amplitude transforms date values into string values. | | `groups` | Optional. Dictionary. This feature is available only to Enterprise customers who have purchased the [Accounts add-on](https://help.amplitude.com/hc/en-us/articles/115001765532). A dictionary of key-value pairs that represent groups of users. Setting groups lets you use [account-level reporting](https://help.amplitude.com/hc/en-us/articles/115001765532). You can track up to 5 unique group types and 10 total groups. | | `app_version` | Optional. String. The version of the app the user is on. | | `platform` | Optional. String. The platform that's sending the data. | | `os_name` | Optional. String. The mobile operating system or browser the user is on. | | `os_version` | Optional. String. The version of the mobile operating system or browser the user is on. | | `device_brand` | Optional. String. The device brand the user is on. | | `device_manufacturer` | Optional. String. The device manufacturer of the device that the user is on. | | `device_model` | Optional. String. The device model the user is on. | | `carrier` | Optional. String. The carrier the user has. | | `country` | Optional. String. The country that the user is in. | | `region` | Optional. String. The geographical region the user is in. | | `city` | Optional. String. The city the user is in. | | `dma` | Optional. String. The Designated Market Area of the user. | | `language` | Optional. String. The language the user has set. | | `paying` | Optional. String. Whether the user is paying. | | `start_version` | Optional. String. The version of the app the user was on first. | #### user_properties supported operations The `user_properties` field supports these operations: | Name | Description | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `$set` | Sets the value of a property. | | `$setOnce` | Sets the value only if the value isn't already set. | | `$add` | Adds a numeric value to a numeric property. | | `$append` and `$prepend` | Appends or prepends the value to a user property array. | | `$unset` | Removes a property. | | `$preInsert` | Adds the specified values to the beginning of the user property list if the values aren't already in the list. Accepts a single value or an array of values. If a list is sent, the list order is maintained. | | `$postInsert` | Adds the specified values to the end of the user property list if the values aren't already in the list. Accepts a single value or an array of values. If a list is sent, the list order is maintained. | | `$remove` | Removes all instances of the specified values from the list. Accepts a single value or an array of values. The keys in the dictionary are the user properties to operate on, and the values are the items to remove. | {% callout type="example" heading="" %} You can't mix user property operations with top-level user properties. Instead, include the top-level properties inside the `$set` operation. When using one of these operators, the dictionary can contain only user property operations. For example, you can't send `{"$append":{"interests":"Music"}, "subscription type":"paid"}` in the same request. Instead, do this: ```json { "$set": { "cohort": "Test A" }, "$setOnce": { "startDate": "2015-10-01" }, "$add": { "friendCount": 3 }, "$append": { "interests": "Music" }, "$prepend": { "sports": "Tennis" }, "$unset": { "oldProperty": "-" } } ``` {% /callout %} ## Status codes | Code | Message | | ---- | ----------------------------------------------------------------------------------------------------------------------------------------- | | 200 | Success | | 400 | Bad Request. If you get a `missing_event` message, it means the identification parameter is missing or incorrectly formatted. | | 414 | You might be using GET, which has a URL character limit. Use POST instead of GET so the data isn't passed in the URL. | | 429 | Amplitude throttles requests for `device_ids` or `user_ids` that exceed a certain threshold of events per second, and returns a 429 code. |