Skip to content

Create new user alias

post

/users/alias/new

Use this endpoint to add new user aliases for existing identified users, or to create new unidentified users.

Up to 50 user aliases may be specified per request.

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. 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.

Creating a new alias-only user requires the external_id to be omitted from the new user alias object. After 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.

Prerequisites

To use this endpoint, you’ll need an API key with the users.alias.new permission.

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, /users/identify, /users/merge, and /users/alias/update endpoints, as documented in API rate limits.

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 Required Array of new user alias objects See user alias object.

For more information on alias_name and alias_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),
  "alias_name" : (required, string),
  "alias_label" : (required, string)
}

Example request

1
2
3
4
5
6
7
8
9
10
11
12
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": "external_identifier",
      "alias_name" : "example_name",
      "alias_label" : "example_label"
    }
  ]
}'

Response

1
2
3
4
5
6
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY
{
    "aliases_processed": 1,
    "message": "success"
}
HOW HELPFUL WAS THIS PAGE?
New Stuff!