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.

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

Request Components

• 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) 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"
    }
  ]
}'