--- openapi: 3.0.3 info: title: Braze REST API – Delete users description: | Delete user profiles by specifying a known user identifier. Up to 50 `external_ids`, `user_aliases`, `braze_ids`, `email_addresses`, or `phone_numbers` can be included in a single request. Only one of those identifier types can be included in a single request. **Warning:** Deleting user profiles cannot be undone. 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 tags: - name: User data description: Identify, track, and manage your users. security: - BearerAuth: [] paths: /users/delete: post: summary: Delete users description: | Delete any user profile by specifying a known user identifier. Requires a REST API key with the `users.delete` permission. **Rate limit:** 20,000 requests per minute (shared with `/users/alias/new`, `/users/identify`, `/users/merge`, and `/users/alias/update`). ## Prerequisites To use this endpoint, you need an [API key]({{site.baseurl}}/api/basics) with the `users.delete` 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/alias/new`, `/users/identify`, `/users/merge`, and `/users/alias/update` endpoints, 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" : (optional, array of string) External IDs to be deleted, "user_aliases" : (optional, array of user alias objects) User aliases to be deleted, "braze_ids" : (optional, array of string) Braze user identifiers to be deleted, "email_addresses": (optional, array of string) User emails to be deleted, "phone_numbers": (optional, array of string) User phone numbers to be deleted } ``` ## Request parameters | Parameter | Required | Data Type | Description | |-------------------|----------|----------------------------|--------------------------------------------------------------------------------------------------| | `external_ids` | Optional | Array of strings | External identifiers to be deleted. | | `user_aliases` | Optional | Array of user alias object | [User aliases]({{site.baseurl}}/api/objects_filters/user_alias_object) to be deleted. | | `braze_ids` | Optional | Array of strings | Braze user identifiers to be deleted. | | `email_addresses` | Optional | Array of strings | User emails to be deleted. Refer to [Deleting users by email](#deleting-users-by-email) for more information. | | `phone_numbers` | Optional | Array of strings | User phone numbers to be deleted. | ### Deleting users by email addresses and phone numbers {#deleting-users-by-email} If an email address or phone number is specified as an identifier, an additional `prioritization` value is required in the identifier. `prioritization` must be an ordered array and should specify which user to delete if there are multiple users. This means deleting users does not occur if more than one user matches a prioritization. The allowed values for the array are: - `identified` - `unidentified` - `most_recently_updated` (refers to prioritizing the most recently updated user) Only one of the following options may exist in the `prioritization` array at a time: - `identified` refers to prioritizing a user with an `external_id` - `unidentified` refers to prioritizing a user without an `external_id` ## Example request ``` curl --location --request POST 'https://rest.iad-01.braze.com/users/delete' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_REST_API_KEY' \ --data-raw '{ "external_ids": ["external_identifier1", "external_identifier2"], "braze_ids": ["braze_identifier1", "braze_identifier2"], "user_aliases": [ { "alias_name": "user_alias1", "alias_label": "alias_label1" }, { "alias_name": "user_alias2", "alias_label": "alias_label2" } ], "email_addresses": [ { "email": "john.smith@example.com", "prioritization": ["unidentified", "most_recently_updated"] } ] }' ``` ## Response ```json { "deleted" : (required, integer) number of user IDs queued for deletion } ``` ## Effects of deleting user profiles When you remove a user with this endpoint, the following occurs: - The user profile is deleted (nulled). - Workspace user counts (such as total users on the [analytics home]({{site.baseurl}}/user_guide/analytics/dashboards/home)) update to account for the removed users. - The removed user still counts toward the aggregated conversion percentage. Custom event counts and purchase counts are not updated for removed users. ### Multiple profiles with a shared email address To merge user profiles that share the same email address, call the [`/users/merge` endpoint]({{site.baseurl}}/api/endpoints/user_data/post_users_merge). ## Troubleshooting ### A success response was returned but the user still appears A successful response confirms the request was queued, not that deletion is complete. Deletion typically finishes in under a second, but it can take up to five minutes for the change to propagate across all caches. If you immediately search for the user in the dashboard or export their data via the API, you may still see results during this propagation window. If the user still exists after several minutes, verify that the identifier in your request matches the user's actual profile: - **`external_ids` array:** Confirm each value matches a user's external ID exactly. - **`braze_id`:** You can find a user's `braze_id` by exporting their data with the [`/users/export/ids` endpoint]({{site.baseurl}}/api/endpoints/export/user_data/post_users_identifier) or by exporting a segment to CSV (where the `braze_id` appears as "Appboy ID"). - **Alias-only or email-only profiles:** If the profile has no `external_id`, create a segment filtering for **External User ID is blank** combined with the known email or phone number, then export to CSV to retrieve the `braze_id`. To confirm whether a user has been deleted, call the [`/users/export/ids` endpoint]({{site.baseurl}}/api/endpoints/export/user_data/post_users_identifier) using the same identifier type you used in the delete request (for example, including the value in `external_ids`, `braze_id`, or `user_aliases`). If the user no longer exists, the response contains `"users": []` and may include `"invalid_user_ids"` listing that identifier. ## 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 matching users were deleted. The response includes the number `deleted`. | `success` | No action needed. | | `400 Bad Request` | No identifier field was provided. | `external_ids, appboy_ids, braze_ids, user_aliases, email_addresses, or phone numbers is required` | Include at least one identifier field. | | `400 Bad Request` | More than one identifier type was provided. | `only one of either external_ids, appboy_ids, braze_ids, user_aliases, email_addresses, or phone_numbers can be included` | Include only one identifier type per request. | | `400 Bad Request` | More than 50 IDs were provided. | `the max number of ids per request was exceeded` | Send 50 or fewer 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.delete` 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: deleteUsers tags: - User data requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DeleteUsersRequest' examples: external_ids: summary: Delete by external_ids value: external_ids: - external_identifier_1 - external_identifier_2 braze_ids: summary: Delete by braze_ids value: braze_ids: - 5fbd99bac125ca40511f2cb1 - 5fbd99bac125ca40511f2cb2 user_aliases: summary: Delete by user_aliases value: user_aliases: - alias_name: user_alias_1 alias_label: alias_label_1 - alias_name: user_alias_2 alias_label: alias_label_2 emails_with_prioritization: summary: Delete by email_addresses with prioritization description: | When deleting by email or phone, you must include a `prioritization` array specifying which user to delete if multiple users match. value: email_addresses: - email: jane.doe@example.com prioritization: - unidentified - most_recently_updated phones_with_prioritization: summary: Delete by phone_numbers with prioritization value: phone_numbers: - phone: "+15555550100" prioritization: - identified responses: "200": description: Users queued for deletion. content: application/json: schema: $ref: '#/components/schemas/DeleteUsersResponse' examples: success: summary: Successful deletion queue value: deleted: 2 message: success "400": description: Invalid request (for example, a missing or unsupported parameter). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_request: summary: Invalid request body value: message: '"external_ids" must be an array of strings' "401": description: Unauthorized – the API key is missing, invalid, or lacks the `users.delete` permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: value: message: invalid_api_key "429": description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rate_limited: value: message: rate_limited 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.delete` permission. Pass the key as `Authorization: Bearer YOUR_REST_API_KEY`. schemas: UserAliasIdentifier: type: object required: [alias_name, alias_label] properties: alias_name: type: string description: The alias name. example: user_alias_1 alias_label: type: string description: The alias label. example: amplitude_id EmailIdentifier: type: object required: [email, prioritization] properties: email: type: string format: email example: jane.doe@example.com prioritization: type: array minItems: 1 maxItems: 2 items: type: string enum: [identified, unidentified, most_recently_updated] description: | Ordered priority for resolving multiple matching users. Only one of `identified` or `unidentified` may appear in the array at a time. example: - unidentified - most_recently_updated PhoneIdentifier: type: object required: [phone, prioritization] properties: phone: type: string description: Phone number in E.164 format. example: "+15555550100" prioritization: type: array minItems: 1 maxItems: 2 items: type: string enum: [identified, unidentified, most_recently_updated] DeleteUsersRequest: type: object description: | Only one of `external_ids`, `user_aliases`, `braze_ids`, `email_addresses`, or `phone_numbers` may be included per request. Each list is capped at 50 entries. properties: external_ids: type: array maxItems: 50 items: type: string description: External identifiers to delete. user_aliases: type: array maxItems: 50 items: $ref: '#/components/schemas/UserAliasIdentifier' braze_ids: type: array maxItems: 50 items: type: string email_addresses: type: array maxItems: 50 items: $ref: '#/components/schemas/EmailIdentifier' phone_numbers: type: array maxItems: 50 items: $ref: '#/components/schemas/PhoneIdentifier' DeleteUsersResponse: type: object required: [deleted] properties: deleted: type: integer description: Number of user IDs queued for deletion. example: 2 message: type: string example: success ErrorResponse: type: object properties: message: type: string description: Human-readable error message. errors: type: array description: Optional list of detailed validation errors. items: type: string