Delete users

Use this endpoint to delete any user profile by specifying a known user identifier.

Up to 50 external_ids, user_aliases, braze_ids, or email_addresses can be included in a single request. Only one of external_ids, user_aliases, braze_ids, or email_addresses can be included in a single request.

Prerequisites

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

Rate limit

For customers who onboarded with Braze on or after September 16, 2021, 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, and /users/merge endpoints, as documented in API rate limits.

Request body

1
2
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

1
2
3
4
5
6
{
  "external_ids" : (optional, array of string) External IDs for the users to delete,
  "user_aliases" : (optional, array of user alias objects) User aliases for the users to delete,
  "braze_ids" : (optional, array of string) Braze user identifiers for the users to delete,
  "email_addresses": (optional, array of string) User emails for the users to delete
}

Request parameters

Deleting users by email

If an email is specified as an identifier, an additional prioritization value is required in the identifier. The prioritization is an ordered array and should specify which user to delete if multiple users are found. This means deleting users will not occur if more than one user matches a prioritization.

The allowed values for the array are: identified, unidentified, most_recently_updated. 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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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": "[email protected]",
      "prioritization": ["unidentified", "most_recently_updated"]
    }
  ]
}'

Response

1
2
3
4
5
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY
{
  "deleted" : (required, integer) number of user IDs queued for deletion
}