Identify users

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

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

Request example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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.