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 older versions of your apps that use the previous external ID naming schema don’t break.

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

Prerequisites

To use this endpoint, you’ll need an API key with the users.external_ids.rename permission.

Rate limit

We apply a rate limit of 1,000 requests per minute to this endpoint, as documented in API rate limits.

Request body

1
2
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY

1
2
3
{
  "external_id_renames" : (required, array of external ID rename objects)
}

Request parameters

Note the following:

• The current_external_id must be the user’s primary ID, and cannot be a deprecated ID.
• The new_external_id must not already be in use as either a primary ID or a deprecated ID.
• The current_external_id and new_external_id cannot be the same.

Request example

1
2
3
4
5
6
7
8
9
10
11
curl --location --request POST 'https://rest.iad-01.braze.com/users/external_ids/rename' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
  "external_id_renames" :[
    {
      "current_external_id": "existing_external_id",
      "new_external_id" : "new_external_id"
    }
  ]
}'

Response

The response will confirm all successful renames, as well as unsuccessful renames with any associated errors. Error messages in the rename_errors field will reference the index of the object in the array of the original request.

1
2
3
4
5
{
  "message" : (string) status message,
  "external_ids" : (array of strings) successful rename operations,
  "rename_errors": (array of arrays) <minor error message>
}

The message field will return success for any valid request. More specific errors are captured in the rename_errors array. The message field returns an error in the case of:

• Invalid API key
• Empty external_id_renames array
• external_id_renames array with more than 50 objects
• Rate limit hit (more than 1,000 requests per minute)

Frequently asked questions

Does this impact MAU?

No, since the number of users will stay the same, they’ll just have a new external_id.

Does user behavior change historically?

No, since the user is still the same, and all their historical behavior is still connected to them.

Can it be run on development or staging workspaces?

Yes. In fact, we highly recommend running a test migration on a staging or development workspace, and ensuring everything has gone smoothly before executing on production data.

Does this consume data points?

This feature does not cost data points.

What is the recommended deprecation period?

We have no hard limit on how long you can keep deprecated external IDs around, but we highly recommend removing them after there is no longer a need to reference users by the deprecated ID.