Identify Users
/users/identify
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.
Looking for the api_key
parameter?
As of May 2020, Braze has changed how we read API keys to be more secure. Now API keys must be passed as a request header, please see YOUR_REST_API_KEY
within the Example Request below.
Braze will continue to support the api_key
being passed through the request body and URL parameters, but will eventually be sunset. Please update your API calls accordingly.
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
Parameter | Required | Data Type | Description |
---|---|---|---|
aliases_to_identify |
Yes | Array of Aliases to Identify Objects | See Alias to Identify Object |
Request Components
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