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.

Subsequently, you can associate multiple additional user aliases with a single external_id. When these subsequent 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.

You can add up to 50 user aliases per request.

Request Body

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

1
2
3
{
   "aliases_to_identify" : (required, array of Aliases to Identify Object)
}

Request Parameters

Request Components

• Alias to Identify Object
• User Alias Object

Request Body with Aliases to Identify Object

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
   "aliases_to_identify" : (required, array of Aliases to Identify Object)
   [
     {
       "external_id" : (required, string) see External User ID below,
       // external_ids for users that do not exist will return a non-fatal error.
       // See Server Responses for details.
       "user_alias" : {
         "alias_name" : (required, string),
         "alias_label" : (required, string)
       }
     }
   ]
}

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_REST_API_KEY' \
--data-raw '{
  "aliases_to_identify" : 
  [
    {
      "external_id": "user_id",
      "user_alias" : {
          "alias_name" : "user_alias123",
          "alias_label" : "label"
      }
    }
  ]
}'

For more information on alias_name and alias_label, check out our User Aliases documentation. You can learn more about the Alias to Identify Object here