Rename external ID

Use this endpoint to rename your users’ external IDs.

You can send up to 50 rename objects per request.

This endpoint sets a new (primary) external_id for the user and deprecates their existing external_id. This means that the user can be identified by either external_id until the deprecated one is removed. Having multiple external IDs allows for a migration period so that legacy versions of your apps that use the previous external ID naming schema don’t break. The profile remains fully functional under both identifiers during the migration window—the Braze SDK, REST API, and messaging pipelines can continue to reference the user by either ID until the deprecated one is explicitly removed.

After your old naming schema is no longer in use, we highly recommend removing deprecated external IDs using the /users/external_ids/remove endpoint.

warning

Make sure to remove deprecated external IDs with the /users/external_ids/remove endpoint instead of /users/delete. Sending a request to /users/delete with the deprecated external ID deletes the user profile entirely and cannot be undone.

You can download the OpenAPI document and use it to validate schemas. To learn how, see Use OpenAPI schemas for request validation.