Identify users

Use this endpoint to identify an unidentified (alias-only, email-only, or phone number-only) user using the provided external ID.

How it works

Calling /users/identify combines a user profile that is identified by an alias (alias-only profile), email address (email-only profile), or phone number (phone number-only profile) with a user profile that has an external_id (identified profile), then removes the alias-only profile.

Identifying a user requires an external_id to be included in the following objects:

• aliases_to_identify
• emails_to_identify
• phone_numbers_to_identify

If there isn’t a user with that external_id, the external_id will be added to the aliased user’s record, and the user will be considered identified.

Note the following:

• When these subsequent associations are made with the merge_behavior field set to none, only the push tokens and message history associated with the user alias are retained; any attributes, events, or purchases will be “orphaned” and not available on the identified user. One workaround is to export the aliased user’s data before identification using the /users/export/ids endpoint, then re-associate the attributes, events, and purchases with the identified user.
• When associations are made with the merge_behavior field set to merge, this endpoint will merge specific fields found on the anonymous user to the identified user.
• Users can only have one alias for a specific label. If a user already exists with the external_id and has an existing alias with the same label as the alias-only profile, then the user profiles will not be combined.

Prerequisites

To use this endpoint, you’ll need an API key with the users.identify permission.

Rate limit

We apply a shared rate limit of 20,000 requests per minute to this endpoint. This rate limit is shared with the /users/delete, /users/alias/new, /users/merge, and /users/alias/update endpoints, as documented in API rate limits.

Request body

1
2
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

1
2
3
4
5
6
{
   "aliases_to_identify" : (required, array of alias to identify objects),
   "emails_to_identify": (optional, array of string) User emails to identify,
   "phone_numbers_to_identify": (optional, array of string) User phone numbers to identify,
   "merge_behavior": (optional, string) one of 'none' or 'merge' is expected
}

Request parameters

You can add up to 50 user aliases per request. You can associate multiple additional user aliases with a single external_id.

Merge_behavior field

Setting the merge_behavior field to merge sets the endpoint to merge the following list of fields found exclusively on the anonymous user to the identified user. Setting the field to none will not merge any user data to the identified user profile. By default, this field will set to merge.

Identifying users by email

If an email is specified as an identifier, you must also include prioritization in the identifier. The prioritization must be an array specifying which user to merge if there are multiple users found. prioritization is an ordered array, meaning if more than one user matches from a prioritization, then merging will not occur.

The allowed values for the array are:

• identified
• unidentified
• most_recently_updated (refers to prioritizing the most recently updated user)
• least_recently_updated (refers to prioritizing the least recently updated user)

Only one of the following options may exist in the prioritization array at a time:

• identified refers to prioritizing a user with an external_id
• unidentified refers to prioritizing a user without an external_id

If you specify identified in the array, this would mean the user must have an external_id to be entered into the Canvas. If you want users with email addresses to enter the message, regardless of whether they’re identified or not, only use the most_recently_updated or least_recently_updated parameter instead.

Request example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
curl --location --request POST 'https://rest.iad-01.braze.com/users/identify' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "aliases_to_identify": [
    {
      "external_id": "external_identifier",
      "user_alias": {
          "alias_name": "example_alias",
          "alias_label": "example_label"
      }
    }
  ],
  "emails_to_identify": [
    {
      "external_id": "external_identifier_2",
      "email": "[email protected]",
      "prioritization": ["unidentified", "most_recently_updated"]
    }
  ]
  "merge_behavior": "merge"
}'

Response

1
2
3
4
5
6
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY
{
    "aliases_processed": 1,
    "message": "success"
}