Braze User Data API

openapi: 3.2.0
info:
  title: Braze User Data API
  description: The Braze and Radar integration allows you to access sophisticated location-based campaign triggers and user profile enrichment with rich, first-party location data.
  version: 1.0.0
servers:
- url: https://rest.iad-01.braze.com
  description: REST endpoint for instance US-01
- url: https://rest.iad-01.braze.com
  description: REST endpoint for instance US-01
- url: https://rest.iad-02.braze.com
  description: REST endpoint for instance US-02
- url: https://rest.iad-03.braze.com
  description: REST endpoint for instance US-03
- url: https://rest.iad-04.braze.com
  description: REST endpoint for instance US-04
- url: https://rest.iad-05.braze.com
  description: REST endpoint for instance US-05
- url: https://rest.iad-06.braze.com
  description: REST endpoint for instance US-06
- url: https://rest.iad-08.braze.com
  description: REST endpoint for instance US-08
- url: https://rest.fra-01.braze.eu
  description: REST endpoint for instance EU-01
- url: https://rest.fra-02.braze.eu
  description: REST endpoint for instance EU-02
security:
- BearerAuth: []
tags:
- name: User Data
  description: The User API allows you to track information on your users by logging data about your users that comes from outside your mobile app.
paths:
  /users/track:
    post:
      tags:
      - User Data
      summary: Track Users
      description: '> Use this endpoint to record custom events, purchases, and update user profile attributes.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                attributes:
                - external_id: rachel_feinberg
                  string_attribute: fruit
                  boolean_attribute_1: true
                  integer_attribute: 25
                  array_attribute:
                  - banana
                  - apple
                events:
                - external_id: user_identifier
                  app_id: your_app_identifier
                  name: rented_movie
                  time: '2022-12-06T19:20:45+01:00'
                  properties:
                    release:
                      studio: FilmStudio
                      year: '2022'
                    cast:
                    - name: Actor1
                    - name: Actor2
                - user_alias:
                    alias_name: device123
                    alias_label: my_device_identifier
                  app_id: your_app_identifier
                  name: rented_movie
                  time: '2013-07-16T19:20:50+01:00'
                purchases:
                - external_id: user_identifier
                  app_id: your_app_identifier
                  product_id: product_name
                  currency: USD
                  price: 12.12
                  quantity: 6
                  time: '2017-05-12T18:47:12Z'
                  properties:
                    color: red
                    monogram: ABC
                    checkout_duration: 180
                    size: Large
                    brand: Backpack Locker
              properties:
                attributes:
                  type: array
                  items:
                    type: object
                events:
                  type: array
                  items:
                    type: object
                purchases:
                  type: array
                  items:
                    type: object
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: Authorization
        in: header
        schema:
          type: string
        example: Bearer {{api_key}}
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      operationId: postUsersTrack
      x-operation-id-source: derived
  /users/alias/update:
    post:
      tags:
      - User Data
      summary: Update User Alias
      description: '> Use this endpoint to update existing user aliases.


        To use this endpoint, youll need to generate an API key with the `users.alias.update` permission.


        Up to 50 user aliases may be specified per request.


        This endpoint does not guarantee the sequence of `alias_updates` objects being updated.


        Updating a user alias requires `alias_label`, `old_alias_name`, and `new_alias_name` to be included in the update user alias object. If there is no user alias associated with the `alias_label` and `old_alias_name`, no alias will be updated. If the given `alias_label` and `old_alias_name` is found, then the `old_alias_name` will be updated to the `new_alias_name`.


        ## 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/delete`, `/users/identify`, `/users/merge`, and `/users/alias/update` endpoints, as documented in API rate limits.


        ### Request parameters


        | Parameter | Required | Data Type | Description |

        | --- | --- | --- | --- |

        | `alias_updates` | Required | Array of update user alias objects | See user alias object.


        For more information on `old_alias_name`, `new_alias_name`, and `alias_label`, refer to User aliases. |


        ### Endpoint request body with update user alias object specification


        ``` json

        {

        "alias_label" : (required, string),

        "old_alias_name" : (required, string),

        "new_alias_name" : (required, string)

        }


        ```'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                alias_updates:
                - alias_label: example_alias_label
                  old_alias_name: example_old_alias_name
                  new_alias_name: example_new_alias_name
              properties:
                alias_updates:
                  type: array
                  items:
                    type: object
                    properties:
                      alias_label:
                        type: string
                      old_alias_name:
                        type: string
                      new_alias_name:
                        type: string
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: Authorization
        in: header
        schema:
          type: string
        example: Bearer {{api_key}}
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      operationId: postUsersAliasUpdate
      x-operation-id-source: derived
  /users/alias/new:
    post:
      tags:
      - User Data
      summary: Create New User Aliases
      description: '> Use this endpoint to add new user aliases for existing identified users, or to create new unidentified users.


        To use this endpoint, youll need to generate an API key with the `users.alias.new` permission.


        Up to 50 user aliases may be specified per request.


        **Adding a user alias for an existing user** requires an `external_id` to be included in the new user alias object. If the `external_id` is present in the object but there is no user with that `external_id`, the alias will not be added to any users. If an `external_id` is not present, a user will still be created but will need to be identified later. You can do this using the "Identifying Users" and the `users/identify` endpoint.


        **Creating a new alias-only user** requires the `external_id` to be omitted from the new user alias object. Once the user is created, use the `/users/track` endpoint to associate the alias-only user with attributes, events, and purchases, and the `/users/identify` endpoint to identify the user with an `external_id`.


        ### 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/delete` and `/users/identify` endpoints, as documented in API rate limits.


        ### Request parameters


        | Parameter | Required | Data Type | Description |

        | --- | --- | --- | --- |

        | `user_aliases` | Required | Array of new user alias objects | See user alias object.


        For more information on `alias_name` and `alias_label`, check out our User Aliases documentation. |'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                user_aliases:
                - external_id: external_identifier
                  alias_name: example_name
                  alias_label: example_label
              properties:
                user_aliases:
                  type: array
                  items:
                    type: object
                    properties:
                      external_id:
                        type: string
                      alias_name:
                        type: string
                      alias_label:
                        type: string
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: Authorization
        in: header
        schema:
          type: string
        example: Bearer {{api_key}}
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      operationId: postUsersAliasNew
      x-operation-id-source: derived
  /users/delete:
    post:
      tags:
      - User Data
      summary: Delete Users
      description: '> Use this endpoint to delete any user profile by specifying a known user identifier.


        To use this endpoint, youll need to generate an API key with the `users.delete` permission.


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


        > **Important:** Deleting user profiles cannot be undone. It will permanently remove users which may cause discrepancies in your data. Learn more about what happens when you delete a user profile via API in our Help documentation.


        ### 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` and `/users/identify` endpoints, as documented in API rate limits.


        ### Request parameter


        | Parameter | Required | Data Type | Description |

        | --- | --- | --- | --- |

        | `external_ids` | Optional | Array of strings | External identifiers for the users to delete. |

        | `user_aliases` | Optional | Array of user alias object | User aliases for the users to delete. |

        | `braze_ids` | Optional | Array of strings | Braze user identifiers for the users to delete. |'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                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
              properties:
                external_ids:
                  type: array
                  items:
                    type: string
                braze_ids:
                  type: array
                  items:
                    type: string
                user_aliases:
                  type: array
                  items:
                    type: object
                    properties:
                      alias_name:
                        type: string
                      alias_label:
                        type: string
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: Authorization
        in: header
        schema:
          type: string
        example: Bearer {{api_key}}
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      operationId: postUsersDelete
      x-operation-id-source: derived
  /users/identify:
    post:
      tags:
      - User Data
      summary: Identify Users
      description: '> Use this endpoint to identify an unidentified (alias-only) user.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                aliases_to_identify:
                - external_id: external_identifier
                  user_alias:
                    alias_name: example_alias
                    alias_label: example_label
              properties:
                aliases_to_identify:
                  type: array
                  items:
                    type: object
                    properties:
                      external_id:
                        type: string
                      user_alias:
                        type: object
                        properties:
                          alias_name:
                            type: string
                          alias_label:
                            type: string
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: Authorization
        in: header
        schema:
          type: string
        example: Bearer {{api_key}}
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      operationId: postUsersIdentify
      x-operation-id-source: derived
  /users/merge:
    post:
      tags:
      - User Data
      summary: Merge Users
      description: '> Use this endpoint to merge one user into another user.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                merge_updates:
                - identifier_to_merge:
                    external_id: old-user1
                  identifier_to_keep:
                    external_id: current-user1
                - identifier_to_merge:
                    user_alias:
                      alias_name: old-user2@example.com
                      alias_label: email
                  identifier_to_keep:
                    user_alias:
                      alias_name: current-user2@example.com
                      alias_label: email
              properties:
                merge_updates:
                  type: array
                  items:
                    type: object
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: Authorization
        in: header
        schema:
          type: string
        example: Bearer {{api_key}}
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      operationId: postUsersMerge
      x-operation-id-source: derived
components:
  responses:
    Unauthorized:
      description: 401 Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: 400 Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: 404 Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: 403 Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: 500 Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: 429 Rate Limited
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
        errors:
          type: array
          items:
            type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer