Skip to content

Identify users

post

/users/identify

Use this endpoint to identify an unidentified (alias-only) user.

Calling /users/identify combines the alias-only profile with the identified profile and removes the alias-only profile. To prevent unexpected loss of data when identifying users, we highly recommend that you first refer to data collection best practices to learn about capturing user data when alias-only user info is already present.

Identifying a user requires an external_id to be included in the aliases_to_identify object. If there is no user with that external_id, the external_id will simply be added to the aliased user’s record, and the user will be considered identified.

You can associate multiple additional user aliases with a single external_id. When any of such associations are made, 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.

Rate limit

For customers who onboarded with Braze on or after September 16, 2021, we apply a shared rate limit of 20,000 requests per minute to this endpoint. This rate limit is shared with the /users/delete and /users/alias/new endpoints, as documented in API rate limits.

Request body

1
2
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
1
2
3
{
   "aliases_to_identify" : (required, array of alias to identify objects)
}

Request parameters

Parameter Required Data Type Description
aliases_to_identify Required Array of aliases to identify object See alias to identify object and user alias object.

Request example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl --location --request POST 'https://rest.iad-01.braze.com/users/identify' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-API-KEY-HERE' \
--data-raw '{
  "aliases_to_identify": [
    {
      "external_id": "external_identifier",
      "user_alias": {
        "alias_name" : "example_alias",
        "alias_label" : "example_label"
      }
    }
  ]
}'

For more information on alias_name and alias_label, check out our user aliases documentation.

WAS THIS PAGE HELPFUL?
New Stuff!