User Mapping (Aliasing) API

With Amplitude's Portfolio add-on, you can generate a holistic view of how your users interact with your entire product portfolio. If you've instrumented multiple platforms or product lines, Portfolio can give you unparalleled insight into your users’ complete journey.

It's not uncommon for user IDs for the same user to differ across projects within the same organization. The user mapping (aliasing) API lets you map users with different user IDs together in Amplitude.

In this example, three user records, each with a different user ID, are all merged into the user ID mike@hooli.com. This new user ID is that user's "global" user ID in the cross-project view. This way, you can get an accurate count of the number of unique users across your entire product portfolio.

Considerations¶

Keep these considerations in mind when using this API.

• When you map User 1 to User 2 (the global user ID) the event stream on User 2 contains all the events associated with User 1 and User 2. However, User 1 only contains the events associated with User 1.
• When you map users, user properties aren't merged. This means 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.
• Users are merged in aggregated counts, however when applying a group, the user IDs are listed.
• 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.

Endpoints¶

Usage¶

You can access the aliasing API endpoint by sending a POST or GET request to https://api.amplitude.com/usermap, with two query parameters.

Query parameters¶

mapping format¶

Notes about the mapping parameter's format:

• A mapping object must have a user_id key.
• If unmap is set to True, then there can't be a global_user_id. Otherwise, there must be a global_user_id:

User mapping¶

Map a user ID to a global user ID. Remember that you can map a single user ID per JSON mapping object.

This is a basic request with only the required parameters. See 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'

POST /usermap?mapping=[{"user_id":"<USER_ID", "global_user_id": "<GLOBAL_USER_ID"}]&api_key=API_KEY
HTTP/1.1
Host: api.amplitude.com

curl --location -g --request POST 'https://api.amplitude.com/usermap?mapping=[{"user_id":"63629@hmail.com", "global_user_id": "mike@hooli.com"}]&api_key=123456789'

POST /usermap?mapping=[{"user_id":"63629@hmail.com", "global_user_id": "mike@hooli.com"}]]&api_key=123456789 HTTP/1.1
Host: api.amplitude.com

curl --location -g --request POST 'curl --location -g --request POST 'https://api.amplitude.com/usermap?mapping=[{"user_id":"63629@hmail.com", "global_user_id": "mike@hooli.com"}, {"user_id":"12345@hmail.com", "global_user_id": "mike@hooli.com"}]&api_key=123456789'

POST /usermap?mapping=[{"user_id":"63629@hmail.com", "global_user_id": "mike@hooli.com"}, {"user_id":"12345@hmail.com", "global_user_id": "mike@hooli.com"}]&api_key=123456789 HTTP/1.1
Host: api.amplitude.com

User unmapping¶

This is a basic request with only the required parameters. Remember that you can unmap a single user ID per JSON mapping object. See 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'

POST /usermap?mapping=[{"user_id":"<USER_ID>", "unmap": true}]&api_key=API_KEY
HTTP/1.1
Host: api.amplitude.com

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

POST /usermap?mapping=[{"user_id":"63629@hmail.com", "unmap": true}]&api_key=123456789 HTTP/1.1
Host: api.amplitude.com

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'

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

Get existing user mappings¶

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

Query parameters¶

    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())

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