--- openapi: 3.0.3 info: title: Braze REST API – Update user alias description: | ## Prerequisites To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics) with the `users.alias.update` 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/alias/new`, `/users/identify`, and `/users/merge` endpoints, as documented in [API rate limits]({{site.baseurl}}/api/api_limits/). 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/update: post: summary: Update user alias operationId: updateUserAlias requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateUserAliasRequest' examples: rename_alias: summary: Update an alias name value: alias_updates: - alias_label: example_alias_label old_alias_name: example_old_alias_name new_alias_name: example_new_alias_name responses: "202": description: The request succeeded and the user aliases were updated. No action needed. content: application/json: schema: $ref: '#/components/schemas/AliasResponse' examples: success: summary: Alias updates accepted value: message: success "400": description: | Bad request. To resolve it: - **The `alias_updates` value isn't an array of objects:** Pass `alias_updates` as an array of objects. - **More than 50 alias updates were provided:** Send 50 or fewer alias updates per request. - **An alias update object includes unexpected keys:** Include only `alias_label`, `old_alias_name`, and `new_alias_name`. - **An alias update property isn't a string:** Send each alias property as a string. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: alias_updates_not_array: summary: The alias_updates value isn't an array of objects value: message: "'alias_updates' must be an array of objects" too_many_alias_updates: summary: More than 50 alias updates value: message: a single request may not contain more than 50 alias updates unexpected_keys: summary: Unexpected keys in an alias update object value: message: "'alias_updates' must only have 'alias_label', 'old_alias_name', and 'new_alias_name'" property_not_string: summary: An alias update property isn't a string value: message: "'alias_label', 'old_alias_name', and 'new_alias_name' must be string type" "401": description: | Unauthorized. The REST API key is missing, malformed, or sent to the wrong REST endpoint. 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). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_api_key: summary: Invalid API key value: message: 'Invalid API key: YOUR_REST_API_KEY' "403": description: Access denied. The REST API key doesn't have the required permission. Use a REST API key that has the `users.alias.update` permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: access_denied: summary: Missing permission value: message: Access Denied "429": description: | Rate limited. You exceeded the rate limit for this endpoint. Slow your request rate and retry with exponential backoff. See [API rate limits]({{site.baseurl}}/api/api_limits/). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: over_rate_limit: summary: Over rate limit value: message: You have exceeded your limit of 20000 requests per minute. Please contact your account executive to increase your limit. If you do not have their info, you may contact Braze directly at https://www.braze.com/contact/. 5XX: description: | Internal server error. An unexpected error occurred on the Braze server. Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: REST API key description: | REST API keys are created in the Braze dashboard at **Settings → APIs and Identifiers → API Keys**. The key must include the `users.alias.update` permission. Pass the key as `Authorization: Bearer YOUR_REST_API_KEY`. schemas: AliasUpdate: title: Update user alias object description: Update existing aliases by replacing `old_alias_name` with `new_alias_name` under the same `alias_label`. type: object required: [alias_label, old_alias_name, new_alias_name] additionalProperties: false properties: alias_label: type: string example: example_alias_label old_alias_name: type: string example: example_old_alias_name new_alias_name: type: string example: example_new_alias_name UpdateUserAliasRequest: title: Update user alias request type: object required: [alias_updates] properties: alias_updates: type: array minItems: 1 maxItems: 50 items: $ref: '#/components/schemas/AliasUpdate' description: | Up to 50 alias updates are allowed per request. See [user alias object]({{site.baseurl}}/api/objects_filters/user_alias_object). For more information on `old_alias_name`, `new_alias_name`, and `alias_label`, refer to [User aliases]({{site.baseurl}}/user_guide/data/unification/user_data/user_profile_lifecycle#user-aliases). AliasResponse: title: Update user alias response type: object properties: message: type: string example: success ErrorResponse: title: Error type: object properties: message: type: string description: Human-readable error message.