Create new user alias

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.

When alias_label and alias_name already exist

The combination of alias_label and alias_name must be unique across your user base. For more information, see User aliases.

If you send a request where the alias_label and alias_name pair already exists for any user (whether on the same user or another), the endpoint still returns a successful response (for example, "aliases_processed": 1, "message": "success"). In that case, no new alias is added to the user in the request. Because the alias_label and alias_name pair is already in use, the request does not make any changes, and it can appear that the alias was never added to the user in question.

Prerequisites

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

Rate limit

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

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

When an alias is skipped because the same alias_label and alias_name already exist for a user, the response body may still indicate success. See When the alias label and name already exist for details.

1
2
3
4
{
    "aliases_processed": 1,
    "message": "success"
}