---
openapi: 3.0.3
info:
title: Braze REST API – Create new user alias
description: |
Add new aliases for existing identified users, or create alias-only users.
Up to 50 alias objects are allowed per request.
version: 1.0.0
contact:
name: Braze Support
url: https://www.braze.com/docs/braze_support/
license:
name: Braze Documentation
url: https://www.braze.com/docs/api/home/
servers:
- url: https://rest.iad-01.braze.com
description: US-01
- url: https://rest.iad-02.braze.com
description: US-02
- url: https://rest.iad-03.braze.com
description: US-03
- url: https://rest.iad-04.braze.com
description: US-04
- url: https://rest.iad-05.braze.com
description: US-05
- url: https://rest.iad-06.braze.com
description: US-06
- url: https://rest.iad-07.braze.com
description: US-07
- url: https://rest.iad-08.braze.com
description: US-08
- url: https://rest.us-10.braze.com
description: US-10
- url: https://rest.fra-01.braze.eu
description: EU-01
- url: https://rest.fra-02.braze.eu
description: EU-02
- url: https://rest.au-01.braze.com
description: AU-01
- url: https://rest.id-01.braze.com
description: ID-01
- url: https://rest.jp-01.braze.com
description: JP-01
- url: https://rest.kr-01.braze.com
description: KR-01
security:
- BearerAuth: []
paths:
/users/alias/new:
post:
summary: Create new user alias
description: |
Creates aliases for users. Requires `users.alias.new` permission.
## Prerequisites
To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics) 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]({{site.baseurl}}/api/api_limits/).
## Request body
```
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY
```
```json
{
"user_aliases" : (required, array of new user alias object)
}
```
## Request parameters
| Parameter | Required | Data Type | Description |
| --------- | ---------| --------- | ----------- |
| `user_aliases` | Required | Array of new user alias objects | See [user alias object]({{site.baseurl}}/api/objects_filters/user_alias_object).
For more information on `alias_name` and `alias_label`, check out our [User Aliases]({{site.baseurl}}/user_guide/data/unification/user_data/user_profile_lifecycle#user-aliases) documentation.|
### Endpoint request body with new user alias object specification
```json
{
"external_id" : (optional, string),
"alias_name" : (required, string),
"alias_label" : (required, string)
}
```
## Example request
```
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](#when-the-alias-label-and-name-already-exist) for details.
```json
{
"aliases_processed": 1,
"message": "success"
}
```
## Troubleshooting
### Why are my attributes not updating after I create a user alias using this endpoint?
This usually happens when `/users/alias/new` is followed by a separate `/users/track` request that tries to update attributes by alias. The track request can be processed before Braze can consistently resolve the new `alias_label` and `alias_name` pair to a profile, so attributes do not land on the user you expect.
**Recommended approach:** Use a single [`/users/track`]({{site.baseurl}}/api/endpoints/user_data/post_user_track) call only when you want to create an alias-only profile or update a profile by an alias that already exists. In the `attributes` array, put `user_alias` and your profile fields in the same [user attributes object]({{site.baseurl}}/api/objects_filters/user_attributes_object/) so Braze resolves the user and applies the update in one step.
Set `_update_existing_only` to `false` when you may need to create an alias-only profile from that object. If you omit it while using `user_alias`, Braze defaults to update-only behavior and does not create the alias-only profile. If the alias already exists on a user in your workspace, the same request updates that profile with your new attributes.
You can't use `/users/track` to add a new alias to an existing user identified by `external_id`. In a user attributes object, `external_id` and `user_alias` are mutually exclusive. To add an alias to an identified user, first call `/users/alias/new`. After the alias is attached, you can update that profile with `/users/track` by `external_id` or by the existing alias.
For example, the following `/users/track` body creates an alias-only profile if the alias doesn't exist yet, or updates the existing profile that already has that alias:
```json
{
"attributes": [
{
"user_alias": {
"alias_name": "example@example.com",
"alias_label": "email"
},
"_update_existing_only": false,
"string_attribute": "test_alias_only_update"
}
]
}
```
## Response status codes
The following table lists the responses for this endpoint, the error message you may receive, and how to resolve it.
| Status code | Meaning | Error message | How to resolve |
| --- | --- | --- | --- |
| `201 Created` | The request succeeded and the user aliases were added. | `success` | No action needed. |
| `400 Bad Request` | The `aliases` value isn't an array. | `'aliases' must be an array` | Pass `aliases` as an array of alias objects. |
| `400 Bad Request` | More than 50 aliases were provided. | `Max input length exceeded for user aliases.` | Send 50 or fewer aliases per request. |
| `401 Unauthorized` | The REST API key is missing, malformed, or sent to the wrong REST endpoint. | `Invalid API key` | Send the key as `Authorization: Bearer YOUR_REST_API_KEY` to the correct [REST endpoint]({{site.baseurl}}/api/basics/#endpoints). For more causes, see [Errors and responses]({{site.baseurl}}/api/errors/#fatal-errors). |
| `403 Access Denied` | The REST API key doesn't have the required permission. | `Access Denied` | Use a REST API key that has the `users.alias.new` permission. |
| `429 Rate Limited` | You exceeded the rate limit for this endpoint. | `Over rate limit` | Slow your request rate and retry with exponential backoff. See [API rate limits]({{site.baseurl}}/api/api_limits/). |
| `5XX Internal Server Error` | An unexpected error occurred on the Braze server. | `Internal Server Error` | Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/). |
operationId: createUserAlias
tags: [User data]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserAliasRequest'
examples:
identified:
summary: Add alias for identified user
value:
user_aliases:
- external_id: external_identifier
alias_name: example_name
alias_label: example_label
alias_only:
summary: Create alias-only user
value:
user_aliases:
- alias_name: anonymous_123
alias_label: temporary_id
responses:
"201":
description: Request accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/AliasResponse'
examples:
success:
value:
aliases_processed: 1
message: success
"400":
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
"401":
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: REST API key
schemas:
NewUserAlias:
type: object
required: [alias_name, alias_label]
properties:
external_id:
type: string
alias_name:
type: string
alias_label:
type: string
CreateUserAliasRequest:
type: object
required: [user_aliases]
properties:
user_aliases:
type: array
maxItems: 50
items:
$ref: '#/components/schemas/NewUserAlias'
AliasResponse:
type: object
properties:
aliases_processed:
type: integer
message:
type: string
example: success
ErrorResponse:
type: object
properties:
message:
type: string