--- openapi: 3.0.3 info: title: Braze REST API – Remove external ID description: | ## 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/). 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 operationId: removeExternalIds requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RemoveExternalIdsRequest' examples: remove_ids: summary: Remove deprecated external IDs value: external_ids: - existing_deprecated_external_id_string responses: "201": description: | The request succeeded and the external IDs were removed. No action needed. 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. 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) content: application/json: schema: $ref: '#/components/schemas/RemoveExternalIdsResponse' examples: success: summary: All external IDs removed value: message: success removed_ids: - existing_deprecated_external_id_string removal_errors: [] partial_success: summary: Some external IDs not removed value: message: success removed_ids: - existing_deprecated_external_id_string removal_errors: - [1, "Cannot remove a user's current external ID"] - [2, External ID not found] "400": description: | Bad request. To resolve it: - **The `external_ids` value isn't an array:** Pass `external_ids` as an array. - **The `external_ids` array is empty:** Include at least one external ID. - **More than 50 external IDs were provided:** Send 50 or fewer external IDs per request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: external_ids_not_array: summary: The external_ids value isn't an array value: message: "'external_ids' must be an array." external_ids_empty: summary: The external_ids array is empty value: message: "'external_ids' must include at least one element." too_many_external_ids: summary: More than 50 external IDs value: message: Max input length exceeded for 'external_ids'. "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.external_ids.remove` 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 1000 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.external_ids.remove` permission. Pass the key as `Authorization: Bearer YOUR_REST_API_KEY`. schemas: RemoveExternalIdsRequest: title: Remove external IDs request type: object required: [external_ids] properties: external_ids: type: array minItems: 1 maxItems: 50 items: type: string description: | External identifiers for the users to remove. Up to 50 IDs are allowed per request. **Important:** Only deprecated IDs can be removed; attempting to remove a primary external ID will result in an error. example: - existing_deprecated_external_id_string RemovalError: title: Removal error type: array description: The index of the external ID in the request's `external_ids` array, followed by the minor error message for that ID. minItems: 2 maxItems: 2 items: oneOf: - type: integer title: Index - type: string title: Error message example: [1, External ID not found] RemoveExternalIdsResponse: title: Remove external IDs response type: object properties: message: type: string description: Status message. example: success removed_ids: type: array description: Successful remove operations. items: type: string removal_errors: type: array description: Unsuccessful remove operations, as an array of arrays. Each inner array holds the index of the external ID in the original request array and a minor error message. items: $ref: '#/components/schemas/RemovalError' ErrorResponse: title: Error type: object properties: message: type: string description: Human-readable error message.