## 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. The [Get existing user mappings](#get-existing-user-mappings) endpoint uses `https://amplitude.com` (default) or `https://analytics.eu.amplitude.com` (EU), the same hosts as other Analytics REST APIs. The `https://analytics.amplitude.com` hostname is the Analytics web app (browser UI), not the programmatic base URL for that endpoint. | Data residency | Base URL | | -------------- | ------------------------------ | | Default | `https://api.amplitude.com` | | EU | `https://api.eu.amplitude.com` | ## Considerations Note the following behaviors when using this API. - When you map User 1 to User 2 (the global user ID), the event stream on User 2 contains all events associated with User 1 _and_ User 2. User 1 only contains the events associated with User 1. - When you map users, user properties **aren't merged**. The user properties attached to each event are from the original user who triggered the event. User properties persist only on the original `user_id` and aren't transferred between User 1 and User 2. - Amplitude merges users in aggregated counts. When you apply a group, Amplitude lists the user IDs. - When you use the User Lookup feature in Amplitude, the UI indicates a mapped user with "Remapped User IDs" or "Remapping Into User ID..." - Contact Support if you need a list of merged user IDs. ## Limits The aliasing API has the following limits: - Batch limits: - Max of 2000 requests/events in a batch. - Max size of 1MB. - You can't increase batch limits. - Rate limits: - By default, Amplitude supports up to 50 events per second over a 30-second window, equalling 1500 alias calls (not batches) total in a 30-second window. - If you go over the limit, Amplitude throttles all requests until calls in the 30-second window fall below the limit. - If you need this limit increased, contact Amplitude Support. ## Query parameters | Name | Description | | --------- | --------------------------------------------------------------------------------------------------------------------- | | `api_key` | Required. Type: `string`. An API Key for any project in your organization. | | `mapping` | Required. Either a single JSON mapping object or an array of JSON objects, each of which represents a single mapping. | ### Mapping parameter | Name | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `user_id` | Required. Type: `string`. A UUID (unique user ID) specified by you, for the user you want to map. Each JSON mapping object can contain one `user_id` to map. | | `global_user_id` | Required unless `unmap` is `true`. Type: `string`. A UUID (unique user ID) specified by you. The unified identity you want to map the other `user_id` to. | | `unmap` | Optional. Type: `boolean`. When `true`, the current mapping for `user_id` is removed. | ## User mapping Map a user ID to a global user ID. You can map a single user ID per JSON mapping object. This is a basic request with only the required parameters. Refer to the examples below for more detailed requests. {% code-group %} ```bash cURL curl --location -g --request POST 'https://api.amplitude.com/usermap?mapping=[{"user_id":"", "unmap": true}]&api_key=API_KEY HTTP/1.1 Host: api.amplitude.com ``` {% /code-group %} {% accordion title="Example: Unmap a user ID" %} Unmaps the user ID "63629@hmail.com" and user ID "12345@hmail.com". {% code-group %} ```bash cURL curl --location -g --request POST 'curl --location -g --request POST 'https://api.amplitude.com/usermap?mapping=[{"user_id":"63629@hmail.com", "unmap":true}, {"user_id":"12345@hmail.com", "unmap":true}]&api_key=123456789' ``` ```bash HTTP POST /usermap?mapping=[{"user_id":"63629@hmail.com", "unmap":true}, {"user_id":"12345@hmail.com", "unmap":true}]&api_key=123456789 HTTP/1.1 Host: api.amplitude.com ``` {% /code-group %} {% /accordion %} ## Get existing user mappings Get the list of mappings that involve the provided user IDs. {% callout type="note" heading="" %} User mappings uses a different URL than the map and unmap endpoints: `https://amplitude.com/api/2/usermap`. {% /callout %} ```python user_ids = [""] request_data = { "user_ids": user_ids, } url = 'https://amplitude.com/api/2/usermap' API_KEY = "REPLACE_ME" SECRET_KEY = "REPLACE_ME" result = requests.get(url, auth=HTTPBasicAuth(API_KEY, SECRET_KEY), data=request_data) if result.status_code != 200: raise AssertionError( "Request failed. Error: code - %s, text - %s" % (result.status_code, result.text)) else: print(result.json()) ``` ### Query parameters | Name | Description | | ------------ | ------------------------------------------------------------------------------------------ | | `api_key` | Required. Type: `string`. An API Key for any project in your organization. | | `secret_key` | Required. Type: `string`. An API Secret Key for any project in your organization. | | `user_ids` | Required. A list of user ids. Minimum 1 user id, maximum 100 user ids in a single request. | ### Response The response for a POST request contains these fields: | Name | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------- | | `user id` | A user id in the request list. | | `mappings` | The mappings associated with this user id. Refer to the `mappings` fields below. Empty if the requested user isn't found. | The `mappings` key contains these fields: | Name | Description | | -------------- | --------------------------------------------------------------------------------------------------- | | `amplitude_id` | The Amplitude ID of the requested user | | `mapped_from` | A list of objects that map into the requested user. {"amplitude_id": 1234, "user_id": "mappedUser"} | | `mapped_to` | A list of objects that the requested user maps into {"amplitude_id": 1234, "user_id": "globalUser"} | ```json { "user1": { "mapped_from": [ { "amplitude_id": 1234567, "user_id": "user3" } ], "mapped_to": [ { "amplitude_id": 1234567, "user_id": "user2" } ] }, "user2": { "mapped_from": [ { "amplitude_id": 9988676, "user_id": "user1" } ], "mapped_to": [] } } ```