---
openapi: 3.0.3
info:
  title: Braze REST API – Delete users
  description: |
    ## 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/).

    ## 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).
  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/delete:
    post:
      summary: Delete users
      operationId: deleteUsers
      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:
        "201":
          description: The request succeeded and the users are queued for deletion. No action needed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteUsersResponse'
              examples:
                success:
                  summary: Users queued for deletion
                  value:
                    deleted: 2
                    message: success
        "400":
          description: |
            Bad request. To resolve it:

            - **No identifier field was provided:** Include at least one identifier field.
            - **More than one identifier type was provided:** Include only one identifier type per request.
            - **More than 50 IDs were provided:** Send 50 or fewer IDs per request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                no_identifier:
                  summary: No identifier field
                  value:
                    message: external_ids, appboy_ids, braze_ids, user_aliases, email_addresses, or phone numbers is required
                multiple_identifier_types:
                  summary: More than one identifier type
                  value:
                    message: only one of either external_ids, appboy_ids, braze_ids, or user_aliases is allowed per request
                too_many_ids:
                  summary: More than 50 IDs
                  value:
                    message: the max number of ids per request was exceeded
        "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.delete` 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 20000 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.delete` permission.
        Pass the key as `Authorization: Bearer YOUR_REST_API_KEY`.
  schemas:
    UserAliasIdentifier:
      title: User alias
      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
    Prioritization:
      title: Prioritization
      type: array
      minItems: 1
      maxItems: 2
      items:
        type: string
        enum: [identified, unidentified, most_recently_updated]
      description: |
        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:
        - unidentified
        - most_recently_updated
    EmailIdentifier:
      title: Email address
      type: object
      required: [email, prioritization]
      properties:
        email:
          type: string
          format: email
          example: jane.doe@example.com
        prioritization:
          $ref: '#/components/schemas/Prioritization'
    PhoneIdentifier:
      title: Phone number
      type: object
      required: [phone, prioritization]
      properties:
        phone:
          type: string
          description: Phone number in E.164 format.
          example: "+15555550100"
        prioritization:
          $ref: '#/components/schemas/Prioritization'
    DeleteUsersRequest:
      title: Delete users request
      description: |
        Only one of `external_ids`, `user_aliases`, `braze_ids`, `email_addresses`,
        or `phone_numbers` may be included per request.
      oneOf:
        - title: By external ID
          description: Include up to 50 external IDs.
          type: object
          required: [external_ids]
          properties:
            external_ids:
              type: array
              maxItems: 50
              items:
                type: string
              description: External identifiers to be deleted.
        - title: By user alias
          description: Include up to 50 user aliases.
          type: object
          required: [user_aliases]
          properties:
            user_aliases:
              type: array
              maxItems: 50
              items:
                $ref: '#/components/schemas/UserAliasIdentifier'
              description: '[User aliases]({{site.baseurl}}/api/objects_filters/user_alias_object) to be deleted.'
        - title: By Braze ID
          description: Include up to 50 Braze IDs.
          type: object
          required: [braze_ids]
          properties:
            braze_ids:
              type: array
              maxItems: 50
              items:
                type: string
              description: Braze user identifiers to be deleted.
        - title: By email address
          description: Include up to 50 email addresses.
          type: object
          required: [email_addresses]
          properties:
            email_addresses:
              type: array
              maxItems: 50
              items:
                $ref: '#/components/schemas/EmailIdentifier'
              description: User emails to be deleted. Each entry requires a `prioritization` array.
        - title: By phone number
          description: Include up to 50 phone numbers.
          type: object
          required: [phone_numbers]
          properties:
            phone_numbers:
              type: array
              maxItems: 50
              items:
                $ref: '#/components/schemas/PhoneIdentifier'
              description: User phone numbers to be deleted. Each entry requires a `prioritization` array.
    DeleteUsersResponse:
      title: Delete users response
      type: object
      required: [deleted]
      properties:
        deleted:
          type: integer
          description: Number of user IDs queued for deletion.
          example: 2
        message:
          type: string
          example: success
    ErrorResponse:
      title: Error
      type: object
      properties:
        message:
          type: string
          description: Human-readable error message.
        errors:
          type: array
          description: Optional list of detailed validation errors.
          items:
            type: string