--- openapi: 3.0.3 info: title: Braze REST API – Remove external ID description: | Remove deprecated external IDs from users. Up to 50 IDs are allowed per request. Only deprecated IDs can be removed. 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/external_ids/remove: post: summary: Remove external ID description: | Removes deprecated external IDs. Requires `users.external_ids.remove` permission. ## Prerequisites To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics) with the `users.external_ids.remove` permission. ## Rate limit We apply a rate limit of 1,000 requests per minute to this endpoint, as documented in [API rate limits]({{site.baseurl}}/api/api_limits/). ## Request body ``` Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY ``` ```json { "external_ids" : (required, array of external identifiers to remove) } ``` ## Request parameters | Parameter | Required | Data Type | Description | | --------- | ---------| --------- | ----------- | | `external_ids` | Required | Array of strings | External identifiers for the users to remove. | ## Example request ``` curl --location --request POST 'https://rest.iad-01.braze.com/users/external_ids/remove' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR-REST-API-KEY' \ --data-raw '{ "external_ids" :[ "existing_deprecated_external_id_string", ... ] }' ``` **Important:** Only deprecated IDs can be removed; attempting to remove a primary external ID will result in an error. ## Response The response will confirm all successful removals, as well as unsuccessful removals with the associated errors. Error messages in the `removal_errors` field will reference the index in the array of the original request. ``` { "message" : (string) status message, "removed_ids" : (array of strings) successful remove operations, "removal_errors": (array of arrays) } ``` The `message` field will return `success` for any valid request. More specific errors are captured in the `removal_errors` array. The `message` field returns an error in the case of: - Invalid API key - Empty `external_ids` array - `external_ids` array with more than 50 items - Rate limit hit (more than 1,000 requests/minute) ## 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 external IDs were removed. | `success` | No action needed. | | `400 Bad Request` | The `external_ids` value isn't an array. | `'external_ids' must be an array.` | Pass `external_ids` as an array. | | `400 Bad Request` | The `external_ids` array is empty. | `'external_ids' must include at least one element.` | Include at least one external ID. | | `400 Bad Request` | More than 50 external IDs were provided. | `Max input length exceeded for 'external_ids'.` | Send 50 or fewer external IDs 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.external_ids.remove` 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: removeExternalIds tags: [User data] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RemoveExternalIdsRequest' examples: remove_ids: value: external_ids: - existing_deprecated_external_id_string responses: "200": description: Request processed. content: application/json: schema: $ref: '#/components/schemas/RemoveExternalIdsResponse' "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: RemoveExternalIdsRequest: type: object required: [external_ids] properties: external_ids: type: array minItems: 1 maxItems: 50 items: type: string RemoveExternalIdsResponse: type: object properties: message: type: string example: success removed_ids: type: array items: type: string removal_errors: type: array items: type: array items: type: string ErrorResponse: type: object properties: message: type: string