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.

You can send API-triggered campaigns to users by user_alias using the /campaigns/trigger/send endpoint.

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.