Create New User Alias
/users/alias/new
Use this endpoint to add new user aliases for existing identified users, or to create new unidentified users.
Adding a user alias for an existing user requires an external_id
to be included in the new user alias object. If the external_id
is present in the object but there is no user with that external_id
, the alias will not be added to any users.
Creating a new alias-only user requires the external_id
to be omitted from the new user alias object. Once the user is created, use the /users/track
endpoint to associate the alias-only user with attributes, events and purchases, and the /users/identify
endpoint to identify the user with an external_id
.
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
{
"user_aliases" : (required, array of New User Alias Object)
}
Request Parameters
Parameter | Required | Data Type | Description |
---|---|---|---|
user_aliases |
Yes | Array of New User Alias Objects | See New User Alias Object |
Request Components
- User Alias Object
For more information onalias_name
andalias_label
, check out our User Aliases documentation
Endpoint Request Body with New User Alias Object Specification
1
2
3
4
5
{
"external_id" : (optional, string) see External User ID below,
"alias_name" : (required, string),
"alias_label" : (required, string)
}
If an external_id
is not present, a user will still be created, but will need to be identified later. You can do this using the “Identifying Users” and the users/identify
endpoint.
Example Request
1
2
3
4
5
6
7
8
9
10
11
12
13
curl --location --request POST 'https://rest.iad-01.braze.com/users/alias/new' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
"user_aliases" :
[
{
"external_id": "user_id",
"alias_name" : "name",
"alias_label" : "label"
}
]
}'