Create New User Alias

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

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) see external user id below,
  "alias_name" : (required, string),
  "alias_label" : (required, string)
}

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-API-KEY-HERE' \
--data-raw '{
  "user_aliases" : 
  [
    {
      "external_id": "external_identifier",
      "alias_name" : "example_name",
      "alias_label" : "example_label"
    }
  ]
}'