User Mapping (Aliasing) API

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 hank@globex.net. 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.

Authentication

This API uses your API key passed in the body of the request:

For more information, see Find your API Credentials

Endpoints

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.

Query parameters

Mapping paramater

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.

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

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

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

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

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

1POST /usermap?mapping=[{"user_id":"63629@hmail.com", "global_user_id": "hank@globex.net"}, {"user_id":"12345@hmail.com", "global_user_id": "hank@globex.net"}]&api_key=123456789 HTTP/1.1
2Host: 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.

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

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

1curl --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'

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

Get existing user mappings

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

 1user_ids = ["<REPLACE ME WITH LIST OF USER IDS>"]
 2 
 3request_data = {
 4    "user_ids": user_ids,
 5}
 6url = 'https://amplitude.com/api/2/usermap'
 7 
 8API_KEY = "REPLACE_ME"
 9SECRET_KEY = "REPLACE_ME"
10result = requests.get(url, auth=HTTPBasicAuth(API_KEY, SECRET_KEY), data=request_data)
11if result.status_code != 200:
12    raise AssertionError(
13        "Request failed. Error: code - %s, text - %s" % (result.status_code, result.text))
14else:
15    print(result.json())

Query parameters

Response

The response for a POST request contains these fields:

The mappings key contains these fields:

 1 {
 2    "user1":
 3        {
 4           "mapped_from": [{
 5               "amplitude_id": 1234567,
 6               "user_id": "user3"
 7           }],
 8           "mapped_to": [{
 9               "amplitude_id": 1234567,
10               "user_id": "user2"
11           }]
12         },
13    "user2":
14        {
15           "mapped_from": [{
16               "amplitude_id": 9988676,
17               "user_id": "user1"
18           }],
19           "mapped_to": []
20         }
21}