User Mapping (Aliasing) 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.

The 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.

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

Mapping parameter

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.

curl --location -g --request POST 'https://api.amplitude.com/usermap?mapping=[{"user_id":"<USER_ID", "global_user_id": "<GLOBAL_USER_ID"}]&api_key=API_KEY'

User unmapping

This is a basic request with only the required parameters. You can unmap a single user ID per JSON mapping object. Refer to the examples below for more detailed requests.

curl --location -g --request POST 'https://api.amplitude.com/usermap?mapping=[{"user_id":"<USER_ID", "unmap": true}]&api_key=API_KEY'

Get existing user mappings

Get the list of mappings that involve the provided user IDs.

    user_ids = ["<REPLACE ME WITH LIST OF 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

Response

The response for a POST request contains these fields:

The mappings key contains these fields:

{
  "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": []
  }
}