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 a valid external_id to be included in the new user alias object. If the external_id is present in the object but it is not a valid ID, the process will fail.

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
Content-Type: application/json

1
2
3
4
{
   "api_key" : (required, string) see App Group REST API Key,
   "user_aliases" : (required, array of New User Alias Object)
}

This endpoint uses the New User Alias Object Specification.

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.

User Identification Endpoint

Use this endpoint to identify an unidentified (alias-only) user.

Identifying a user requires an external_id to be included in the aliases to identify the object. If the external_id is not a valid or known ID, it will simply be added to the aliases user’s record, and the user will be considered identified.

Subsequently, you can associate multiple additional user aliases with a single external_id. When these subsequent associations are made, only the push tokens and message history associated with the user alias are retained; any attributes, events or purchases will be “orphaned” and not available on the identified user. One workaround is to export the aliased user’s data before identification using the /users/export/ids endpoint, then re-associate the attributes, events, and purchases with the identified user.

You can add up to 50 user aliases per request.

Your Endpoint will correspond to your [Braze Instance][1].

New User Identify Request

1
2
3
4
5
6
POST https://YOUR_REST_API_URL/users/identify
Content-Type: application/json
{
   "api_key" : (required, string) see App Group REST API Key,
   "aliases_to_identify" : (required, array of Aliases to Identify Object)
}

Aliases to Identify Object Specification

1
2
3
4
5
6
7
8
9
{
  "external_id" : (required, string) see External User ID below,
  // external_ids for users that do not exist will return a non-fatal error.
  // See Server Responses for details.
  "user_alias" : {
    "alias_name" : (required, string),
    "alias_label" : (required, string)
  }
}

For more information on alias_name and alias_label, check out our User Aliases documentation