openapi: 3.0.0 info: title: Braze 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. When Radar geofence or trip tracking events are generated, custom events and user attributes are sent to Braze in real-time. These events and attributes can then be used to trigger location-based campaigns, power last-mile pickup and delivery operations, monitor fleet and shipping logistics, or build user segments based on location patterns. 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 components: responses: BadRequest: description: 400 Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: 401 Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: 403 Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: 404 Not Found content: application/json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: 429 Rate Limited content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: 500 Internal Server Error 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 tags: - name: Catalogs description: >- Use the Braze Catalogs Endpoints to add, edit, and manage your catalogs and catalog item details. You can use the asynchronous catalog endpoints to make bulk changes to your catalog. Looking for guidance on creating a catalog? Check out our article for [creating and using catalogs](https://www.braze.com/docs/user_guide/personalization_and_dynamic_content/catalog/). - name: Catalogs > Catalog Management - name: Catalogs > Catalog Management > Synchronous - name: Catalogs > Catalog Items - name: Catalogs > Catalog Items > Asynchronous - name: Catalogs > Catalog Items > Synchronous - name: Email Lists & Addresses description: >- Users email subscription status can be updated and retrieved via Braze using a RESTful API. You can use the API to set up bi-directional sync between Braze and other email systems or your own database. - name: Export description: >+ With this collection of endpoints, you will be able to access and export various levels of details on your users, segments, campaigns, and Canvases. Please be sure to reference the correct Instance when making API requests. - name: Export > Campaign - name: Export > Canvas - name: Export > Custom Events - name: Export > KPI - name: Export > News Feed - name: Export > Purchases - name: Export > Segment - name: Export > Session Analytics - name: Export > Users - name: Messaging description: >+ The Braze messaging API provides you with two distinct options for sending messages to your users. You can provide the message contents and configuration in the API request with the /messages/send and /messages/schedule endpoints. Alternatively, you can manage the details of your message with an API-Triggered Delivery campaign in the dashboard and just control when and to whom it is sent with the campaigns/trigger/send and campaigns/trigger/schedule endpoints. The following sections will detail the request specification for both methods. The examples below contain the URL https://rest.iad-01.braze.com, but some customers will need to use a different endpoint URL, for example if you are hosted in Brazes EU data center or have a dedicated Braze installation. Your Success Manager will inform you if you should use a different endpoint URL. Similarly to other campaigns, you can limit the number of times a particular user can receive a Messaging API campaign by configuring re-eligibility settings in the Braze Dashboard. Braze will not deliver API messages to users that havent become re-eligible for the campaign regardless of how many API requests are sent. - name: Messaging > Live Activities - name: Messaging > Schedule Mesages - name: Messaging > Send Messages - name: Preference Center - name: SCIM - name: SMS description: >- Use the Braze SMS Endpoints to manage your users phone numbers in your subscription groups. - name: Subscription Groups description: >- Use the Subscription Group REST APIs to programmatically manage the subscription groups that you have stored on the Braze dashboard, on the Subscription Group page. - name: Subscription Groups > Email - name: Subscription Groups > SMS and WhatsApp - name: Templates - name: Templates > Content Blocks description: >- Content Blocks are an Email Templating feature that allow you to: - Create a consistent look and feel to your Email campaigns using Content Blocks as Headers and Footers. - Distribute the same offer codes through different channels. - Create pre-defined assets that can be used to build messages with consistent information and assets. - Copy entire message bodies to other messages. You can edit Content Blocks in the Templates & Media section of the Braze UI, or here, via API. - name: Templates > Email Templates - 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. You can also use this API to delete users for testing or other purposes. All API endpoints have a data payload limit of 4MB. Attempts to post more data than 4MB will fail with an HTTP 413 Request Entity Too Large. The examples below contain the URL https://rest.iad-01.braze.com, but some customers will need to use a different endpoint URL, for example if you are hosted in Brazes EU data center or have a dedicated Braze installation. Your Success Manager will inform you if you should use a different endpoint URL. - name: User Data > External ID Migration description: >- The External ID Migration API allows you to rename existing external IDs (creating a new primary ID and deprecating the existing ID) and remove deprecated IDs post-migration.

We've architected this solution to allow multiple External IDs in order to support a migration period whereby older versions of your apps still in the wild that use the previous External ID naming schema dont break. We highly recommend removing deprecated External IDs once your old naming schema is no longer in use. paths: /templates/email/update: post: tags: - Templates > Email Templates summary: Update Email Template description: >- > Use this endpoint to update email templates on the Braze dashboard. To use this endpoint, youll need to generate an API key with the `templates.email.update` permission. You can access an email templates `email_template_id` by navigating to it on the **Templates & Media** page. The [Create email template endpoint](https://www.braze.com/docs/api/endpoints/templates/email_templates/post_create_email_template/) will also return an `email_template_id` reference. All fields other than the `email_template_id` are optional, but you must specify at least one field to update. ### Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ### Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `email_template_id` | Required | String | Your [email template's API identifier](https://www.braze.com/docs/api/identifier_types/). | | `template_name` | Optional | String | Name of your email template. | | `subject` | Optional | String | Email template subject line. | | `body` | Optional | String | Email template body that may include HTML. | | `plaintext_body` | Optional | String | A plaintext version of the email template body. | | `preheader` | Optional | String | Email preheader used to generate previews in some clients. | | `tags` | Optional | String | [Tags](https://www.braze.com/docs/user_guide/administrative/app_settings/manage_app_group/tags/) must already exist. | | `should_inline_css` | Optional | Boolean | Enables or disables the `inline_css` feature per template. If not provided, Braze will use the default setting for the AppGroup. One of `true` or `false` is expected. | ### Possible errors The following table lists possible returned errors and their associated troubleshooting steps, if applicable. | Error | Troubleshooting | | --- | --- | | Template name is required | | | Tags must be an array | Tags must be formatted as an array of strings, for example `["marketing", "promotional", "transactional"]`. | | All tags must be strings | Make sure your tags are encapsulated in quotes (`""`). | | Some tags could not be found | To add a tag when creating an email template, the tag must already exist in Braze. | | Invalid value for `should_inline_css`. One of `true` or `false` was expected | This parameter only accepts boolean values (true or false). Make sure the value for `should_inline_css` is not encapsulated in quotes (`""`), which causes the value to be sent as a string instead. | requestBody: content: application/json: schema: type: object example: email_template_id: email_template_id template_name: Weekly Newsletter subject: This Week's Styles body: >- Check out this week's digital lookbook to inspire your outfits. Take a look at https://www.braze.com/ plaintext_body: >- This is the updated text within my email body and here is a link to https://www.braze.com/. preheader: We want you to have the best looks this Summer tags: - Tag1 - Tag2 properties: email_template_id: type: string template_name: type: string subject: type: string body: type: string plaintext_body: type: string preheader: type: string tags: type: array items: 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' /users/track: post: tags: - User Data summary: Track Users description: >- > Use this endpoint to record custom events, purchases, and update user profile attributes. To use this endpoint, youll need to generate an API key with the `users.track` permission. **Note:** Braze processes the data passed via API at face value and customers should only pass deltas (changing data) to minimize unnecessary data point consumption. To read more, refer to [Data points](https://www.braze.com/docs/user_guide/onboarding_with_braze/data_points#data-points). Customers using the API for server-to-server calls may need to allowlist `rest.iad-01.braze.com` if theyre behind a firewall. ### Rate limit We apply a base speed limit of 50,000 requests per minute to this endpoint for all customers. Each request to the `/users/track` endpoint can contain up to 75 events, 75 attribute updates, and 75 purchases. Each component (event, attribute, and purchase arrays), can update up to 75 users each for a max of 225 individual data points. Each update can also belong to the same user for a max of 225 updates to a single user in a request. See our page on [API rate limits](https://www.braze.com/docs/api/api_limits/) for details, and reach out to your customer success manager if you need your limit increased. ### Request parameters For each of the request components listed in the following table, one of `external_id`, `user_alias`, or `braze_id` is required. | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `attributes` | Optional | Array of attributes objects | See [user attributes object](https://www.braze.com/docs/api/objects_filters/user_attributes_object/) | | `events` | Optional | Array of event objects | See [events object](https://www.braze.com/docs/api/objects_filters/event_object/) | | `purchases` | Optional | Array of purchase objects | See [purchases object](https://www.braze.com/docs/api/objects_filters/purchase_object/) | ## User track responses Upon using any of the aforementioned API requests you should receive one of the following three general responses: #### Successful message Successful messages will be met with the following response: ``` json { "message" : "success", "attributes_processed" : (optional, integer), if attributes are included in the request, this will return an integer of the number of external_ids with attributes that were queued to be processed, "events_processed" : (optional, integer), if events are included in the request, this will return an integer of the number of events that were queued to be processed, "purchases_processed" : (optional, integer), if purchases are included in the request, this will return an integer of the number of purchases that were queued to be processed, } ``` #### Successful message with non-fatal errors If your message is successful but has non-fatal errors such as one invalid event object out of a long list of events, then you will receive the following response: ``` json { "message" : "success", "errors" : [ { } ] } ``` #### Message with fatal errors In the case of a success, any data that was not affected by an error in the `errors` array will still be processed. If your message has a fatal error you will receive the following response: ``` json { "message" : , "errors" : [ { } ] } ``` ### Fatal error response codes For status codes and associated error messages that will be returned if your request encounters a fatal error, reference [Fatal errors & responses](https://www.braze.com/api/errors/#fatal-errors). If you receive the error provided external_id is blacklisted and disallowed, your request may have included a dummy user. For more information, refer to [Spam blocking](https://www.braze.com/docs/user_guide/data_and_analytics/user_data_collection/user_archival/#spam-blocking). ### Creating an alias-only user profile Keep the following nuances in mind when using the `/users/track` endpoint: You can use the `/users/track` endpoint to create a new alias-only user by setting the `_update_existing_only` key with a value of `false` in the body of the request. If this value is omitted, the alias-only user profile will not be created. Using an alias-only user guarantees that one profile with that alias will exist. This is especially helpful when building a new integration as it prevents the creation of duplicate user profiles. ### Importing legacy user data You may submit data through the Braze API for a user who has not yet used your mobile app in order to generate a user profile. If the user subsequently uses the application all information following their identification via the SDK will be merged with the existing user profile you created via the API call. Any user behavior that is recorded anonymously by the SDK prior to identification will be lost upon merging with the existing API-generated user profile. The segmentation tool will include these users regardless of whether they have engaged with the app. If you want to exclude users uploaded via the User API who have not yet engaged with the app, simply add the filter: `Session Count > 0`. ### Making bulk updates If you have a use case where you need to make batch updates to the `users/track` endpoint, we recommend adding the bulk update header so that Braze can properly identify, observe, and route your request. Refer to the following sample request with the `X-Braze-Bulk` header: ``` json curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \ --header 'Content-Type: application/json' \ --header 'X-Braze-Bulk: true' \ --header 'Authorization: Bearer YOUR-API-KEY-HERE' \ --data-raw '{ "attributes": [ ], "events": [ ], "purchases": [ ] }' ``` Warning: When the `X-Braze-Bulk` header is present with any value, Braze will consider the request a bulk request. Set the value to `true`. Currently, setting the value to `false` does not disable the headerit will still be treated as if it were true. #### Use cases Consider the following use cases where you may use the bulk update header: - A daily job where multiple users custom attributes are updated via the `/users/track` endpoint. - An ad-hoc user data backfill script which updates user information via the `/users/track` endpoint. 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' /catalogs/{catalog_name}: delete: tags: - Catalogs > Catalog Management > Synchronous summary: Delete Catalog description: >- > Use this endpoint to delete a catalog. To use this endpoint, youll need to generate an API key with the `catalogs.delete` permission. ## Rate limit This endpoint has a shared rate limit of 5 requests per minute between all synchronous catalog endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Path parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `catalog_name` | Required | String | Name of the catalog. | ## Response There are two status code responses for this endpoint: `200` and `404`. ### Example success response The status code `200` could return the following response body. ``` json { "message": "success" } ``` ### Example error response The status code `404` could return the following response body. Refer to [Troubleshooting](https://www.braze.com/docs/api/endpoints/catalogs/catalog_management/synchronous/delete_catalog/#troubleshooting) for more information about errors you may encounter. ``` json { "errors": [ { "id": "catalog-not-found", "message": "Could not find catalog", "parameters": [ "catalog_name" ], "parameter_values": [ "restaurants" ] } ], "message": "Invalid Request" } ``` ## Troubleshooting The following table lists possible returned errors and their associated troubleshooting steps. | Error | Troubleshooting | | --- | --- | | `catalog-not-found` | Check that the catalog name is valid. | parameters: - name: Content-Type in: header schema: type: string example: application/json - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: catalog_name in: path schema: type: string required: true responses: '200': 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' /catalogs: get: tags: - Catalogs > Catalog Management > Synchronous summary: List Catalogs description: >- > Use this endpoint to return a list of catalogs in a workspace. To use this endpoint, youll need to generate an API key with the `catalogs.get` permission. ## Rate limit This endpoint has a shared rate limit of 5 requests per minute between all synchronous catalog endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Path and request parameters There are no path or request parameters for this endpoint. ## Example request ``` curl --location --request GET 'https://rest.iad-03.braze.com/catalogs' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR-REST-API-KEY' ``` ## Response ### Example success response The status code `200` could return the following response body. ``` json { "catalogs": [ { "description": "My Restaurants", "fields": [ { "name": "id", "type": "string" }, { "name": "Name", "type": "string" }, { "name": "City", "type": "string" }, { "name": "Cuisine", "type": "string" }, { "name": "Rating", "type": "number" }, { "name": "Loyalty_Program", "type": "boolean" }, { "name": "Created_At", "type": "time" } ], "name": "restaurants", "num_items": 10, "updated_at": "2022-11-02T20:04:06.879+00:00" }, { "description": "My Catalog", "fields": [ { "name": "id", "type": "string" }, { "name": "string_field", "type": "string" }, { "name": "number_field", "type": "number" }, { "name": "boolean_field", "type": "boolean" }, { "name": "time_field", "type": "time" }, ], "name": "my_catalog", "num_items": 3, "updated_at": "2022-11-02T09:03:19.967+00:00" }, ], "message": "success" } ``` 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 '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' post: tags: - Catalogs > Catalog Management > Synchronous summary: Create Catalog description: >- > Use this endpoint to create a catalog. To use this endpoint, youll need to generate an API key with the `catalogs.create` permission. ## Rate limit This endpoint has a shared rate limit of 5 requests per minute between all synchronous catalog endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `catalogs` | Required | Array | An array that contains catalog objects. Only one catalog object is allowed for this request. | ### Catalog object parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `name` | Required | String | The name of the catalog that you want to create. | | `description` | Required | String | The description of the catalog that you want to create. | | `fields` | Required | Array | An array of objects where the object contains keys `name` and `type`. | ## Example request ``` curl --location --request POST 'https://rest.iad-03.braze.com/catalogs' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR-REST-API-KEY' \ --data-raw '{ "catalogs": [ { "name": "restaurants", "description": "My Restaurants", "fields": [ { "name": "id", "type": "string" }, { "name": "Name", "type": "string" }, { "name": "City", "type": "string" }, { "name": "Cuisine", "type": "string" }, { "name": "Rating", "type": "number" }, { "name": "Loyalty_Program", "type": "boolean" }, { "name": "Created_At", "type": "time" } ] } ] }' ``` ## Response There are two status code responses for this endpoint: `201` and `400`. ### Example success response The status code `201` could return the following response body. ``` json { "catalogs": [ { "description": "My Restaurants", "fields": [ { "name": "id", "type": "string" }, { "name": "Name", "type": "string" }, { "name": "City", "type": "string" }, { "name": "Cuisine", "type": "string" }, { "name": "Rating", "type": "number" }, { "name": "Loyalty_Program", "type": "boolean" }, { "name": "Created_At", "type": "time" } ], "name": "restaurants", "num_items": 0, "updated_at": "2022-11-02T20:04:06.879+00:00" } ], "message": "success" } ``` ### Example error response The status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. ``` json { "errors": [ { "id": "catalog-name-already-exists", "message": "A catalog with that name already exists", "parameters": [ "name" ], "parameter_values": [ "restaurants" ] } ], "message": "Invalid Request" } ``` ## Troubleshooting The following table lists possible returned errors and their associated troubleshooting steps. | Error | Troubleshooting | | --- | --- | | `catalog-array-invalid` | `catalogs` must be an array of objects. | | `catalog-name-already-exists` | Catalog with that name already exists. | | `catalog-name-too-large` | Character limit for a catalog name is 250. | | `description-too-long` | Character limit for description is 250. | | `field-names-not-unique` | The same field name is referenced twice. | | `field-names-too-large` | Character limit for a field name is 250. | | `id-not-first-column` | The `id` must be the first field in the array. Check that the type is a string. | | `invalid_catalog_name` | Catalog name can only include letters, numbers, hyphens, and underscores. | | `invalid-field-names` | Fields can only include letters, numbers, hyphens, and underscores. | | `invalid-field-types` | Make sure the field types are valid. | | `invalid-fields` | `fields` is not formatted correctly. | | `reached-company-catalogs-limit` | Maximum number of catalogs reached. Contact your Braze account manager for more information. | | `too-many-catalog-atoms` | You can only create one catalog per request. | | `too-many-fields` | Number of fields limit is 30. | requestBody: content: application/json: schema: type: object example: catalogs: - name: restaurants description: My Restaurants fields: - name: id type: string properties: catalogs: type: array items: type: object properties: name: type: string description: type: string fields: type: array items: type: object properties: name: type: string type: 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' /catalogs/{catalog_name}/items: delete: tags: - Catalogs > Catalog Items > Asynchronous summary: Delete Multiple Catalog Items description: >- > Use this endpoint to delete multiple items in your catalog. To use this endpoint, youll need to generate an API key with the `catalogs.delete_items` permission. Each request can support up to 50 items. This endpoint is asynchronous. ## Rate limit This endpoint has a shared rate limit of 100 requests per minute between all asynchronous catalog item endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Path parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `catalog_name` | Required | String | Name of the catalog. | ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `items` | Required | Array | An array that contains item objects. The item objects should contain an `id` referencing the items Braze should delete. Up to 50 item objects are allowed per request. | ## Example request ``` curl --location --request DELETE 'https://rest.iad-03.braze.com/catalogs/restaurants/items' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR-REST-API-KEY' \ --data-raw '{ "items": [ {"id": "restaurant1"}, {"id": "restaurant2"}, {"id": "restaurant3"} ] }' ``` ## Response There are three status code responses for this endpoint: `202`, `400`, and `404`. ### Example success response The status code `202` could return the following response body. ``` json { "message": "success" } ``` ### Example error response The status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. ``` json { "errors": [ { "id": "items-missing-ids", "message": "There are 1 item(s) that do not have ids", "parameters": [], "parameter_values": [] } ], "message": "Invalid Request", } ``` ## Troubleshooting The following table lists possible returned errors and their associated troubleshooting steps. | Error | Troubleshooting | | --- | --- | | `catalog-not-found` | Check that the catalog name is valid. | | `ids-too-large` | Item IDs can't be more than 250 characters. | | `ids-not-unique` | Check that the item IDs are unique in the request. | | `ids-not-strings` | Item IDs must be of type string. | | `items-missing-ids` | There are items that do not have item IDs. Check that each item has an item ID. | | `invalid-ids` | Item IDs can only include letters, numbers, hyphens, and underscores. | | `request-includes-too-many-items` | Your request has too many items. The item limit per request is 50. | parameters: - name: Content-Type in: header schema: type: string example: application/json - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: catalog_name in: path schema: type: string required: true responses: '200': 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' patch: tags: - Catalogs > Catalog Items > Asynchronous summary: Edit Multiple Catalog Items description: >- > Use this endpoint to delete multiple items in your catalog. To use this endpoint, youll need to generate an API key with the `catalogs.delete_items` permission. Each request can support up to 50 items. This endpoint is asynchronous. ## Rate limit This endpoint has a shared rate limit of 100 requests per minute between all asynchronous catalog item endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Path parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `catalog_name` | Required | String | Name of the catalog. | ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `items` | Required | Array | An array that contains item objects. The item objects should contain an `id` referencing the items Braze should delete. Up to 50 item objects are allowed per request. | ## Example request ``` curl --location --request DELETE 'https://rest.iad-03.braze.com/catalogs/restaurants/items' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR-REST-API-KEY' \ --data-raw '{ "items": [ {"id": "restaurant1"}, {"id": "restaurant2"}, {"id": "restaurant3"} ] }' ``` ## Response There are three status code responses for this endpoint: `202`, `400`, and `404`. ### Example success response The status code `202` could return the following response body. ``` json { "message": "success" } ``` ### Example error response The status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. ``` json { "errors": [ { "id": "items-missing-ids", "message": "There are 1 item(s) that do not have ids", "parameters": [], "parameter_values": [] } ], "message": "Invalid Request", } ``` ## Troubleshooting The following table lists possible returned errors and their associated troubleshooting steps. | Error | Troubleshooting | | --- | --- | | `catalog-not-found` | Check that the catalog name is valid. | | `ids-too-large` | Item IDs can't be more than 250 characters. | | `ids-not-unique` | Check that the item IDs are unique in the request. | | `ids-not-strings` | Item IDs must be of type string. | | `items-missing-ids` | There are items that do not have item IDs. Check that each item has an item ID. | | `invalid-ids` | Item IDs can only include letters, numbers, hyphens, and underscores. | | `request-includes-too-many-items` | Your request has too many items. The item limit per request is 50. | requestBody: content: application/json: schema: type: object example: items: - id: restaurant1 properties: items: type: array items: type: object properties: id: 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}} - name: catalog_name in: path schema: type: string required: true responses: '200': 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' post: tags: - Catalogs > Catalog Items > Asynchronous summary: Create Multiple Catalog Items description: >- > Use this endpoint to create multiple items in your catalog. To use this endpoint, youll need to generate an API key with the `catalogs.add_items` permission. Each request can support up to 50 items. This endpoint is asynchronous. ## Rate limit This endpoint has a shared rate limit of 100 requests per minute between all asynchronous catalog item endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Path parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `catalog_name` | Required | String | Name of the catalog. | ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `items` | Required | Array | An array that contains item objects. The item objects should contain all of the fields in the catalog. Up to 50 item objects are allowed per request. | ## Example request ``` curl --location --request POST 'https://rest.iad-03.braze.com/catalogs/restaurants/items' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR-REST-API-KEY' \ --data-raw '{ "items": [ { "id": "restaurant1", "Name": "Restaurant1", "City": "New York", "Cuisine": "American", "Rating": 5, "Loyalty_Program": true, "Created_At": "2022-11-01T09:03:19.967+00:00" }, { "id": "restaurant2", "Name": "Restaurant2", "City": "New York", "Cuisine": "American", "Rating": 10, "Loyalty_Program": true, "Created_At": "2022-11-02T09:03:19.967+00:00" }, { "id": "restaurant3", "Name": "Restaurant3", "City": "New York", "Cuisine": "American", "Rating": 3, "Loyalty_Program": false, "Created_At": "2022-11-03T09:03:19.967+00:00" } ] }' ``` ## Response There are three status code responses for this endpoint: `202`, `400`, and `404`. ### Example success response The status code `202` could return the following response body. ``` json { "message": "success" } ``` ### Example error response The status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. ``` json { "errors": [ { "id": "fields-do-not-match", "message": "Fields do not match with fields on the catalog", "parameters": [ "id" ], "parameter_values": [ "restaurant2" ] } ], "message": "Invalid Request" } ``` ## Troubleshooting The following table lists possible returned errors and their associated troubleshooting steps. | Error | Troubleshooting | | --- | --- | | `catalog-not-found` | Check that the catalog name is valid. | | `ids-not-strings` | Item IDs must be of type string. | | `ids-not-unique` | Item IDs must be unique in the request. | | `ids-too-large` | Item IDs can't be more than 250 characters. | | `invalid-ids` | Item IDs can only include letters, numbers, hyphens, and underscores. | | `invalid-fields` | Confirm that the fields in the request exist in the catalog. | | `invalid-keys-in-value-object` | Item object keys can't include `.` or `$`. | | `item-array-invalid` | `items` must be an array of objects. | | `items-missing-ids` | There are items that do not have item IDs. Check that each item has an item ID. | | `items-too-large` | Item values can't exceed 5,000 characters. | | `request-includes-too-many-items` | Your request has too many items. The item limit per request is 50. | | `too-deep-nesting-in-value-object` | Item objects can't have more than 50 levels of nesting. | | `unable-to-coerce-value` | Item types can't be converted. | requestBody: content: application/json: schema: type: object example: items: - id: restaurant1 Name: Restaurant1 City: New York Cuisine: American Rating: 5 Loyalty_Program: true Created_At: '2022-11-01T09:03:19.967+00:00' properties: items: 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}} - name: catalog_name in: path schema: type: string required: true 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' put: tags: - Catalogs > Catalog Items > Asynchronous summary: Update Catalog Item description: >- > Use this endpoint to send Canvas messages via API-triggered delivery. To use this endpoint, you'll need to generate an API key with the `catalogs.replace_item` permission. API-triggered Delivery allows you to store message content in the Braze dashboard while dictating when a message is sent, and to whom via your API. Note that to send messages with this endpoint, you must have a [Canvas ID](https://www.braze.com/docs/api/identifier_types/#canvas-api-identifier), created when you build a Canvas. ## Rate limit This endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog item endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `catalog_name` | Required | String | Name of the catalog. | | `item_id` | Required | String | The ID of the catalog item. | ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `items` | Required | Array | An array that contains item objects. The item objects should contain fields that exist in the catalog except for the `id` field. Only one item object is allowed per request. | ## Example request ## Response There are three status code responses for this endpoint: `200`, `400`, and `404`. ### Example success response The status code `200` could return the following response body. ``` json { "message": "success" } ``` ### Example error response The status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. ``` json { "errors": [ { "id": "invalid-fields", "message": "Some of the fields given do not exist in the catalog", "parameters": [ "id" ], "parameter_values": [ "restaurant1" ] } ], "message": "Invalid Request" } ``` ## Troubleshooting The following table lists possible returned errors and their associated troubleshooting steps. | Error | Troubleshooting | | --- | --- | | `catalog_not_found` | Check that the catalog name is valid. | | `ids_not_string` | Confirm that each item ID is a string. | | `ids_not_unique` | Check that each item ID is unique. | | `ids_too_large` | Character limit for each item ID is 250 characters. | | `item_array_invalid` | `items` must be an array of objects. | | `items_missing_ids` | Confirm that each item has an ID. | | `items_too_large` | Item values can't exceed 5,000 characters. | | `invalid_ids` | Supported characters for item ID names are letters, numbers, hyphens, and underscores. | | `invalid_fields` | Confirm that the fields in the request exist in the catalog. | | `invalid_keys_in_value_object` | Item object keys can't include `.` or `$`. | | `too_deep_nesting_in_value_object` | Item objects can't have more than 50 levels of nesting. | `request_includes_too_many_items` | Your request has too many items. The item limit per request is 50. | | `unable_to_coerce_value` | Item types can't be converted. | requestBody: content: application/json: schema: type: object example: items: - Name: Restaurant Loyalty_Program: false Location: Latitude: 33.6112 Longitude: -117.8711 Open_Time: '2021-09-03T09:03:19.967+00:00' properties: items: 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}} - name: catalog_name in: path schema: type: string required: true responses: '200': 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' get: tags: - Catalogs > Catalog Items > Synchronous summary: List Multiple Catalog Item Details description: >- > Use this endpoint to return multiple catalog items and their content. To use this endpoint, youll need to generate an API key with the `catalogs.get_items` permission. ## Rate limit This endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog item endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Path parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `catalog_name` | Required | String | Name of the catalog. | ## Query parameters Note that each call to this endpoint will return 50 items. For a catalog with more than 50 items, use the `Link` header to retrieve the data on the next page as shown in the following example response. | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `cursor` | Optional | String | Determines the pagination of the catalog items. | ## Example requests ### Without cursor ``` curl --location --request GET 'https://rest.iad-03.braze.com/catalogs/restaurants/items' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR-REST-API-KEY' ``` ### With cursor ``` curl --location --request GET 'https://rest.iad-03.braze.com/catalogs/restaurants/items?cursor=c2tpcDow' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR-REST-API-KEY' ``` ## Response There are three status code responses for this endpoint: `200`, `400`, and `404`. ### Example success response The status code `200` could return the following response header and body. {% alert note %} The `Link` header won't exist if the catalog has less than or equal to 50 items. For calls without a cursor, `prev` will not show. When looking at the last page of items, `next` will not show. {% endalert %} ``` Link: ; rel="prev",; rel="next" ``` ``` json { "items": [ { "id": "restaurant1", "Name": "Restaurant1", "City": "New York", "Cuisine": "American", "Rating": 5, "Loyalty_Program": true, "Open_Time": "2022-11-02T09:03:19.967Z" }, { "id": "restaurant2", "Name": "Restaurant2", "City": "New York", "Cuisine": "American", "Rating": 10, "Loyalty_Program": true, "Open_Time": "2022-11-02T09:03:19.967Z" }, { "id": "restaurant3", "Name": "Restaurant3", "City": "New York", "Cuisine": "American", "Rating": 5, "Loyalty_Program": false, "Open_Time": "2022-11-02T09:03:19.967Z" } ], "message": "success" } ``` ### Example error response The status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. ``` json { "errors": [ { "id": "invalid-cursor", "message": "'cursor' is not valid", "parameters": [ "cursor" ], "parameter_values": [ "bad-cursor" ] } ], "message": "Invalid Request" } ``` ## Troubleshooting The following table lists possible returned errors and their associated troubleshooting steps. | Error | Troubleshooting | | --- | --- | | `catalog-not-found` | Check that the catalog name is valid. | | `invalid-cursor` | Check that your `cursor` is valid. | parameters: - name: Content-Type in: header schema: type: string example: application/json - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: catalog_name in: path schema: type: string required: true responses: '200': 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' /catalogs/{catalog_name}/items/{item_id}: delete: tags: - Catalogs > Catalog Items > Synchronous summary: Delete a Catalog Item description: >- > Use this endpoint to delete an item in your catalog. To use this endpoint, youll need to generate an API key with the `catalogs.delete_item` permission. ## Rate limit This endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog item endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Path parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `catalog_name` | Required | String | Name of the catalog. | | `item_id` | Required | String | The ID of the catalog item. | ## Request parameters There is no request body for this endpoint. ## Example request ``` curl --location --request DELETE 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR-REST-API-KEY' ``` ## Response There are three status code responses for this endpoint: `202`, `400`, and `404`. ### Example success response The status code `202` could return the following response body. ``` json { "message": "success" } ``` ### Example error response The status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. ``` json { "errors": [ { "id": "item-not-found", "message": "Could not find item", "parameters": [ "item_id" ], "parameter_values": [ "restaurant34" ] } ], "message": "Invalid Request" } ``` ## Troubleshooting The following table lists possible returned errors and their associated troubleshooting steps. | Error | Troubleshooting | | --- | --- | | `arbitrary-error` | An arbitrary error occurred. Please try again or contact [Support](https://www.braze.com/docs/support_contact/). | | `catalog-not-found` | Check that the catalog name is valid. | | `item-not-found` | Check that the item to be deleted exists in your catalog. | parameters: - name: Content-Type in: header schema: type: string example: application/json - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: catalog_name in: path schema: type: string required: true - name: item_id in: path schema: type: string required: true responses: '200': 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' get: tags: - Catalogs > Catalog Items > Synchronous summary: List Catalog Item Details description: >- > Use this endpoint to return a catalog item and its content. To use this endpoint, youll need to generate an API key with the `catalogs.get_item` permission. ## Rate limit This endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog item endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Path parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `catalog_name` | Required | String | Name of the catalog. | | `item_id` | Required | String | The ID of the catalog item. | ## Request parameters There is no request body for this endpoint. ## Example request ``` curl --location --request GET 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR-REST-API-KEY' ``` ## Response There are two status code responses for this endpoint: `200` and `404`. ### Example success response The status code `200` could return the following response body. ``` json { "items": [ { "id": "restaurant3", "Name": "Restaurant1", "City": "New York", "Cuisine": "American", "Rating": 5, "Loyalty_Program": true, "Open_Time": "2022-11-01T09:03:19.967Z" } ], "message": "success" } ``` ### Example error response The status code `404` could return the following response. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. ``` json { "errors": [ { "id": "item-not-found", "message": "Could not find item", "parameters": [ "item_id" ], "parameter_values": [ "restaurant34" ] } ], "message": "Invalid Request" } ``` ## Troubleshooting The following table lists possible returned errors and their associated troubleshooting steps, if applicable. | Error | Troubleshooting | | --- | --- | | `catalog-not-found` | Check that the catalog name is valid. | | `item-not-found` | Check that the item is in the catalog. | parameters: - name: Content-Type in: header schema: type: string example: application/json - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: catalog_name in: path schema: type: string required: true - name: item_id in: path schema: type: string required: true responses: '200': 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' patch: tags: - Catalogs > Catalog Items > Synchronous summary: Edit Catalog Items description: >- > Use this endpoint to edit an item in your catalog. To use this endpoint, youll need to generate an API key with the `catalogs.update_item` permission. ## Rate Limit This endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog item endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Path parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `catalog_name` | Required | String | Name of the catalog. | | `item_id` | Required | String | The ID of the catalog item. | ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `items` | Required | Array | An array that contains item objects. The item objects should contain fields that exist in the catalog except for the `id` field. Only one item object is allowed per request. | ## Example request ``` curl --location --request PATCH 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR-REST-API-KEY' \ --data-raw '{ "items": [ { "Name": "Restaurant", "Loyalty_Program": false, "Open_Time": "2021-09-03T09:03:19.967+00:00" } ] }' ``` ## Response There are three status code responses for this endpoint: `200`, `400`, and `404`. ### Example success response The status code `200` could return the following response body. ``` json { "message": "success" } ``` ### Example error response The status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. ``` json { "errors": [ { "id": "invalid-fields", "message": "Some of the fields given do not exist in the catalog", "parameters": [ "id" ], "parameter_values": [ "restaurant1" ] } ], "message": "Invalid Request" } ``` ## Troubleshooting The following table lists possible returned errors and their associated troubleshooting steps. | Error | Troubleshooting | | --- | --- | | `arbitrary-error` | An arbitrary error occurred. Please try again or contact [Support](https://www.braze.com/docs/support_contact/). | | `catalog-not-found` | Check that the catalog name is valid. | | `filtered-set-field-too-long` | The field value is being used in a filtered set that exceeds the character limit for an item. | | `id-in-body` | An item ID already exists in the catalog. | | `ids-too-large` | Character limit for each item ID is 250 characters. | | `invalid-ids` | Supported characters for item ID names are letters, numbers, hyphens, and underscores. | | `invalid-fields` | Confirm that the fields in the request exist in the catalog. | | `invalid-keys-in-value-object` | Item object keys can't include `.` or `$`. | | `item-not-found` | Check that the item is in the catalog. | | `item-array-invalid` | `items` must be an array of objects. | | `items-too-large` | Character limit for each item is 5,000 characters. | | `request-includes-too-many-items` | You can only edit one catalog item per request. | | `too-deep-nesting-in-value-object` | Item objects can't have more than 50 levels of nesting. | | `unable-to-coerce-value` | Item types can't be converted. | requestBody: content: application/json: schema: type: object example: items: - Name: Restaurant Loyalty_Program: false Open_Time: '2021-09-03T09:03:19.967+00:00' properties: items: 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}} - name: catalog_name in: path schema: type: string required: true - name: item_id in: path schema: type: string required: true responses: '200': 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' post: tags: - Catalogs > Catalog Items > Synchronous summary: Create Catalog Item description: >- > Use this endpoint to create an item in your catalog. To use this endpoint, youll need to generate an API key with the `catalogs.create_item` permission. ## Rate limit This endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog item endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Path parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `catalog_name` | Required | String | Name of the catalog. | | `item_id` | Required | String | The ID of the catalog item. | ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `items` | Required | Array | An array that contains item objects. The item objects should contain all of the fields in the catalog except for the `id` field. Only one item object is allowed per request. | ## Example Request ``` curl --location --request POST 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR-REST-API-KEY' \ --data-raw '{ "items": [ { "Name": "Restaurant1", "City": "New York", "Cuisine": "American", "Rating": 5, "Loyalty_Program": true, "Created_At": "2022-11-01T09:03:19.967+00:00" } ] }' ``` ## Response There are three status code responses for this endpoint: `201`, `400`, and `404`. ### Example success response The status code `201` could return the following response body. ``` json { "message": "success" } ``` ### Example error response The status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. ``` json { "errors": [ { "id": "fields-do-not-match", "message": "Fields do not match with fields on the catalog", "parameters": [ "id" ], "parameter_values": [ "restaurant2" ] } ], "message": "Invalid Request" } ``` ## Troubleshooting The following table lists possible returned errors and their associated troubleshooting steps. | Error | Troubleshooting | | --- | --- | | `already-reached-catalog-item-limit` | Maximum number of catalogs reached. Contact your Braze account manager for more information. | | `already-reached-company-item-limit` | Maximum number of catalog items reached. Contact your Braze account manager for more information. | | `arbitrary-error` | An arbitrary error occurred. Please try again or contact [Support](https://www.braze.com/docs/support_contact/). | | `catalog-not-found` | Check that the catalog name is valid. | | `filtered-set-field-too-long` | The field value is being used in a filtered set that exceeds the character limit for an item. | | `id-in-body` | Remove any item IDs in the request body. | | `ids-too-large` | Character limit for each item ID is 250 characters. | | `invalid-ids` | Supported characters for item ID names are letters, numbers, hyphens, and underscores. | | `invalid-fields` | Confirm that the fields in the request exist in the catalog. | | `invalid-keys-in-value-object` | Item object keys can't include `.` or `$`. | | `item-already-exists` | The item already exists in the catalog. | | `item-array-invalid` | `items` must be an array of objects. | | `items-too-large` | Character limit for each item is 5,000 characters. | | `request-includes-too-many-items` | You can only create one catalog item per request. | | `too-deep-nesting-in-value-object` | Item objects can't have more than 50 levels of nesting. | | `unable-to-coerce-value` | Item types can't be converted. | requestBody: content: application/json: schema: type: object example: items: - Name: Restaurant1 City: New York Cuisine: American Rating: 5 Loyalty_Program: true Created_At: '2022-11-01T09:03:19.967+00:00' properties: items: 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}} - name: catalog_name in: path schema: type: string required: true - name: item_id in: path schema: type: string required: true 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' put: tags: - Catalogs > Catalog Items > Synchronous summary: Update Catalog Item description: >- > Use this endpoint to update an item in your catalog. To use this endpoint, you'll need to generate an API key with the `catalogs.replace_item` permission. If the `item_id` isn't found, this endpoint will create the item. This endpoint is synchronous. ## Rate limit This endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog item endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Path parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `catalog_name` | Required | String | Name of the catalog. | | `item_id` | Required | String | The ID of the catalog item. | ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `items` | Required | Array | An array that contains item objects. The item objects should contain fields that exist in the catalog except for the `id` field. Only one item object is allowed per request. | ## Example request ``` curl --location --request PUT 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR-REST-API-KEY' \ --data-raw '{ "items": [ { "Name": "Restaurant", "Loyalty_Program": false, "Location": { "Latitude": 33.6112, "Longitude": -117.8711 }, "Open_Time": "2021-09-03T09:03:19.967+00:00" } ] }' ``` ## Response There are three status code responses for this endpoint: `200`, `400`, and `404`. ### Example success response The status code `200` could return the following response body. ``` json { "message": "success" } ``` ### Example error response The status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. ``` json { "errors": [ { "id": "invalid-fields", "message": "Some of the fields given do not exist in the catalog", "parameters": [ "id" ], "parameter_values": [ "restaurant1" ] } ], "message": "Invalid Request" } ``` ## Troubleshooting The following table lists possible returned errors and their associated troubleshooting steps. | Error | Troubleshooting | | --- | --- | | `already_reached_catalog_item_limit` | Maximum number of catalogs reached. Contact your Braze account manager for more information. | | `already_reached_company_item_limit` | Maximum number of items reached. Contact your Braze account manager for more information. | | `arbitrary_error` | An arbitrary error occurred. Please try again or contact [Support](https://www.braze.com/docs/support_contact/). | | `catalog_not_found` | Check that the catalog name is valid. | | `filtered-set-field-too-long` | The field value is being used in a filtered set that exceeds the character limit for an item. | | `id_in_body` | Remove any item IDs in the request body. | | `ids_too_large` | Character limit for each item ID is 250 characters. | | `invalid_ids` | Supported characters for item ID names are letters, numbers, hyphens, and underscores. | | `invalid_fields` | Confirm that the fields in the request exist in the catalog. | | `invalid_keys_in_value_object` | Item object keys can't include `.` or `$`. | | `item_already_exists` | The item already exists in the catalog. | | `item_array_invalid` | `items` must be an array of objects. | | `items_too_large` | Item values can't exceed 5,000 characters. | | `request_includes_too_many_items` | Your request has too many items. The item limit per request is 50. | | `too_deep_nesting_in_value_object` | Item objects can't have more than 50 levels of nesting. | | `unable_to_coerce_value` | Item types can't be converted. | requestBody: content: application/json: schema: type: object example: items: - Name: Restaurant Loyalty_Program: false Location: Latitude: 33.6112 Longitude: -117.8711 Open_Time: '2021-09-03T09:03:19.967+00:00' properties: items: 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}} - name: catalog_name in: path schema: type: string required: true - name: item_id in: path schema: type: string required: true responses: '200': 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' /email/hard_bounces: get: tags: - Email Lists & Addresses summary: Query Hard Bounced Emails description: >- > Use this endpoint to pull a list of email addresses that have hard bounced your email messages within a certain time frame. To use this endpoint, youll need to generate an API key with the `email.hard_bounces` permission. **Note:** You must provide an `end_date`, as well as either an `email` or a `start_date`. If you provide all three, `start_date`, `end_date`, and an `email`, we prioritize the emails given and disregard the date range. If your date range has more than `limit` number of hard bounces, you will need to make multiple API calls, each time increasing the `offset` until a call returns either fewer than `limit` or zero results. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Example request ``` curl --location --request GET 'https://rest.iad-01.braze.com/email/hard_bounces?start_date=2019-01-01&end_date=2019-02-01&limit=100&offset=1&email=example@braze.com' \ --header 'Authorization: Bearer YOUR-API-KEY-HERE' ``` ## Response Entries are listed in descending order. ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "emails": [ { "email": "example1@braze.com", "hard_bounced_at": "2016-08-25 15:24:32 +0000" }, { "email": "example2@braze.com", "hard_bounced_at": "2016-08-24 17:41:58 +0000" }, { "email": "example3@braze.com", "hard_bounced_at": "2016-08-24 12:01:13 +0000" } ], "message": "success" } ``` parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: start_date in: query schema: type: string description: > (Optional*) String in YYYY-MM-DD format Start date of the range to retrieve hard bounces, must be earlier than `end_date`. This is treated as midnight in UTC time by the API. *You must provide either an `email` or a `start_date`, and an `end_date`. example: '2019-01-01' - name: end_date in: query schema: type: string description: >- (Optional*) String in YYYY-MM-DD format String in YYYY-MM-DD format. End date of the range to retrieve hard bounces. This is treated as midnight in UTC time by the API. *You must provide either an `email` or a `start_date`, and an `end_date`. example: '2019-02-01' - name: limit in: query schema: type: integer description: >- (Optional) Integer Optional field to limit the number of results returned. Defaults to 100, maximum is 500. example: 100 - name: offset in: query schema: type: integer description: |- (Optional) Integer Optional beginning point in the list to retrieve from. example: 1 - name: email in: query schema: type: string description: >- (Optional*) String If provided, we will return whether or not the user has hard bounced. *You must provide either an `email` or a `start_date`, and an `end_date`. example: example@braze.com responses: '200': 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' /email/unsubscribes: get: tags: - Email Lists & Addresses summary: Query List of Unsubscribed Email Addresses description: >- > Use this endpoint to return emails that have unsubscribed during the time period from `start_date` to `end_date`. You can use this endpoint to set up a bi-directional sync between Braze and other email systems or your own database. To use this endpoint, youll need to generate an API key with the `email.unsubscribe` permission. **Note:** You must provide an `end_date`, as well as either an `email` or a `start_date`. If your date range has more than `limit` number of unsubscribes, you will need to make multiple API calls, each time increasing the `offset` until a call returns either fewer than `limit` or zero results. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Example request ``` curl --location --request GET 'https://rest.iad-01.braze.com/email/unsubscribes?start_date=2020-01-01&end_date=2020-02-01&limit=1&offset=1&sort_direction=desc&email=example@braze.com' \ --header 'Authorization: Bearer YOUR-API-KEY-HERE' ``` ## Response Entries are listed in descending order. ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "emails": [ { "email": "example1@braze.com", "unsubscribed_at": "2016-08-25 15:24:32 +0000" }, { "email": "example2@braze.com", "unsubscribed_at": "2016-08-24 17:41:58 +0000" }, { "email": "example3@braze.com", "unsubscribed_at": "2016-08-24 12:01:13 +0000" } ], "message": "success" } ``` parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: start_date in: query schema: type: string description: >- (Optional*) String in YYYY-MM-DD format Start date of the range to retrieve unsubscribes, must be earlier than end_date. This is treated as midnight in UTC time by the API. example: '2020-01-01' - name: end_date in: query schema: type: string description: >- (Optional*) String in YYYY-MM-DD format End date of the range to retrieve unsubscribes. This is treated as midnight in UTC time by the API. example: '2020-02-01' - name: limit in: query schema: type: integer description: >- (Optional) Integer Optional field to limit the number of results returned. Limit must be greater than 1. Defaults to 100, maximum is 500. example: 1 - name: offset in: query schema: type: integer description: |- (Optional) Integer Optional beginning point in the list to retrieve from. example: 1 - name: sort_direction in: query schema: type: string description: >- (Optional) String Pass in the value `asc` to sort unsubscribes from oldest to newest. Pass in `desc` to sort from newest to oldest. If sort_direction is not included, the default order is newest to oldest. example: desc - name: email in: query schema: type: string description: >- (Optional*) String If provided, we will return whether or not the user has unsubscribed. example: example@braze.com responses: '200': 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' /email/status: post: tags: - Email Lists & Addresses summary: Change Email Subscription Status description: >- > Use this endpoint to set the email subscription state for your users. Users can be `opted_in`, `unsubscribed`, or `subscribed` (not specifically opted in or out). You can set the email subscription state for an email address that is not yet associated with any of your users within Braze. When that email address is subsequently associated with a user, the email subscription state that you uploaded will be automatically set. To use this endpoint, youll need to generate an API key with the `email.status` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `email` | Required | String or array | String email address to modify, or an array of up to 50 email addresses to modify. | | `subscription_state` | Required | String | Either subscribed, unsubscribed, or opted_in. | requestBody: content: application/json: schema: type: object example: email: example@braze.com subscription_state: subscribed properties: email: type: string format: email subscription_state: 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' /email/bounce/remove: post: tags: - Email Lists & Addresses summary: Remove Hard Bounced Emails description: >- > Use this endpoint to remove email addresses from your Braze bounce list. We will also remove them from the bounce list maintained by your email provider. To use this endpoint, youll need to generate an API key with the `email.bounce.remove` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `email` | Required | String or array | String email address to modify, or an array of up to 50 email addresses to modify. | requestBody: content: application/json: schema: type: object example: email: example@braze.com properties: email: type: string format: email 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' /email/spam/remove: post: tags: - Email Lists & Addresses summary: Remove Email Addresses from Spam List description: >- > Use this endpoint to remove email addresses from your Braze spam list. We will also remove them from the spam list maintained by your email provider. To use this endpoint, youll need to generate an API key with the `email.spam.remove` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `email` | Required | String or array | String email address to modify, or an array of up to 50 email addresses to modify. | requestBody: content: application/json: schema: type: object example: email: example@braze.com properties: email: type: string format: email 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' /email/blocklist: post: tags: - Email Lists & Addresses summary: Blocklist Email Addresses description: >- > Use this endpoint to unsubscribe a user from email and mark them as hard bounced. To use this endpoint, youll need to generate an API key with the `email.blacklist` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `email` | Required | String or array | String email address to blacklist, or an array of up to 50 email addresses to blocklist. | requestBody: content: application/json: schema: type: object example: email: - blocklist_email1 - blocklist_email2 properties: email: type: array items: 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' /email/blacklist: post: tags: - Email Lists & Addresses summary: Blacklist Email Addresses description: >- > Use this endpoint to unsubscribe a user from email and mark them as hard bounced. To use this endpoint, youll need to generate an API key with the `email.blacklist` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `email` | Required | String or array | String email address to blacklist, or an array of up to 50 email addresses to blocklist. | requestBody: content: application/json: schema: type: object example: email: - blacklist_email1 - blacklist_email2 properties: email: type: array items: 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' /campaigns/data_series: get: tags: - Export > Campaign summary: Export Campaign Analytics description: >- > Use this endpoint to retrieve a daily series of various stats for a campaign over time. Data returned includes how many messages were sent, opened, clicked, or converted by messaging channel. To use this endpoint, youll need to generate an API key with the `campaigns.data_series` permission. Note: If you are using our [older navigation](https://www.braze.com/docs/navigation), `campaign_id` can be found at **Developer Console > API Settings**. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Responses ### Multichannel response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "message": (required, string) the status of the export, returns 'success' when completed without errors, "data" : [ { "time" : (string) date as ISO 8601 date, "messages" : { "ios_push" : [ { "variation_name": "iOS_Push", "sent" : (int), "direct_opens" : (int), "total_opens" : (int), "bounces" : (int), "body_clicks" : (int) "revenue": 0, "unique_recipients": 1, "conversions": 0, "conversions_by_send_time": 0, "conversions1": 0, "conversions1_by_send_time": 0, "conversions2": 0, "conversions2_by_send_time": 0, "conversions3": 0, "conversions3_by_send_time": 0, "carousel_slide_[NUM]_[TITLE]_click": (optional, int), "notif_button_[NUM]_[TITLE]_click": (optional, int) } ], "android_push" : [ { "sent" : (int), "direct_opens" : (int), "total_opens" : (int), "bounces" : (int), "body_clicks" : (int) } ], "webhook": [ { "sent": (int), "errors": (int) } ], "email" : [ { "sent": (int), "opens": (int), "unique_opens": (int), "clicks": (int), "unique_clicks": (int), "unsubscribes": (int), "bounces": (int), "delivered": (int), "reported_spam": (int) } ], "sms" : [ { "sent": (int), "delivered": (int), "undelivered": (int), "delivery_failed": (int) } ] }, "conversions_by_send_time": (optional, int), "conversions1_by_send_time": (optional, int), "conversions2_by_send_time": (optional, int), "conversions3_by_send_time": (optional, int), "conversions": (int), "conversions1": (optional, int), "conversions2": (optional, int), "conversions3": (optional, int), "unique_recipients": (int), "revenue": (optional, float) }, ... ], ... } ``` ### Multivariate response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "data" : [ { "time" : (string) date as ISO 8601 date, "conversions" : (int), "revenue": (float), "conversions_by_send_time": (int), "messages" : { "trigger_in_app_message": [{ "variation_name": (optional, string), "impressions": (int), "clicks": (int), "first_button_clicks": (int), "second_button_clicks": (int), "revenue": (optional, float),, "unique_recipients": (int), "conversions": (optional, int), "conversions_by_send_time": (optional, int), "conversions1": (optional, int), "conversions1_by_send_time": (optional, int), "conversions2": (optional, int), "conversions2_by_send_time": (optional, int), "conversions3": (optional, int), "conversions3_by_send_time": (optional, int) }, { "variation_name": (optional, string), "impressions": (int), "clicks": (int), "first_button_clicks": (int), "second_button_clicks": (int), "revenue": (optional, float),, "unique_recipients": (int), "conversions": (optional, int), "conversions_by_send_time": (optional, int), "conversions1": (optional, int), "conversions1_by_send_time": (optional, int), "conversions2": (optional, int), "conversions2_by_send_time": (optional, int), "conversions3": (optional, int). "conversions3_by_send_time": (optional, int) }, { "variation_name": (optional, string), "revenue": (optional, float),, "unique_recipients": (int), "conversions": (optional, int), "conversions_by_send_time": (optional, int), "conversions1": (optional, int), "conversions1_by_send_time": (optional, int), "conversions2": (optional, int), "conversions2_by_send_time": (optional, int), "conversions3": (optional, int), "conversions3_by_send_time": (optional, int), "enrolled": (optional, int) }] }, "conversions_by_send_time": (optional, int), "conversions1_by_send_time": (optional, int), "conversions2_by_send_time": (optional, int), "conversions3_by_send_time": (optional, int), "conversions": (optional, int, "conversions1": (optional, int), "conversions2": (optional, int), "conversions3": (optional, int), "unique_recipients": (int), "revenue": (optional, float) }], ... } ``` Possible message types are `email`, `in_app_message`, `webhook`, `android_push`, ios_push, `kindle_push`, `web_push`. All push message types will have the same statistics shown for `android_push`. > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: campaign_id in: query schema: type: string description: >- (Required) String See [campaign API identifier](https://www.braze.com/docs/api/identifier_types/). The `campaign_id` for API campaigns can be found at **Settings > Setup and Testing > API Keys** and the **Campaign Details** page within your dashboard, or you can use the [List campaigns endpoint](https://www.braze.com/docs/api/endpoints/export/campaigns/get_campaigns/). example: '{{campaign_identifier}}' - name: length in: query schema: type: integer description: >- (Required) Integer Max number of days before `ending_at` to include in the returned series. Must be between 1 and 100 (inclusive). example: 7 - name: ending_at in: query schema: type: string description: >- (Optional) Datetime ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string) Date on which the data series should end. Defaults to time of the request. example: '2020-06-28T23:59:59-5:00' responses: '200': 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' /campaigns/details: get: tags: - Export > Campaign summary: Export Campaign Details description: >- > Use this endpoint to retrieve relevant information on a specified campaign, which can be identified by the `campaign_id`. To use this endpoint, youll need to generate an API key with the `campaign.details` permission. If you want to retrieve Canvas data, refer to the [Canvas Details](https://www.braze.com/docs/api/endpoints/export/canvas/get_canvas_details/) endpoint. Note: If you are using our [older navigation](https://www.braze.com/docs/navigation), `campaign_id` can be found at **Developer Console** > **API Settings** ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Responses ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "message": (required, string) the status of the export, returns 'success' when completed without errors, "created_at" : (string) the date created as ISO 8601 date, "updated_at" : (string) the date last updated as ISO 8601 date, "archived": (boolean) whether this campaign is archived, "draft": (boolean) whether this campaign is a draft, "name" : (string) the campaign name, "description" : (string) the campaign description, "schedule_type" : (string) the type of scheduling action, "channels" : (array) the list of channels to send via, "first_sent" : (string) the date and hour of first sent as ISO 8601 date, "last_sent" : (string) the date and hour of last sent as ISO 8601 date, "tags" : (array) the tag names associated with the campaign, "messages": { "message_variation_id": (string) { // <=This is the actual id "channel": (string) the channel type of the message, must be either email, ios_push, webhook, content_card, in-app_message, or sms, "name": (string) the name of the message in the dashboard (eg., "Variation 1") ... channel-specific fields for this message, see the following messages section ... } }, "conversion_behaviors": (array) the conversion event behaviors assigned to the campaign, see the following conversions behavior section. } ``` ### Messages The `messages` response will contain information about each message. The following includes example message responses for each channel: #### Push channels ``` json { "channel": (string) description of the channel, such as "ios_push" or "android_push" "alert": (string) alert body text, "extras": (hash) any key value pairs provided } ``` #### Email channel ``` json { "channel": "email", "subject": (string) subject, "body": (string) HTML body, "from": (string) from address and display name, "reply_to": (string) reply-to for message, if different than "from" address, "title": (string) name of the email, "extras": (hash) any key value pairs provided } ``` #### In-app message channel ``` json { "type": (string) description of in-app message type, such as "survey", "data": { "pages": [ { "header": { "text":(string) display text for the header of the survey, } "choices": [ { "choice_id": (string) choice identifier, "text": (string) display text, "custom_attribute_key": (string) custom attribute key, "custom_attribute_value": (sting) custom attribute value, "deleted": (boolean) deleted from live campaign, }, ... ] } ] } } ``` #### Content Card channel ``` json { "channel": "content_cards", "name": (string) name of variant, "extras": (hash) any key value pairs provided; only present if at least one key-value pair has been set } ``` #### Webhook channel ``` json { "channel": "webhook", "url": (string) url for webhook, "body": (string) payload body, "type": (string) body content type, "headers": (hash) specified request headers, "method": (string) HTTP method (e.g., "POST" or "GET"), } ``` #### SMS channel ``` json { "channel": "sms", "body": (string) payload body, "from": (string) list of numbers associated with the subscription group, "subscription_group_id": (string) API id of the subscription group targeted in the SMS message } ``` #### Control Messages ``` json { "channel": (string) description of the channel that the control is for, "type": "control" } ``` ### Conversion Behaviors The `conversion_behaviors` array will contain information about each conversion event behavior set for the campaign. These behaviors are in order as set by the campaign. For example, Conversion Event A will be the first item in the array, Conversion Event B will be second, etc. The following lists example conversion event behavior responses: #### Clicks email ``` json { "type": "Clicks Email", "window": (integer) number of seconds during which the user can convert on this event, i.e. - 86400, which is 24 hours } ``` #### Opens email ``` json { "type": "Opens Email", "window": (integer) number of seconds during which the user can convert on this event, i.e. - 86400, which is 24 hours } ``` #### Makes purchase (any purchase) ``` json { "type": "Makes Any Purchase", "window": (integer) number of seconds during which the user can convert on this event, i.e. - 86400, which is 24 hours } ``` #### Makes purchase (specific product) ``` json { "type": "Makes Specific Purchase", "window": (integer) number of seconds during which the user can convert on this event, i.e. - 86400, which is 24 hours, "product": (string) name of the product, i.e. - "Feline Body Armor" } ``` #### Performs custom event ``` json { "type": "Performs Custom Event", "window": (integer) number of seconds during which the user can convert on this event, i.e. - 86400, which is 24 hours, "custom_event_name": (string) name of the event, i.e. - "Used Feline Body Armor" } ``` #### Upgrades app ``` json { "type": "Upgrades App", "window": (integer) number of seconds during which the user can convert on this event, i.e. - 86400, which is 24 hours, "app_ids": (array|null) array of app ids, i.e. - ["12345", "67890"], or `null` if "Track sessions for any app" is selected in the UI } ``` #### Uses app ``` json { "type": "Starts Session", "window": (integer) number of seconds during which the user can convert on this event, i.e. - 86400, which is 24 hours, "app_ids": (array|null) array of app ids, i.e. - ["12345", "67890"], or `null` if "Track sessions for any app" is selected in the UI } ``` > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: campaign_id in: query schema: type: string description: >- (Required) String See [campaign API identifier](https://www.braze.com/docs/api/identifier_types/). The `campaign_id` for API campaigns can be found on the **Settings > Setup and Testing > API Keys** and the campaign details page within your dashboard, or you can use the [Campaign List Endpoint](https://www.braze.com/docs/api/endpoints/export/campaigns/get_campaign_analytics/#campaign-list-endpoint). example: '{{campaign_identifier}}' responses: '200': 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' /campaigns/list: get: tags: - Export > Campaign summary: Export Campaign List description: >- > Use this endpoint to export a list of campaigns, each of which will include its name, campaign API identifier, whether it is an API campaign, and tags associated with the campaign. The campaigns are returned in groups of 100 sorted by time of creation (oldest to newest by default). To use this endpoint, youll need to generate an API key with the `campaigns.list` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Campaign list endpoint API response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "message": (required, string) the status of the export, returns 'success' when completed without errors, "campaigns" : [ { "id" : (string) Campaign API Identifier, "last_edited": (ISO 8601 string) the last edited time for the message "name" : (string) campaign name, "is_api_campaign" : (boolean) whether the campaign is an API Campaign, "tags" : (array) tag names associated with the campaign }, ... ] } ``` > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: page in: query schema: type: integer description: >- (Optional) Integer The page of campaigns to return, defaults to 0 (returns the first set of up to 100). - name: include_archived in: query schema: type: boolean description: |- (Optional) Boolean Whether or not to include archived campaigns, defaults to false. - name: sort_direction in: query schema: type: string description: >- (Optional) String - Sort creation time from newest to oldest: pass in the value `desc`. - Sort creation time from oldest to newest: pass in the value `asc`. If `sort_direction` is not included, the default order is oldest to newest. example: desc - name: last_edit.time[gt] in: query schema: type: string description: >- (Optional) Datetime ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string) Filters the results and only returns campaigns that were edited greater than the time provided till now. Format is `yyyy-MM-DDTHH:mm:ss`. example: '2020-06-28T23:59:59-5:00' responses: '200': 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' /sends/data_series: get: tags: - Export > Campaign summary: Export Send Analytics description: >- > Use this endpoint to retrieve a daily series of various stats for a tracked `send_id`. Braze stores send analytics for 14 days after the send. Campaign conversions will be attributed towards the most recent send id that a given user has received from the campaign. To use this endpoint, youll need to generate an API key with the `sends.data_series` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Response ### Send analytics endpoint API response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "variation_name": (string) variation name, "sent": (int) the number of sends, "delivered": (int) the number of messages successfully delivered, "undelivered": (int) the number of undelivered, "delivery_failed": (int) the number of rejected, "direct_opens": (int) the number of direct opens, "total_opens": (int) the number of total opens, "bounces": (int) the number of bounces, "body_clicks": (int) the number of body clicks, "revenue": (float) the number of dollars of revenue (USD), "unique_recipients": (int) the number of unique recipients, "conversions": (int) the number of conversions, "conversions_by_send_time": (int) the number of conversions, "conversions1": (int, optional) the number of conversions for the second conversion event, "conversions1_by_send_time": (int, optional) the number of conversions for the second conversion event by send time, "conversions2": (int, optional) the number of conversions for the third conversion event, "conversions2_by_send_time": (int, optional) the number of conversions for the third conversion event by send time, "conversions3": (int, optional) the number of conversions for the fourth conversion event, "conversions3_by_send_time": (int, optional) the number of conversions for the fourth conversion event by send time } ] }, "conversions_by_send_time": 0, "conversions1_by_send_time": 0, "conversions2_by_send_time": 0, "conversions3_by_send_time": 0, "conversions": 0, "conversions1": 0, "conversions2": 0, "conversions3": 0, "unique_recipients": 1, "revenue": 0 } ], "message": "success" } ``` > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: campaign_id in: query schema: type: string description: >- (Required) String See [Campaign API identifier](https://www.braze.com/docs/api/identifier_types/). example: '{{campaign_identifier}}' - name: send_id in: query schema: type: string description: >- (Required) String See [Send API identifier](https://www.braze.com/docs/api/identifier_types/). example: '{{send_identifier}}' - name: length in: query schema: type: integer description: >- (Required) Integer Max number of days before `ending_at` to include in the returned series. Must be between 1 and 100 (inclusive). example: 30 - name: ending_at in: query schema: type: string description: >- (Optional) Datetime ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string) Date on which the data series should end. Defaults to time of the request. example: '2014-12-10T23:59:59-05:00' responses: '200': 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' /canvas/data_series: get: tags: - Export > Canvas summary: Export Canvas Data Series Analytics description: >- > Use this endpoint to export time series data for a Canvas. To use this endpoint, youll need to generate an API key with the `canvas.data_series` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "data": { "name": (string) Canvas name, "stats": [ { "time": (string) date as ISO 8601 date, "total_stats": { "revenue": (float), "conversions": (int), "conversions_by_entry_time": (int), "entries": (int) }, "variant_stats": (optional) { "00000000-0000-0000-0000-0000000000000": (API identifier for variant) { "name": (string) name of variant, "revenue": (int), "conversions": (int), "conversions_by_entry_time": (int), "entries": (int) }, ... (more variants) }, "step_stats": (optional) { "00000000-0000-0000-0000-0000000000000": (API identifier for step) { "name": (string) name of step, "revenue": (float), "conversions": (int), "conversions_by_entry_time": (int), "messages": { "email": [ { "sent": (int), "opens": (int), "unique_opens": (int), "clicks": (int), ... (more stats) } ], ... (more channels) } }, ... (more steps) } }, ... (more stats by time) ] }, "message": (required, string) the status of the export, returns 'success' when completed without errors } ``` > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: canvas_id in: query schema: type: string description: >- (Required) String See [Canvas API Identifier](https://www.braze.com/docs/api/identifier_types/). example: '{{canvas_id}}' - name: ending_at in: query schema: type: string description: >- (Required) Datetime ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string) Date on which the data export should end. Defaults to time of the request. example: '2018-05-30T23:59:59-5:00' - name: starting_at in: query schema: type: string description: >- (Optional*) Datetime ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string) Date on which the data export should begin. *Either `length` or `starting_at` is required. example: '2018-05-28T23:59:59-5:00' - name: length in: query schema: type: integer description: >- (Optional*) String Maximum number of days before `ending_at` to include in the returned series. Must be between 1 and 14 (inclusive). *Either `length` or `starting_at` is required. example: 10 - name: include_variant_breakdown in: query schema: type: boolean description: |- (Optional) Boolean Whether or not to include variant stats (defaults to false). example: true - name: include_step_breakdown in: query schema: type: boolean description: |- (Optional) Boolean Whether or not to include step stats (defaults to false). example: true - name: include_deleted_step_data in: query schema: type: boolean description: >- (Optional) Boolean Whether or not to include step stats for deleted steps (defaults to false). example: true responses: '200': 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' /canvas/data_summary: get: tags: - Export > Canvas summary: Export Canvas Data Analytics Summary description: >- > Use this endpoint to export rollups of time series data for a Canvas, providing a concise summary of a Canvas results. To use this endpoint, youll need to generate an API key with the `canvas.data_summary` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "data": { "name": (string) Canvas name, "total_stats": { "revenue": (float), "conversions": (int), "conversions_by_entry_time": (int), "entries": (int) }, "variant_stats": (optional) { "00000000-0000-0000-0000-0000000000000": (API identifier for variant) { "name": (string) name of variant, "revenue": (float), "conversions": (int), "entries": (int) }, ... (more variants) }, "step_stats": (optional) { "00000000-0000-0000-0000-0000000000000": (API identifier for step) { "name": (string) name of step, "revenue": (float), "conversions": (int), "conversions_by_entry_time": (int), "messages": { "android_push": (name of channel) [ { "sent": (int), "opens": (int), "influenced_opens": (int), "bounces": (int) ... (more stats for channel) } ], ... (more channels) } }, ... (more steps) } }, "message": (required, string) the status of the export, returns 'success' when completed without errors } ``` > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://desktop.postman.com/?desktopVersion=9.19.0&userId=16580579&teamId=409325). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: canvas_id in: query schema: type: string description: >- (Required) String See [Canvas API identifier](https://www.braze.com/docs/api/identifier_types/). example: '{{canvas_id}}' - name: ending_at in: query schema: type: string description: >- (Required) Datetime ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string) Date on which the data export should end. Defaults to time of the request example: '2018-05-30T23:59:59-5:00' - name: starting_at in: query schema: type: string description: >- (Optional*) Datetime ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string) Date on which the data export should begin. *Either `length` or `starting_at` is required. example: '2018-05-28T23:59:59-5:00' - name: length in: query schema: type: integer description: >- (Optional*) Integer Max number of days before `ending_at` to include in the returned series. Must be between 1 and 14 (inclusive). *Either `length` or `starting_at` is required. example: 5 - name: include_variant_breakdown in: query schema: type: boolean description: |- (Optional) Boolean Whether or not to include variant stats (defaults to false). example: true - name: include_step_breakdown in: query schema: type: boolean description: |- (Optional) Boolean Whether or not to include step stats (defaults to false). example: true - name: include_deleted_step_data in: query schema: type: boolean description: >- (Optional) Boolean Whether or not to include step stats for deleted steps (defaults to false). example: true responses: '200': 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' /canvas/details: get: tags: - Export > Canvas summary: Export Canvas Details description: >- > Use this endpoint to export metadata about a Canvas, such as the name, time created, current status, and more. To use this endpoint, youll need to generate an API key with the `canvas.details` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Response Note: All Canvas steps have a next_paths field, which is an array of `{name, next_step_id}` data. For full steps and Message steps, the `next_step_ids` field will be present, but will not contain data for other Canvas Flow steps. ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "created_at": (string) date created as ISO 8601 date, "updated_at": (string) date updated as ISO 8601 date, "name": (string) Canvas name, "description": (string) Canvas description, "archived": (boolean) whether this Canvas is archived, "draft": (boolean) whether this Canvas is a draft, "schedule_type": (string) type of scheduling action, "first_entry": (string) date of first entry as ISO 8601 date, "last_entry": (string) date of last entry as ISO 8601 date, "channels": (array of strings) step channels used with Canvas, "variants": [ { "name": (string) name of variant, "id": (string) API identifier of the variant, "first_step_ids": (array of strings) API identifiers for first steps in variant, "first_step_id": (string) API identifier of first step in variant (deprecated in November 2017, only included if the variant has only one first step) }, ... (more variations) ], "tags": (array of strings) tag names associated with the Canvas, "steps": [ { "name": (string) name of step, "id": (string) API identifier of the step, "next_step_ids": (array of strings) API identifiers of steps following step, "channels": (array of strings) channels used in step, "messages": { "message_variation_id": (string) { // <=This is the actual id "channel": (string) channel type of the message (eg., "email"), ... channel-specific fields for this message, see Campaign Details Endpoint API Response for example message responses ... } } }, ... (more steps) ], "message": (required, string) the status of the export, returns 'success' when completed without errors } ``` > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://desktop.postman.com/?desktopVersion=9.19.0&userId=16580579&teamId=409325). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: canvas_id in: query schema: type: string description: >- (Required) String See [Canvas API Identifier](https://www.braze.com/docs/api/identifier_types/) example: '{{canvas_identifier}}' responses: '200': 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' /canvas/list: get: tags: - Export > Canvas summary: Export Canvas List description: >- > Use this endpoint to export a list of Canvases, including the name, Canvas API identifier and associated tags. Canvases are returned in groups of 100 sorted by time of creation (oldest to newest by default). Archived Canvases will not be included in the API response unless the `include_archived` field is specified. Canvases that are stopped but not archived, however, will be returned by default. To use this endpoint, youll need to generate an API key with the `canvas.list` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "canvases" : [ { "id" : (string) Canvas API Identifier, "last_edited": (ISO 8601 string) the last edited time for the message, "name" : (string) Canvas name, "tags" : (array) tag names associated with the Canvas, }, ... (more Canvases) ], "message": (required, string) the status of the export, returns 'success' when completed without errors } ``` > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://desktop.postman.com/?desktopVersion=9.19.0&userId=16580579&teamId=409325). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: page in: query schema: type: integer description: >- (Optional) Integer The page of Canvases to return, defaults to `0` (returns the first set of up to 100). example: 1 - name: include_archived in: query schema: type: boolean description: |- (Optional) Boolean Whether or not to include archived Canvases, defaults to `false`. - name: sort_direction in: query schema: type: string description: >- (Optional) String - Sort creation time from newest to oldest: pass in the value `desc`. - Sort creation time from oldest to newest: pass in the value `asc`. If `sort_direction` is not included, the default order is oldest to newest. example: desc - name: last_edit.time[gt] in: query schema: type: string description: >- (Optional) Datetime ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string) Filters the results and only returns Canvases that were edited greater than the time provided till now. Format is `yyyy-MM-DDTHH:mm:ss`. example: '2020-06-28T23:59:59-5:00' responses: '200': 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' /events/list: get: tags: - Export > Custom Events summary: Export Custom Events List description: >- > Use this endpoint to export a list of custom events that have been recorded for your app. The event names are returned in groups of 250, sorted alphabetically. To use this endpoint, youll need to generate an API key with the `events.list` permission. ## Rate limit For customers who onboarded with Braze on or after September 16, 2021, we apply a shared rate limit of 1,000 requests per hour to this endpoint. This rate limit is shared with the `/purchases/product_list` endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "message": (required, string) the status of the export, returns 'success' when completed without errors, "events" : [ "Event A", (string) the event name, "Event B", (string) the event name, "Event C", (string) the event name, ... ] } ``` ### Fatal error response codes For status codes and associated error messages that will be returned if your request encounters a fatal error, reference [Fatal errors & responses](https://www.braze.com/docs/api/errors/#fatal-errors). > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: page in: query schema: type: integer description: >- (Optional) Integer The page of event names to return, defaults to 0 (returns the first set of up to 250). example: 3 responses: '200': 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' /events/data_series: get: tags: - Export > Custom Events summary: Export Custom Events Analytics description: >- > Use this endpoint to retrieve a series of the number of occurrences of a custom event in your app over a designated time period. Note: If you are using our [older navigation](https://www.braze.com/docs/navigation), `app_id` can be found at**Developer Console** > **API Settings** To use this endpoint, youll need to generate an API key with the `events.data_series` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "message": (required, string) the status of the export, returns 'success' when completed without errors, "data" : [ { "time" : (string) point in time - as ISO 8601 extended when unit is "hour" and as ISO 8601 date when unit is "day", "count" : (int) }, ... ] } ``` ### Fatal error response codes For status codes and associated error messages that will be returned if your request encounters a fatal error, reference [Fatal errors & responses](https://www.braze.com/docs/api/errors/#fatal-errors). > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: event in: query schema: type: string description: |- (Required) String The name of the custom event for which to return analytics. example: event_name - name: length in: query schema: type: integer description: >- (Required) Integer Maximum number of units (days or hours) before `ending_at` to include in the returned series. Must be between 1 and 100 (inclusive). example: 24 - name: unit in: query schema: type: string description: >- (Optional) String Unit of time between data points - can be `day` or `hour`, defaults to `day`. example: hour - name: ending_at in: query schema: type: string description: >- (Optional) Datetime ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string) Date on which the data series should end. Defaults to time of the request. example: '2014-12-10T23:59:59-05:00' - name: app_id in: query schema: type: string description: >- (Optional) String App API identifier retrieved from **Settings > Setup and Testing > API Keys** to limit analytics to a specific app. example: '{{app_identifier}}' - name: segment_id in: query schema: type: string description: >- (Optional) String See [Segment API identifier](https://www.braze.com/docs/api/identifier_types/). Segment ID indicating the analytics-enabled segment for which event analytics should be returned. example: '{{segment_identifier}}' responses: '200': 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' /kpi/new_users/data_series: get: tags: - Export > KPI summary: Export Daily New Users by Date description: >- > Use this endpoint to retrieve a daily series of the total number of new users on each date. Note: If you are using our [older navigation](https://www.braze.com/docs/navigation), `app_id` can be found at **Developer Console** > **API Settings**. To use this endpoint, youll need to generate an API key with the `kpi.new_users.data_series` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "message": (required, string) the status of the export, returns 'success' when completed without errors, "data" : [ { "time" : (string) the date as ISO 8601 date, "new_users" : (int) the number of daily new users }, ... ] } ``` > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: length in: query schema: type: integer description: >- (Required) Integer Maximum number of days before `ending_at` to include in the returned series. Must be between 1 and 100 (inclusive). example: 14 - name: ending_at in: query schema: type: string description: >- (Optional) Datetime ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string) Date on which the data series should end. Defaults to time of the request. example: '2018-06-28T23:59:59-5:00' - name: app_id in: query schema: type: string description: >- (Optional) String App API identifier retrieved from **Settings > Setup and Testing > API Keys**. If excluded, results for all apps in workspace will be returned. example: '{{app_identifier}}' responses: '200': 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' /kpi/dau/data_series: get: tags: - Export > KPI summary: Export Daily Active Users by Date description: >- > Use this endpoint to retrieve a daily series of the total number of unique active users on each date. Note: If you are using our [older navigation](https://www.braze.com/docs/navigation), API Keys can be found at **Developer Console > API Settings**. To use this endpoint, youll need to generate an API key with the `kpi.dau.data_series` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "message": (required, string) the status of the export, returns 'success' when completed without errors, "data" : [ { "time" : (string) the date as ISO 8601 date, "dau" : (int) the number of daily active users }, ... ] } ``` > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: length in: query schema: type: integer description: >- (Required) Integer Maximum number of days before `ending_at` to include in the returned series. Must be between 1 and 100 (inclusive). example: 10 - name: ending_at in: query schema: type: string description: >- (Optional) Datetime ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string) Date on which the data series should end. Defaults to time of the request. example: '2018-06-28T23:59:59-5:00' - name: app_id in: query schema: type: string description: >- (Optional) String App API identifier retrieved from **Settings > Setup and Testing > API Keys**. If excluded, results for all apps in workspace will be returned. example: '{{app_identifier}}' responses: '200': 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' /kpi/mau/data_series: get: tags: - Export > KPI summary: Export Monthly Active Users for Last 30 Days description: >- > Use this endpoint to retrieve a daily series of the total number of unique active users over a 30-day rolling window. Note: If you are using our [older navigation](https://www.braze.com/docs/navigation), API Keys can be found at **Developer Console > API Settings**. To use this endpoint, youll need to generate an API key with the `kpi.mau.data_series` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "message": (required, string) the status of the export, returns 'success' when completed without errors, "data" : [ { "time" : (string) the date as ISO 8601 date, "mau" : (int) the number of monthly active users }, ... ] } ``` > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: length in: query schema: type: integer description: >- (Required) Integer Maximum number of days before `ending_at` to include in the returned series. Must be between 1 and 100 (inclusive). example: 7 - name: ending_at in: query schema: type: string description: >- (Optional) Datetime ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string) Date on which the data series should end. Defaults to time of the request. example: '2018-06-28T23:59:59-05:00' - name: app_id in: query schema: type: string description: >- (Optional) String App API identifier retrieved from **Settings > Setup and Testing > API Keys**. If excluded, results for all apps in workspace will be returned. example: '{{app_identifier}}' responses: '200': 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' /kpi/uninstalls/data_series: get: tags: - Export > KPI summary: Export KPIs for Daily App Uninstalls by Date description: >- > Use this endpoint to retrieve a daily series of the total number of uninstalls on each date. Note: If you are using our [older navigation](https://www.braze.com/docs/navigation), API Keys can be found at **Developer Console > API Settings**. To use this endpoint, youll need to generate an API key with the `kpi.uninstalls.data_series` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "message": (required, string) the status of the export, returns 'success' when completed without errors, "data" : [ { "time" : (string) the date as ISO 8601 date, "uninstalls" : (int) the number of uninstalls }, ... ] } ``` > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: length in: query schema: type: integer description: >- (Required) Integer Maximum number of days before `ending_at` to include in the returned series. Must be between 1 and 100 (inclusive). example: 14 - name: ending_at in: query schema: type: string description: >- (Optional) Datetime ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string) Date on which the data series should end. Defaults to time of the request. example: '2018-06-28T23:59:59-5:00' - name: app_id in: query schema: type: string description: >- (Optional) String App API identifier retrieved from **Settings > Setup and Testing > API Keys**. If excluded, results for all apps in workspace will be returned. example: '{{app_identifier}}' responses: '200': 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' /feed/data_series: get: tags: - Export > News Feed summary: Export News Feed Card Analytics description: >- > Use this endpoint to retrieve a daily series of engagement stats for a card over time. Note: If you are using our [older navigation](https://www.braze.com/docs/navigation), \`card_id\` can be found at **Developer Console > API Settings**. To use this endpoint, youll need to generate an API key with the `feed.data_series` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "message": (required, string) the status of the export, returns 'success' when completed without errors, "data" : [ { "time" : (string) the point in time - as ISO 8601 extended when unit is "hour" and as ISO 8601 date when unit is "day", "clicks" : (int) the number of clicks, "impressions" : (int) the number of impressions, "unique_clicks" : (int) the number of unique clicks, "unique_impressions" : (int) the number of unique impressions }, ... ] } ``` > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: card_id in: query schema: type: string description: >- (Required) String See [Card API identifier](https://www.braze.com/docs/api/identifier_types/). The `card_id` for a given card can be found in the **Settings > Setup and Testing > API Keys** page and on the card details page within your dashboard, or you can use the [News Feed List Endpoint](https://www.braze.com/docs/api/endpoints/export/news_feed/get_news_feed_cards/). example: '{{card_identifier}}' - name: length in: query schema: type: integer description: >- (Required) Integer Max number of units (days or hours) before `ending_at` to include in the returned series. Must be between 1 and 100 (inclusive). example: 14 - name: unit in: query schema: type: string description: >- (Optional) String Unit of time between data points. Can be `day` or `hour`, defaults to `day`. example: day - name: ending_at in: query schema: type: string description: > (Optional) Datetime ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string) Date on which the data series should end. Defaults to time of the request. example: '2018-06-28T23:59:59-5:00' responses: '200': 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' /feed/details: get: tags: - Export > News Feed summary: Export News Feed Cards Details description: >- > Use this endpoint to retrieve relevant information on a card, which can be identified by the `card_id`. Note: If you are using our [older navigation](https://www.braze.com/docs/navigation), `card_id` can be found at **Developer Console > API Settings**. To use this endpoint, youll need to generate an API key with the `feed.details` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "message": (required, string) The status of the export, returns 'success' when completed without errors, "created_at" : (string) Date created as ISO 8601 date, "updated_at" : (string) Date last updated as ISO 8601 date, "name" : (string) Card name, "publish_at" : (string) Date card was published as ISO 8601 date, "end_at" : (string) Date card will stop displaying for users as ISO 8601 date, "tags" : (array) Tag names associated with the card, "title" : (string) Title of the card, "image_url" : (string) Image URL used by this card, "extras" : (dictionary) Dictionary containing key-value pair data attached to this card, "description" : (string) Description text used by this card, "archived": (boolean) whether this Card is archived, "draft": (boolean) whether this Card is a draft, } ``` > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: card_id in: query schema: type: string description: >- (Required) String See [Card API identifier](https://www.braze.com/docs/api/identifier_types/). The `card_id` for a given card can be found in the **Settings > Setup and Testing > API Keys** page and on the card details page within your dashboard, or you can use the [News Feed List Endpoint](https://www.braze.com/docs/api/endpoints/export/news_feed/get_news_feed_cards/). example: '{{card_identifier}}' responses: '200': 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' /feed/list: get: tags: - Export > News Feed summary: Export News Feed Cards List description: >- > Use this endpoint to export a list of News Feed cards, each of which will include its name and card API identifier. The cards are returned in groups of 100 sorted by time of creation (oldest to newest by default). To use this endpoint, youll need to generate an API key with the `feed.list` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "message": (required, string) the status of the export, returns 'success' when completed without errors, "cards" : [ { "id" : (string) Card API Identifier, "type" : (string) type of the card - NewsItem (classic cards), CaptionedImage, Banner or DevPick (cross-promotional cards), "title" : (string) title of the card, "tags" : (array) tag names associated with the card }, ... ] } ``` > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: page in: query schema: type: integer description: >- (Optional) Integer The page of cards to return, defaults to 0 (returns the first set of up to 100). example: 1 - name: include_archived in: query schema: type: boolean description: |- (Optional) Boolean Whether or not to include archived cards, defaults to false. example: true - name: sort_direction in: query schema: type: string description: >- (Optional) String - Sort creation time from newest to oldest: pass in the value `desc`. - Sort creation time from oldest to newest: pass in the value `asc`. If `sort_direction` is not included, the default order is oldest to newest. example: desc responses: '200': 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' /purchases/product_list: get: tags: - Export > Purchases summary: Export Product IDs description: >- > Use this endpoint to return a paginated lists of product IDs. To use this endpoint, youll need to generate an API key with the `purchases.product_list` permission. ## Rate limit For customers who onboarded with Braze on or after September 16, 2021, we apply a shared rate limit of 1,000 requests per hour to this endpoint. This rate limit is shared with the `/events/list` endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "products": [ "product_name" (string), the name of the product ], "message": "success" } ``` > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: page in: query schema: type: integer description: |- (Optional) Integer The page of your product list that you would like to view. example: 1 responses: '200': 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' /purchases/quantity_series: get: tags: - Export > Purchases summary: Export Number of Purchases description: >- > Use this endpoint to return the total number of purchases in your app over a time range. To use this endpoint, youll need to generate an API key with the `purchases.quantity_series` permission. ## Rate limit For customers who onboarded with Braze on or after September 16, 2021, we apply a shared rate limit of 1,000 requests per hour to this endpoint. This rate limit is shared with the `/events/list` endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Example request ``` curl --location --request GET 'https://rest.iad-01.braze.com/purchases/quantity_series?length=100' \ --header 'Authorization: Bearer YOUR-REST-API-KEY' ``` ## Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "message": (required, string) the status of the export, returns 'success' when completed without errors, "data" : [ { "time" : (string) the date as ISO 8601 date, "purchase_quantity" : (int) the number of items purchased in the time period }, ... ] } ``` > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: ending_at in: query schema: type: string description: >- (Optional) Datetime (ISO 8601 string) Date on which the data series should end. Defaults to time of the request. example: '2018-06-28T23:59:59-5:00' - name: length in: query schema: type: integer description: >- (Required) Integer Maximum number of days before ending_at to include in the returned series. Must be between 1 and 100 (inclusive). example: 100 - name: unit in: query schema: type: integer description: >- (Optional) String Unit of time between data points. Can be `day` or `hour`, defaults to `day`. example: 14 - name: app_id in: query schema: type: string description: >- (Optional) String App API identifier retrieved from the Settings > Setup and Testing > API Keys to limit analytics to a specific app. example: '{{app_identifier}}' - name: product in: query schema: type: string description: >- (Optional) String Name of product to filter response by. If excluded, results for all apps will be returned. example: name responses: '200': 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' /purchases/revenue_series: get: tags: - Export > Purchases summary: Export Revenue Data by Time description: >- > Use this endpoint to return the total money spent in your app over a time range. To use this endpoint, youll need to generate an API key with the `purchases.revenue_series` permission. ## Rate limit For customers who onboarded with Braze on or after September 16, 2021, we apply a shared rate limit of 1,000 requests per hour to this endpoint. This rate limit is shared with the `/events/list` endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Example request ``` curl --location --request GET 'https://rest.iad-01.braze.com/purchases/revenue_series?length=100' \ --header 'Authorization: Bearer YOUR-REST-API-KEY' ``` ## Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "message": (required, string) the status of the export, returns 'success' when completed without errors, "data" : [ { "time" : (string) the date as ISO 8601 date, "revenue" : (int) amount of revenue for the time period }, ... ] } ``` > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: ending_at in: query schema: type: string description: >- (Optional) Datetime (ISO 8601 string) Date on which the data series should end. Defaults to time of the request. example: '2018-06-28T23:59:59-5:00' - name: length in: query schema: type: integer description: >- (Required) Integer Maximum number of days before ending_at to include in the returned series. Must be between 1 and 100 (inclusive). example: 100 - name: unit in: query schema: type: integer description: >- (Optional) String Unit of time between data points. Can be `day` or `hour`, defaults to `day`. example: 14 - name: app_id in: query schema: type: string description: >- (Optional) String App API identifier retrieved from the Settings > Setup and Testing > API Keys to limit analytics to a specific app. example: '{{app_identifier}}' - name: product in: query schema: type: string description: >- (Optional) String Name of product to filter response by. If excluded, results for all apps will be returned. example: name responses: '200': 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' /segments/list: get: tags: - Export > Segment summary: Export Segment List description: >- > Use this endpoint to export a list of segments, each of which will include its name, Segment API identifier, and whether it has analytics tracking enabled. The segments are returned in groups of 100 sorted by time of creation (oldest to newest by default). Archived segments are not included. To use this endpoint, youll need to generate an API key with the `segments.list` permission. ### Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "message": (required, string) the status of the export, returns 'success' when completed without errors, "segments" : [ { "id" : (string) Segment API Identifier, "name" : (string) segment name, "analytics_tracking_enabled" : (boolean) whether the segment has analytics tracking enabled, "tags" : (array) tag names associated with the segment }, ... ] } ``` > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: page in: query schema: type: integer description: >- (Optional) Integer The page of segments to return, defaults to 0 (returns the first set of up to 100). example: 1 - name: sort_direction in: query schema: type: string description: >- (Optional) String - Sort creation time from newest to oldest: pass in the value `desc`. - Sort creation time from oldest to newest: pass in the value `asc`. If `sort_direction` is not included, the default order is oldest to newest. example: desc responses: '200': 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' /segments/data_series: get: tags: - Export > Segment summary: Export Segment Analytics description: >- > Use this endpoint to retrieve a daily series of the estimated size of a segment over time. Note: If you are using our [older navigation](https://www.braze.com/docs/navigation), `segment_id` can be found at **Developer Console > API Settings**. To use this endpoint, youll need to generate an API key with the `segments.data_series` permission. ### Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "message": (required, string) the status of the export, returns 'success' when completed without errors, "data" : [ { "time" : (string) date as ISO 8601 date, "size" : (int) size of the segment on that date }, ... ] } ``` > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: segment_id in: query schema: type: string description: >- (Required) String See [Segment API identifier](https://www.braze.com/docs/api/identifier_types/). The `segment_id` for a given segment can be found in your **Settings > Setup and Testing > API Keys.** within your Braze account or you can use the [Segment List Endpoint](https://www.braze.com/docs/api/endpoints/export/get_segment/). example: '{{segment_identifier}}' - name: length in: query schema: type: integer description: >- (Required) Integer Max number of days before `ending_at` to include in the returned series - must be between 1 and 100 (inclusive). example: 14 - name: ending_at in: query schema: type: string description: >- (Optional) Datetime ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string) Date on which the data series should end. Defaults to time of the request. example: '2018-06-27T23:59:59-5:00' responses: '200': 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' /segments/details: get: tags: - Export > Segment summary: Export Segment Details description: >- > Use this endpoint to retrieve relevant information on a segment, which can be identified by the `segment_id`. Note: If you are using our [older navigation](https://www.braze.com/docs/navigation), `segment_id` can be found at **Developer Console > API Settings**. To use this endpoint, youll need to generate an API key with the `segments.details` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "message": (required, string) the status of the export, returns 'success' when completed without errors, "created_at" : (string) date created as ISO 8601 date, "updated_at" : (string) date last updated as ISO 8601 date, "name" : (string) segment name, "description" : (string) human-readable description of filters, "text_description" : (string) segment description, "tags" : (array) tag names associated with the segment } ``` > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: segment_id in: query schema: type: string description: >- (Required) String See [Segment API identifier](https://www.braze.com/docs/api/identifier_types/). The `segment_id` for a given segment can be found in your **Settings > Setup and Testing > API Keys** within your Braze account or you can use the [Segment List Endpoint](https://www.braze.com/docs/api/endpoints/export/get_segment/). example: '{{segment_identifier}}' responses: '200': 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' /sessions/data_series: get: tags: - Export > Session Analytics summary: Export App Sessions by Time description: >- > Use this endpoint to retrieve a series of the number of sessions for your app over a designated time period. Note: If you are using our [older navigation](https://www.braze.com/docs/navigation), `segment_id` can be found at **Developer Console > API Settings**. To use this endpoint, youll need to generate an API key with the `sessions.data_series` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "message": (required, string) the status of the export, returns 'success' when completed without errors, "data" : [ { "time" : (string) point in time - as ISO 8601 extended when unit is "hour" and as ISO 8601 date when unit is "day", "sessions" : (int) }, ... ] } ``` > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: length in: query schema: type: integer description: >- (Required) Integer Max number of days before `ending_at` to include in the returned series - must be between 1 and 100 (inclusive). example: 14 - name: unit in: query schema: type: string description: >- (Optional) String Unit of time between data points. Can be `day` or `hour`, defaults to `day`. example: day - name: ending_at in: query schema: type: string description: >- (Optional) Datetime (ISO 8601 string) Date on which the data series should end. Defaults to time of the request. example: '2018-06-28T23:59:59-5:00' - name: app_id in: query schema: type: string description: >- (Optional) String App API identifier retrieved from the **Settings > Setup and Testing > API Keys** to limit analytics to a specific app. example: '{{app_identifier}}' - name: segment_id in: query schema: type: string description: >- (Required) String See [Segment API identifier](https://www.braze.com/docs/api/identifier_types/). Segment ID indicating the analytics-enabled segment for which sessions should be returned. example: '{{segment_identifier}}' responses: '200': 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' /users/export/ids: post: tags: - Export > Users summary: Export User Profile by Identifier description: >- > Use this endpoint to export data from any user profile by specifying a user identifier. Up to 50 `external_ids` or `user_aliases` can be included in a single request. Should you want to specify `device_id` or `email_address` only one of either identifier can be included per request. To use this endpoint, youll need to generate an API key with the `users.export.ids` permission. ## Rate limit For customers who onboarded with Braze on or after August 16, 2021, we apply a rate limit of 2,500 requests per minute to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `external_ids` | Optional | Array of strings | External identifiers for users you wish export. | | `user_aliases` | Optional | Array of user alias object | [User aliases](https://www.braze.com/docs/api/objects_filters/user_alias_object/) for users to export. | | `device_id` | Optional | String | Device identifier, as returned by various SDK methods such as `getDeviceId`. | | `braze_id` | Optional | String | Braze identifier for a particular user. | | `email_address` | Optional | String | Email address of user. | | `phone` | Optional | String in [E.164](https://en.wikipedia.org/wiki/E.164) format | Phone number of user. | | `fields_to_export` | Optional | Array of strings | Name of user data fields to export. Defaults to all if not provided. | ## Fields to export The following is a list of valid `fields_to_export`. Using `fields_to_export` to minimize the data returned can improve response time of this API endpoint: | Field to export | Data type | Description | | --- | --- | --- | | `apps` | Array | Apps this user has logged sessions for, which includes the fields:

\- `name`: app name
\- `platform`: app platform, such as iOS, Android, or Web
\- `version`: app version number or name
\- `sessions`: total number of sessions for this app
\- `first_used`: date of first session
\- `last_used`: date of last session

All fields are strings. | | `attributed_campaign` | String | Data from [attribution integrations](https:/www.braze.com/docs/partners/message_orchestration/attribution), if set up. Identifier for a particular ad campaign. | | `attributed_source` | String | Data from [attribution integrations](https:/www.braze.com/docs/partners/message_orchestration/attribution), if set up. Identifier for the platform the ad was on. | | `attributed_adgroup` | String | Data from [attribution integrations](https:/www.braze.com/docs/partners/message_orchestration/attribution), if set up. Identifier for an optional sub-grouping below campaign. | | `attributed_ad` | String | Data from [attribution integrations](https:/www.braze.com/docs/partners/message_orchestration/attribution), if set up. Identifier for an optional sub-grouping below campaign and adgroup. | | `braze_id` | String | Device-specific unique user identifier set by Braze for this user. | | `country` | String | User's country using [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard. | | `created_at` | String | Date and time for when the user profile was created, in ISO 8601 format. | | `custom_attributes` | Object | Custom attribute key-value pairs for this user. | | `custom_events` | Array | Custom events attributed to this user in the last 90 days. | | `devices` | Array | Information about the user's device, which could include the following depending on platform:

\- `model`: Device's model name
\- `os`: Device's operating system
\- `carrier`: Device's service carrier, if available
\- `idfv`: (iOS) Braze's device identifier, the Apple Identifier for Vendor, if exists
\- `idfa`: (iOS) Identifier for Advertising, if exists
\- `device_id`: (Android) Braze's device identifier
\- `google_ad_id`: (Android) Google Play Advertising Identifier, if exists
\- `roku_ad_id`: (Roku) Roku Advertising Identifier
\- `ad_tracking_enabled`: If ad tracking is enabled on the device, can be true or false | | `dob` | String | User's date of birth in the format `YYYY-MM-DD`. | | `email` | String | User's email address. | | `external_id` | String | Unique user identifier for identified users. | | `first_name` | String | User's first name. | | `gender` | String | User's gender. Possible values are:

\- `M`: male
\- `F`: female
\- `O`: other
\- `N`: not applicable
\- `P`: prefer not to say
\- `nil`: unknown | | `home_city` | String | User's home city. | | `language` | String | User's language in ISO-639-1 standard. | | `last_coordinates` | Array of floats | User's most recent device location, formatted as `[longitude, latitude]`. | | `last_name` | String | User's last name. | | `phone` | String | User's telephone number in E.164 format. | | `purchase`s | Array | Purchases this user has made in the last 90 days. | | `random_bucket` | Integer | User's [random bucket number](https:/www.braze.com/docs/user_guide/data_and_analytics/braze_currents/event_glossary/customer_behavior_events#random-bucket-number-event), used to create uniformly distributed segments of random users. | | `time_zone` | String | User's time zone in the same format as the IANA Time Zone Database. | | `total_revenue` | Float | Total revenue attributed to this user. Total revenue is calculated based on purchases the user made during conversion windows for the campaigns and Canvases they received. | | `uninstalled_at` | Timestamp | Date and time the user uninstalls the app. Omitted if the app has not been uninstalled. | | `user_aliases` | Object | [User aliases object](https:/www.braze.com/docs/api/objects_filters/user_alias_object#user-alias-object-specification) containing the `alias_name` and `alias_label`, if exists. | ### Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "message": (required, string) the status of the export, returns 'success' when completed without errors, "users" : (array of object) the data for each of the exported users, may be empty if no users are found, "invalid_user_ids" : (optional, array of string) each of the identifiers provided in the request that did not correspond to a known user } ``` For an example of the data that is accessible via this endpoint see the following example. ### Sample user export file output User export object (we will include the least data possible - if a field is missing from the object it should be assumed to be null, false, or empty): ``` json { "external_id" : (string), "user_aliases" : [ { "alias_name" : (string), "alias_label" : (string) } ], "braze_id": (string), "first_name" : (string), "last_name" : (string), "email" : (string), "dob" : (string) date for the user's date of birth, "home_city" : (string), "country" : (string), "phone" : (string), "language" : (string) ISO-639 two letter code, "time_zone" : (string), "last_coordinates" : (array of float) [lon, lat], "gender" : (string) "M" | "F", "total_revenue" : (float), "attributed_campaign" : (string), "attributed_source" : (string), "attributed_adgroup" : (string), "attributed_ad" : (string), "push_subscribe" : (string) "opted_in" | "subscribed" | "unsubscribed", "email_subscribe" : (string) "opted_in" | "subscribed" | "unsubscribed", "custom_attributes" : (object) custom attribute key-value pairs, "custom_events" : [ { "name" : (string), "first" : (string) date, "last" : (string) date, "count" : (int) }, ... ], "purchases" : [ { "name" : (string), "first" : (string) date, "last" : (string) date, "count" : (int) }, ... ], "devices" : [ { "model" : (string), "os" : (string), "carrier" : (string), "idfv" : (string) only included for iOS devices, "idfa" : (string) only included for iOS devices when IDFA collection is enabled, "google_ad_id" : (string) only included for Android devices when Google Play Advertising Identifier collection is enabled, "roku_ad_id" : (string) only included for Roku devices, "windows_ad_id" : (string) only included for Windows devices, "ad_tracking_enabled" : (bool) }, ... ], "push_tokens" : [ { "app" : (string) app name, "platform" : (string), "token" : (string) }, ... ], "apps" : [ { "name" : (string), "platform" : (string), "version" : (string), "sessions" : (integer), "first_used" : (string) date, "last_used" : (string) date }, ... ], "campaigns_received" : [ { "name" : (string), "last_received" : (string) date, "engaged" : { "opened_email" : (bool), "opened_push" : (bool), "clicked_email" : (bool), "clicked_triggered_in_app_message" : (bool) }, "converted" : (bool), "api_campaign_id" : (string), "variation_name" : (optional, string) exists only if it is a multivariate campaign, "variation_api_id" : (optional, string) exists only if it is a multivariate campaign, "in_control" : (optional, bool) exists only if it is a multivariate campaign }, ... ], "canvases_received": [ { "name": (string), "api_canvas_id": (string), "last_received_message": (string) date, "last_entered": (string) date, "variation_name": (string), "in_control": (bool), "last_exited": (string) date, "steps_received": [ { "name": (string), "api_canvas_step_id": (string), "last_received": (string) date }, { "name": (string), "api_canvas_step_id": (string), "last_received": (string) date }, { "name": (string), "api_canvas_step_id": (string), "last_received": (string) date } ] }, ... ], "cards_clicked" : [ { "name" : (string) }, ... ] } ``` #### Sample output ``` json { "created_at" : "2020-07-10 15:00:00.000 UTC", "external_id" : "A8i3mkd99", "user_aliases" : [ { "alias_name" : "user_123", "alias_label" : "amplitude_id" } ], "braze_id": "5fbd99bac125ca40511f2cb1", "random_bucket" : 2365, "first_name" : "Jane", "last_name" : "Doe", "email" : "example@braze.com", "dob" : "1980-12-21", "home_city" : "Chicago", "country" : "US", "phone" : "+442071838750", "language" : "en", "time_zone" : "Eastern Time (US & Canada)", "last_coordinates" : [41.84157636433568, -87.83520818508256], "gender" : "F", "total_revenue" : 65, "attributed_campaign" : "braze_test_campaign_072219", "attributed_source" : "braze_test_source_072219", "attributed_adgroup" : "braze_test_adgroup_072219", "attributed_ad" : "braze_test_ad_072219", "push_subscribe" : "opted_in", "push_opted_in_at": "2020-01-26T22:45:53.953Z", "email_subscribe" : "subscribed", "custom_attributes": { "loyaltyId": "37c98b9d-9a7f-4b2f-a125-d873c5152856", "loyaltyPoints": "321", "loyaltyPointsNumber": 107 }, "custom_events": [ { "name": "Loyalty Acknowledgement", "first": "2021-06-28T17:02:43.032Z", "last": "2021-06-28T17:02:43.032Z", "count": 1 }, ... ], "purchases": [ { "name": "item_40834", "first": "2021-09-05T03:45:50.540Z", "last": "2022-06-03T17:30:41.201Z", "count": 10 }, ... ], "devices": [ { "model": "Pixel XL", "os": "Android (Q)", "carrier": null, "device_id": "312ef2c1-83db-4789-967-554545a1bf7a", "ad_tracking_enabled": true }, ... ], "push_tokens": [ { "app": "MovieCanon", "platform": "Android", "token": "12345abcd", "device_id": "312ef2c1-83db-4789-967-554545a1bf7a", "notifications_enabled": true }, ... ], "apps": [ { "name": "MovieCannon", "platform": "Android", "version": "3.29.0", "sessions": 1129, "first_used": "2020-02-02T19:56:19.142Z", "last_used": "2021-11-11T00:25:19.201Z" }, ... ], "campaigns_received": [ { "name": "Email Unsubscribe", "api_campaign_id": "d72fdc84-ddda-44f1-a0d5-0e79f47ef942", "last_received": "2022-06-02T03:07:38.105Z", "engaged": { "opened_email": true }, "converted": true, "multiple_converted": { "Primary Conversion Event - A": true }, "in_control": false, "variation_name": "Variant 1", "variation_api_id": "1bddc73a-a134-4784-9134-5b5574a9e0b8" }, ... ], "canvases_received": [ { "name": "Non Global Holdout Group 4/21/21", "api_canvas_id": "46972a9d-dc81-473f-aa03-e3473b4ed781", "last_received_message": "2021-07-07T20:46:24.136Z", "last_entered": "2021-07-07T20:45:24.000+00:00", "variation_name": "Variant 1", "in_control": false, "last_entered_control_at": null, "last_exited": "2021-07-07T20:46:24.136Z", "steps_received": [ { "name": "Step", "api_canvas_step_id": "43d1a349-c3c8-4be1-9fbe-ce708e4d1c39", "last_received": "2021-07-07T20:46:24.136Z" }, ... ] } ... ], "cards_clicked" : [ { "name" : "Loyalty Promo" }, ... ] } ``` > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). requestBody: content: application/json: schema: type: object example: external_ids: - user_identifier1 - user_identifier2 user_aliases: - alias_name: example_alias alias_label: example_label device_id: '1234567' braze_id: braze_identifier email_address: example@braze.com phone: '+11112223333' fields_to_export: - first_name - email - purchases properties: external_ids: type: array items: type: string user_aliases: type: array items: type: object properties: alias_name: type: string alias_label: type: string device_id: type: string braze_id: type: string email_address: type: string format: email phone: type: string fields_to_export: type: array items: 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' /users/export/segment: post: tags: - Export > Users summary: Export User Profile by Segment description: >- > Use this endpoint to export all the users within a segment. User data is exported as multiple files of user JSON objects separated by new lines (i.e., one JSON object per line). Data is exported to an automatically generated URL, or to an S3 bucket if this integration is already set up. This endpoint is currently not supported by Google Cloud Storage. Note that a company may run at most one export per segment using this endpoint at a given time. Wait for your export to complete before retrying. > Beginning December 2021, the following changed for this API: > 1\. The fields_to_export field in this API request is required. The option to default to all fields has been removed. 2\. The fields for custom_events, purchases, campaigns_received, and canvases_received only contain data from the last 90 days. Note: If you are using our [older navigation](https://www.braze.com/docs/navigation), `segment_id` can be found at **Developer Console > API Settings**. To use this endpoint, youll need to generate an API key with the `users.export.segment` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Credential-based response details For information regarding credentials-based response details, visit this [section](https://www.braze.com/docs/api/endpoints/export/user_data/post_users_segment/#credentials-based-response-details) in the Braze API docs. ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `segment_id` | Required | String | Identifier for the segment to be exported. See [segment identifier](https://www.braze.com/docs/api/identifier_types/).

The segment_id for a given segment can be found in your **Settings > Setup and Testing > API Keys** within your Braze account or you can use the [Segment List Endpoint](https://www.braze.com/docs/api/endpoints/export/segments/get_segment/). | | `callback_endpoint` | Optional | String | Endpoint to post a download URL to when the export is available. | | `fields_to_export` | Required\* | Array of strings | Name of user data fields to export, you may also export custom attributes.

\*Beginning April 2021, new accounts must specify specific fields to export. | | `output_format` | Optional | String | When using your own S3 bucket, allows you to specify file format as `zip` or `gzip`. Defaults to ZIP file format. | ### Fields to export The following is a list of valid `fields_to_export`. Using `fields_to_export` to minimize the data returned can improve response time of this API endpoint: | Field to export | Data type | Description | | --- | --- | --- | | `apps` | Array | Apps this user has logged sessions for, which includes the fields:

\- `name`: app name
\- `platform`: app platform, such as iOS, Android, or Web
\- `version`: app version number or name
\- `sessions`: total number of sessions for this app
\- `first_used`: date of first session
\- `last_used`: date of last session

All fields are strings. | | `attributed_campaign` | String | Data from [attribution integrations](https:/www.braze.com/docs/partners/message_orchestration/attribution), if set up. Identifier for a particular ad campaign. | | `attributed_source` | String | Data from [attribution integrations](https:/www.braze.com/docs/partners/message_orchestration/attribution), if set up. Identifier for the platform the ad was on. | | `attributed_adgroup` | String | Data from [attribution integrations](https:/www.braze.com/docs/partners/message_orchestration/attribution), if set up. Identifier for an optional sub-grouping below campaign. | | `attributed_ad` | String | Data from [attribution integrations](https:/www.braze.com/docs/partners/message_orchestration/attribution), if set up. Identifier for an optional sub-grouping below campaign and adgroup. | | `braze_id` | String | Device-specific unique user identifier set by Braze for this user. | | `country` | String | User's country using [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard. | | `created_at` | String | Date and time for when the user profile was created, in ISO 8601 format. | | `custom_attributes` | Object | Custom attribute key-value pairs for this user. | | `custom_events` | Array | Custom events attributed to this user in the last 90 days. | | `devices` | Array | Information about the user's device, which could include the following depending on platform:

\- `model`: Device's model name
\- `os`: Device's operating system
\- `carrier`: Device's service carrier, if available
\- `idfv`: (iOS) Braze's device identifier, the Apple Identifier for Vendor, if exists
\- `idfa`: (iOS) Identifier for Advertising, if exists
\- `device_id`: (Android) Braze's device identifier
\- `google_ad_id`: (Android) Google Play Advertising Identifier, if exists
\- `roku_ad_id`: (Roku) Roku Advertising Identifier
\- `ad_tracking_enabled`: If ad tracking is enabled on the device, can be true or false | | `dob` | String | User's date of birth in the format `YYYY-MM-DD`. | | `email` | String | User's email address. | | `external_id` | String | Unique user identifier for identified users. | | `first_name` | String | User's first name. | | `gender` | String | User's gender. Possible values are:

\- `M`: male
\- `F`: female
\- `O`: other
\- `N`: not applicable
\- `P`: prefer not to say
\- `nil`: unknown | | `home_city` | String | User's home city. | | `language` | String | User's language in ISO-639-1 standard. | | `last_coordinates` | Array of floats | User's most recent device location, formatted as `[longitude, latitude]`. | | `last_name` | String | User's last name. | | `phone` | String | User's telephone number in E.164 format. | | `purchase`s | Array | Purchases this user has made in the last 90 days. | | `random_bucket` | Integer | User's [random bucket number](https:/www.braze.com/docs/user_guide/data_and_analytics/braze_currents/event_glossary/customer_behavior_events#random-bucket-number-event), used to create uniformly distributed segments of random users. | | `time_zone` | String | User's time zone in the same format as the IANA Time Zone Database. | | `total_revenue` | Float | Total revenue attributed to this user. Total revenue is calculated based on purchases the user made during conversion windows for the campaigns and Canvases they received. | | `uninstalled_at` | Timestamp | Date and time the user uninstalls the app. Omitted if the app has not been uninstalled. | | `user_aliases` | Object | [User aliases object](https:/www.braze.com/docs/api/objects_filters/user_alias_object#user-alias-object-specification) containing the `alias_name` and `alias_label`, if exists. | ### Important reminders - The fields for `custom_events`, `purchases`, `campaigns_received`, and `canvases_received` will contain only contain data from the last 90 days. - Both `custom_events` and `purchases` contain fields for `first` and `count`. Both of these fields will reflect information from all time, and will not be limited to just data from the last 90 days. For example, if a particular user first did the event prior to 90 days ago, this will be accurately reflected in the `first` field, and the `count` field will take into account events that occurred prior to the last 90 days as well. - The number of concurrent segment exports a company can run at the endpoint level is capped at 100. Attempts that surpass this limit will result in an error. ### Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "message": (required, string) the status of the export, returns 'success' when completed without errors, "object_prefix": (required, string) the filename prefix that will be used for the JSON file produced by this export, e.g. 'bb8e2a91-c4aa-478b-b3f2-a4ee91731ad1-1464728599', "url" : (optional, string) the URL where the segment export data can be downloaded if you do not have your own S3 credentials } ``` Once made available, the URL will only be valid for a few hours. As such, we highly recommend that you add your own S3 credentials to Braze. ### Sample user export file output User export object (we will include the least data possible - if a field is missing from the object it should be assumed to be null, false, or empty): ``` json { "external_id" : (string), "user_aliases" : [ { "alias_name" : (string), "alias_label" : (string) } ], "braze_id": (string), "first_name" : (string), "last_name" : (string), "email" : (string), "dob" : (string) date for the user's date of birth, "home_city" : (string), "country" : (string), "phone" : (string), "language" : (string) ISO-639 two letter code, "time_zone" : (string), "last_coordinates" : (array of float) [lon, lat], "gender" : (string) "M" | "F", "total_revenue" : (float), "attributed_campaign" : (string), "attributed_source" : (string), "attributed_adgroup" : (string), "attributed_ad" : (string), "push_subscribe" : (string) "opted_in" | "subscribed" | "unsubscribed", "email_subscribe" : (string) "opted_in" | "subscribed" | "unsubscribed", "custom_attributes" : (object) custom attribute key value pairs, "custom_events" : [ { "name" : (string), "first" : (string) date, "last" : (string) date, "count" : (int) }, ... ], "purchases" : [ { "name" : (string), "first" : (string) date, "last" : (string) date, "count" : (int) }, ... ], "devices" : [ { "model" : (string), "os" : (string), "carrier" : (string), "idfv" : (string) only included for iOS devices, "idfa" : (string) only included for iOS devices when IDFA collection is enabled, "google_ad_id" : (string) only included for Android devices when Google Play Advertising Identifier collection is enabled, "roku_ad_id" : (string) only included for Roku devices, "windows_ad_id" : (string) only included for Windows devices, "ad_tracking_enabled" : (bool) }, ... ], "push_tokens" : [ { "app" : (string) app name, "platform" : (string), "token" : (string) }, ... ], "apps" : [ { "name" : (string), "platform" : (string), "version" : (string), "sessions" : (string), "first_used" : (string) date, "last_used" : (string) date }, ... ], "campaigns_received" : [ { "name" : (string), "last_received" : (string) date, "engaged" : { "opened_email" : (bool), "opened_push" : (bool), "clicked_email" : (bool), "clicked_in_app_message" : (bool) }, "converted" : (bool), "api_campaign_id" : (string), "variation_name" : (optional, string) exists only if it is a multivariate campaign, "variation_api_id" : (optional, string) exists only if it is a multivariate campaign, "in_control" : (optional, bool) exists only if it is a multivariate campaign }, ... ], "canvases_received": [ { "name": (string), "api_canvas_id": (string), "last_received_message": (string) date, "last_entered": (string) date, "variation_name": (string), "in_control": (bool), "last_exited": (string) date, "steps_received": [ { "name": (string), "api_canvas_step_id": (string), "last_received": (string) date }, { "name": (string), "api_canvas_step_id": (string), "last_received": (string) date }, { "name": (string), "api_canvas_step_id": (string), "last_received": (string) date } ] }, ... ], "cards_clicked" : [ { "name" : (string) }, ... ] } ``` Sample output ``` json { "created_at" : "2020-07-10 15:00:00.000 UTC", "external_id" : "A8i3mkd99", "user_aliases" : [ { "alias_name" : "user_123", "alias_label" : "amplitude_id" } ], "braze_id": "5fbd99bac125ca40511f2cb1", "random_bucket" : 2365, "first_name" : "Jane", "last_name" : "Doe", "email" : "example@braze.com", "dob" : "1980-12-21", "home_city" : "Chicago", "country" : "US", "phone" : "+442071838750", "language" : "en", "time_zone" : "Eastern Time (US & Canada)", "last_coordinates" : [41.84157636433568, -87.83520818508256], "gender" : "F", "total_revenue" : 65, "attributed_campaign" : "braze_test_campaign_072219", "attributed_source" : "braze_test_source_072219", "attributed_adgroup" : "braze_test_adgroup_072219", "attributed_ad" : "braze_test_ad_072219", "push_subscribe" : "opted_in", "push_opted_in_at": "2020-01-26T22:45:53.953Z", "email_subscribe" : "subscribed", "custom_attributes": { "loyaltyId": "37c98b9d-9a7f-4b2f-a125-d873c5152856", "loyaltyPoints": "321", "loyaltyPointsNumber": 107 }, "custom_events": [ { "name": "Loyalty Acknowledgement", "first": "2021-06-28T17:02:43.032Z", "last": "2021-06-28T17:02:43.032Z", "count": 1 }, ... ], "purchases": [ { "name": "item_40834", "first": "2021-09-05T03:45:50.540Z", "last": "2022-06-03T17:30:41.201Z", "count": 10 }, ... ], "devices": [ { "model": "Pixel XL", "os": "Android (Q)", "carrier": null, "device_id": "312ef2c1-83db-4789-967-554545a1bf7a", "ad_tracking_enabled": true }, ... ], "push_tokens": [ { "app": "MovieCanon", "platform": "Android", "token": "12345abcd", "device_id": "312ef2c1-83db-4789-967-554545a1bf7a", "notifications_enabled": true }, ... ], "apps": [ { "name": "MovieCannon", "platform": "Android", "version": "3.29.0", "sessions": 1129, "first_used": "2020-02-02T19:56:19.142Z", "last_used": "2021-11-11T00:25:19.201Z" }, ... ], "campaigns_received": [ { "name": "Email Unsubscribe", "api_campaign_id": "d72fdc84-ddda-44f1-a0d5-0e79f47ef942", "last_received": "2022-06-02T03:07:38.105Z", "engaged": { "opened_email": true }, "converted": true, "multiple_converted": { "Primary Conversion Event - A": true }, "in_control": false, "variation_name": "Variant 1", "variation_api_id": "1bddc73a-a134-4784-9134-5b5574a9e0b8" }, ... ], "canvases_received": [ { "name": "Non Global Holdout Group 4/21/21", "api_canvas_id": "46972a9d-dc81-473f-aa03-e3473b4ed781", "last_received_message": "2021-07-07T20:46:24.136Z", "last_entered": "2021-07-07T20:45:24.000+00:00", "variation_name": "Variant 1", "in_control": false, "last_entered_control_at": null, "last_exited": "2021-07-07T20:46:24.136Z", "steps_received": [ { "name": "Step", "api_canvas_step_id": "43d1a349-c3c8-4be1-9fbe-ce708e4d1c39", "last_received": "2021-07-07T20:46:24.136Z" }, ... ] } ... ], "cards_clicked" : [ { "name" : "Loyalty Promo" }, ... ] } ``` > Tip: For help with CSV and API exports, visit Export troubleshooting. requestBody: content: application/json: schema: type: object example: segment_id: segment_identifier callback_endpoint: example_endpoint fields_to_export: - first_name - email - purchases output_format: zip properties: segment_id: type: string callback_endpoint: type: string fields_to_export: type: array items: type: string output_format: 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' /users/export/global_control_group: post: tags: - Export > Users summary: Export User Profile by Global Control Group description: >- > Use this endpoint to export all users within a Global Control Group. User data is exported as multiple files of user JSON objects separated by new lines (i.e., one JSON object per line). > Warning: Individual custom attributes cannot be exported. However, all custom attributes can be exported by including custom_attributes in the fields_to_export array (e.g.,\[first_name, email, custom_attributes\]). To use this endpoint, youll need to generate an API key with the `users.export.global_control_group` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](http://localhost:4000/docs/api/api_limits/). ## Credential-based response details For information regarding credentials-based response details, visit this [section](https://www.braze.com/docs/api/endpoints/export/user_data/post_users_global_control_group/#credentials-based-response-details) in the Braze API docs. ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `callback_endpoint` | Optional | String | Endpoint to post a download URL to when the export is available. | | `fields_to_export` | Required\* | Array of strings | Name of user data fields to export, you may also export custom attributes.

\*Beginning April 2021, new accounts must specify specific fields to export. | | `output_format` | Optional | String | When using your own S3 bucket, allows to specify file format as `zip` or `gzip`. Defaults to ZIP file format. | ## Fields to export The following is a list of valid `fields_to_export`. Using `fields_to_export` to minimize the data returned can improve response time of this API endpoint: | Field to export | Data type | Description | | --- | --- | --- | | `apps` | Array | Apps this user has logged sessions for, which includes the fields:

\- `name`: app name
\- `platform`: app platform, such as iOS, Android, or Web
\- `version`: app version number or name
\- `sessions`: total number of sessions for this app
\- `first_used`: date of first session
\- `last_used`: date of last session

All fields are strings. | | `attributed_campaign` | String | Data from [attribution integrations](https:/www.braze.com/docs/partners/message_orchestration/attribution), if set up. Identifier for a particular ad campaign. | | `attributed_source` | String | Data from [attribution integrations](https:/www.braze.com/docs/partners/message_orchestration/attribution), if set up. Identifier for the platform the ad was on. | | `attributed_adgroup` | String | Data from [attribution integrations](https:/www.braze.com/docs/partners/message_orchestration/attribution), if set up. Identifier for an optional sub-grouping below campaign. | | `attributed_ad` | String | Data from [attribution integrations](https:/www.braze.com/docs/partners/message_orchestration/attribution), if set up. Identifier for an optional sub-grouping below campaign and adgroup. | | `braze_id` | String | Device-specific unique user identifier set by Braze for this user. | | `country` | String | User's country using [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard. | | `created_at` | String | Date and time for when the user profile was created, in ISO 8601 format. | | `custom_attributes` | Object | Custom attribute key-value pairs for this user. | | `custom_events` | Array | Custom events attributed to this user in the last 90 days. | | `devices` | Array | Information about the user's device, which could include the following depending on platform:

\- `model`: Device's model name
\- `os`: Device's operating system
\- `carrier`: Device's service carrier, if available
\- `idfv`: (iOS) Braze's device identifier, the Apple Identifier for Vendor, if exists
\- `idfa`: (iOS) Identifier for Advertising, if exists
\- `device_id`: (Android) Braze's device identifier
\- `google_ad_id`: (Android) Google Play Advertising Identifier, if exists
\- `roku_ad_id`: (Roku) Roku Advertising Identifier
\- `ad_tracking_enabled`: If ad tracking is enabled on the device, can be true or false | | `dob` | String | User's date of birth in the format `YYYY-MM-DD`. | | `email` | String | User's email address. | | `external_id` | String | Unique user identifier for identified users. | | `first_name` | String | User's first name. | | `gender` | String | User's gender. Possible values are:

\- `M`: male
\- `F`: female
\- `O`: other
\- `N`: not applicable
\- `P`: prefer not to say
\- `nil`: unknown | | `home_city` | String | User's home city. | | `language` | String | User's language in ISO-639-1 standard. | | `last_coordinates` | Array of floats | User's most recent device location, formatted as `[longitude, latitude]`. | | `last_name` | String | User's last name. | | `phone` | String | User's telephone number in E.164 format. | | `purchase`s | Array | Purchases this user has made in the last 90 days. | | `random_bucket` | Integer | User's [random bucket number](https:/www.braze.com/docs/user_guide/data_and_analytics/braze_currents/event_glossary/customer_behavior_events#random-bucket-number-event), used to create uniformly distributed segments of random users. | | `time_zone` | String | User's time zone in the same format as the IANA Time Zone Database. | | `total_revenue` | Float | Total revenue attributed to this user. Total revenue is calculated based on purchases the user made during conversion windows for the campaigns and Canvases they received. | | `uninstalled_at` | Timestamp | Date and time the user uninstalls the app. Omitted if the app has not been uninstalled. | | `user_aliases` | Object | [User aliases object](https:/www.braze.com/docs/api/objects_filters/user_alias_object#user-alias-object-specification) containing the `alias_name` and `alias_label`, if exists. | ## Response ``` Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "message": (required, string) the status of the export, returns 'success' when completed without errors, "object_prefix": (required, string) the filename prefix that will be used for the JSON file produced by this export, e.g.,'bb8e2a91-c4aa-478b-b3f2-a4ee91731ad1-1464728599', "url" : (optional, string) the URL where the segment export data can be downloaded if you do not have your own S3 credentials } ``` Once made available, the URL will only be valid for a few hours. As such, we highly recommend that you add your own S3 credentials to Braze. ### Sample user export file output User export object (we will include the least data possible - if a field is missing from the object it should be assumed to be null, false, or empty): ``` { "external_id" : (string), "user_aliases" : [ { "alias_name" : (string), "alias_label" : (string) } ], "braze_id": (string), "first_name" : (string), "last_name" : (string), "email" : (string), "dob" : (string) date for the user's date of birth, "home_city" : (string), "country" : (string), "phone" : (string), "language" : (string) ISO-639 two letter code, "time_zone" : (string), "last_coordinates" : (array of float) [lon, lat], "gender" : (string) "M" | "F", "total_revenue" : (float), "attributed_campaign" : (string), "attributed_source" : (string), "attributed_adgroup" : (string), "attributed_ad" : (string), "custom_attributes" : (object) custom attribute key-value pairs, "custom_events" : [ { "name" : (string), "first" : (string) date, "last" : (string) date, "count" : (int) }, ... ], "purchases" : [ { "name" : (string), "first" : (string) date, "last" : (string) date, "count" : (int) }, ... ], "devices" : [ { "model" : (string), "os" : (string), "carrier" : (string), "idfv" : (string) only included for iOS devices, "idfa" : (string) only included for iOS devices when IDFA collection is enabled, "google_ad_id" : (string) only included for Android devices when Google Play Advertising Identifier collection is enabled, "roku_ad_id" : (string) only included for Roku devices, "windows_ad_id" : (string) only included for Windows devices, "ad_tracking_enabled" : (bool) }, ... ], "apps" : [ { "name" : (string), "platform" : (string), "version" : (string), "sessions" : (string), "first_used" : (string) date, "last_used" : (string) date }, ... ], } ``` ### Sample output ``` json { "created_at" : "2020-07-10 15:00:00.000 UTC", "external_id" : "A8i3mkd99", "user_aliases" : [ { "alias_name" : "user_123", "alias_label" : "amplitude_id" } ], "braze_id": "5fbd99bac125ca40511f2cb1", "random_bucket" : 2365, "first_name" : "Jane", "last_name" : "Doe", "email" : "example@braze.com", "dob" : "1980-12-21", "home_city" : "Chicago", "country" : "US", "phone" : "+442071838750", "language" : "en", "time_zone" : "Eastern Time (US & Canada)", "last_coordinates" : [41.84157636433568, -87.83520818508256], "gender" : "F", "total_revenue" : 65, "attributed_campaign" : "braze_test_campaign_072219", "attributed_source" : "braze_test_source_072219", "attributed_adgroup" : "braze_test_adgroup_072219", "attributed_ad" : "braze_test_ad_072219", "custom_attributes": { "loyaltyId": "37c98b9d-9a7f-4b2f-a125-d873c5152856", "loyaltyPoints": "321", "loyaltyPointsNumber": 107 }, "custom_events": [ { "name": "Loyalty Acknowledgement", "first": "2021-06-28T17:02:43.032Z", "last": "2021-06-28T17:02:43.032Z", "count": 1 }, ... ], "purchases": [ { "name": "item_40834", "first": "2021-09-05T03:45:50.540Z", "last": "2022-06-03T17:30:41.201Z", "count": 10 }, ... ], "devices": [ { "model": "Pixel XL", "os": "Android (Q)", "carrier": null, "device_id": "312ef2c1-83db-4789-967-554545a1bf7a", "ad_tracking_enabled": true }, ... ], "apps": [ { "name": "MovieCannon", "platform": "Android", "version": "3.29.0", "sessions": 1129, "first_used": "2020-02-02T19:56:19.142Z", "last_used": "2021-11-11T00:25:19.201Z" }, ... ], } ``` requestBody: content: application/json: schema: type: object example: callback_endpoint: '' fields_to_export: - email - braze_id output_format: zip properties: callback_endpoint: type: string fields_to_export: type: array items: type: string output_format: 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' /messages/live_activity/update: post: tags: - Messaging > Live Activities summary: Update Live Activity description: >- > Use this endpoint to update and end [Live Activities](https://www.braze.com/docs/developer_guide/platform_integration_guides/swift/live_activities/live_activities/) displayed by your iOS app. This endpoint requires additional setup. To use this endpoint, youll need to generate an API key with the `messages.live_activity.update` permission. Before using this endpoint, you must register an activity with the Braze Swift SDK using the [`launchActivity`](https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class/launchactivity(pushtokentag:activity:fileid:line:)) method. Required request parameters will be defined during this step. Refer to [Live Activities](https://www.braze.com/docs/developer_guide/platform_integration_guides/swift/live_activities/live_activities/) for more information on registration. Once you have registered your activity, pass a JSON payload with updates to the Apple Push Notification service (APNs) through this endpoint. See Apples documentation on [updating your Live Activity with push notification payloads](https://developer.apple.com/documentation/activitykit/updating-and-ending-your-live-activity-with-activitykit-push-notifications) for more information. > **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits. ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `app_id` | Required | String | App [API identifier]({{site.baseurl}}/api/identifier_types/#the-app-identifier) retrieved from **Settings > Setup and Testing > API Keys.** | | `activity_id` | Required | String | When you register your Live Activity using [`launchActivity`](https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class), you use the `pushTokenTag` parameter to name the Activity's push token to a custom string.

Set `activity_id` to this custom string to define which Live Activity you want to update. | | `content_state` | Required | Object | You define the `ContentState` parameters when you create your Live Activity. Pass the updated values for your `ContentState` using this object.

The format of this request must match the shape you initially defined. | | `end_activity` | Optional | Boolean | If `true`, this request ends the Live Activity. | | `dismissal_date` | Optional | Datetime
([ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) string) | This parameter defines the time to remove the Live Activity from the user's UI. If this time is in the past, the Live Activity will be removed immediately. | | `stale_date` | Optional | Datetime
([ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) string) | This parameter tells the system when the Live Activity content is marked as outdated in the user's UI. | | `notification` | Optional | Object |







Include an [`apple_push`]({{site.baseurl}}/api/objects_filters/messaging/apple_object/) object to define a push notification. This behavior of this push notification depends on if the user is active or if the user is using a proxy device. {::nomarkdown}






| ## Response There are two status code responses for this endpoint: `201` and `4XX`. ### Example success response A `201` status code is returned if the request was formatted correctly and we received the request. The status code `201` could return the following response body. ``` json { "message": "success" } ``` ### Example error response The `4XX` class of status code indicates a client error. Refer to the [API errors and responses article]({{site.baseurl}}/api/errors/) for more information about errors you may encounter. The status code `400` could return the following response body. ``` json { "error": "\nProblem:\n message body does not match declared format\nResolution:\n when specifying application/json as content-type, you must pass valid application/json in the request's 'body' " } ``` requestBody: content: application/json: schema: type: object example: app_id: '{YOUR-APP-API-IDENTIFIER}' activity_id: live-activity-1 content_state: teamOneScore: 2 teamTwoScore: 4 end_activity: false dismissal_date: 2023-02-28T00:00:00+0000 stale_date: 2023-02-27T16:55:49+0000 notification: alert: body: It's halftime! Let's look at the scores title: Halftime properties: app_id: type: string activity_id: type: string content_state: type: object properties: teamOneScore: type: integer teamTwoScore: type: integer end_activity: type: boolean dismissal_date: type: string format: date-time stale_date: type: string format: date-time notification: type: object properties: alert: type: object properties: body: type: string title: 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' /messages/scheduled_broadcasts: get: tags: - Messaging > Schedule Mesages summary: List Upcoming Scheduled Campaigns and Canvases description: >- > Use this endpoint to return a JSON list of information about scheduled campaigns and entry Canvases between now and a designated `end_time` specified in the request. To use this endpoint, youll need to generate an API key with the `messages.schedule_broadcasts` permission. Daily, recurring messages will only appear once with their next occurrence. Results returned in this endpoint are only for campaigns and Canvases created and scheduled in Braze. ### Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "scheduled_broadcasts": [ { "name" (string) the name of the scheduled boradcast, "id" (stings) the Canvas or campaign identifier, "type" (string) the broadcast type either Canvas or Campaign, "tags" (array) an array of tag names formatted as strings, "next_send_time" (string) The next send time formatted in ISO 8601, may also include time zone if not local/intelligent delivery, "schedule_type" (string) The schedule type, either local_time_zones, intelligent_delivery or the name of your company's time zone, }, ] } ``` parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: end_time in: query schema: type: string description: >- (Required) String in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format End date of the range to retrieve upcoming scheduled Campaigns and Canvases. This is treated as midnight in UTC time by the API. example: '2018-09-01T00:00:00-04:00' responses: '200': 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' /messages/schedule/delete: post: tags: - Messaging > Schedule Mesages summary: Delete Scheduled Messages description: >- > Use this endpoint to cancel a message that you previously scheduled before it has been sent. To use this endpoint, youll need to generate an API key with the `messages.schedule.delete` permission. ### Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ### Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `schedule_id` | Required | String | The schedule_id to delete (obtained from the response to create schedule). | requestBody: content: application/json: schema: type: object example: schedule_id: schedule_identifier properties: schedule_id: 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' /canvas/trigger/schedule/delete: post: tags: - Messaging > Schedule Mesages summary: Delete Scheduled API-Triggered Canvases description: >- > Use this endpoint to cancel a Canvas message that you previously scheduled via API-triggered before it has been sent. To use this endpoint, youll need to generate an API key with the `canvas.trigger.schedule.delete` permission. Scheduled messages or triggers that are deleted very close to or during the time they were supposed to be sent will be updated with best efforts, so last-second deletions could be applied to all, some, or none of your targeted users. ### Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `canvas_id` | Required | String | See [Canvas identifier](https://braze.com/docs/api/identifier_types/). | | `schedule_id` | Required | String | The `schedule_id` to delete (obtained from the response to create schedule). | requestBody: content: application/json: schema: type: object example: canvas_id: canvas_identifier schedule_id: schedule_identifier properties: canvas_id: type: string schedule_id: 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' /campaigns/trigger/schedule/delete: post: tags: - Messaging > Schedule Mesages summary: Delete Scheduled API Triggered Campaigns description: >- > The delete schedule endpoint allows you to cancel a message that you previously scheduled API-triggered Canvases before it has been sent. To use this endpoint, youll need to generate an API key with the `campaigns.trigger.schedule.delete` permission. Scheduled messages or triggers that are deleted very close to or during the time they were supposed to be sent will be updated with best efforts, so last-second deletions could be applied to all, some, or none of your targeted users. ### Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ### Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `campaign_id` | Required | String | See [campaign identifier](https://www.braze.com/docs/api/identifier_types/). | | `schedule_id` | Required | String | The `schedule_id` to delete (obtained from the response to create schedule). | requestBody: content: application/json: schema: type: object example: campaign_id: campaign_identifier schedule_id: schedule_identifier properties: campaign_id: type: string schedule_id: 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' /messages/schedule/create: post: tags: - Messaging > Schedule Mesages summary: Create Scheduled Messages description: >- > Use this endpoint to schedule a campaign, Canvas, or other message to be sent at a designated time (up to 90 days in the future) and provides you with an identifier to reference that message for updates. To use this endpoint, youll need to generate an API key with the `messages.schedule.create` permission. If you are targeting a segment, a record of your request will be stored in the [Developer Console](https://dashboard.braze.com/app_settings/developer_console/activitylog/) after all scheduled messages have been sent. ### Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). Braze endpoints support [batching API requests](https://www.braze.com/docs/api/api_limits/#batching-api-requests). A single request to the messaging endpoints can reach any of the following: - Up to 50 specific external_ids, each with individual message parameters - A segment of any size created in the Braze dashboard, specified by its `segment_id` - An ad-hoc audience segment of any size, defined in the request as a [Connected Audience](https://www.braze.com/docs/api/objects_filters/connected_audience/) object ### Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `broadcast` | Optional | Boolean | See [broadcast](https://www.braze.com/docs/api/parameters/#broadcast). This parameter defaults to false (as of August 31, 2017).

If `recipients` is omitted, `broadcast` must be set to true. However, use caution when setting `broadcast: true`, as unintentionally setting this flag may cause you to send your message to a larger than expected audience. | | `external_user_ids` | Optional | Array of strings | See [external user identifier](https://www.braze.com/docs/api/parameters/#external-user-id). | | `user_aliases` | Optional | Array of user alias objects | See [user alias object](https://www.braze.com/docs/api/objects_filters/user_alias_object/). | | `audience` | Optional | Connected audience object | See [connected audience](https://www.braze.com/docs/api/objects_filters/connected_audience/). | | `segment_id` | Optional | String | See [segment identifier](https://www.braze.com/docs/api/identifier_types/). | | `campaign_id` | Required | String | See [campaign identifier](https://www.braze.com/docs/api/identifier_types/). | | `recipients` | Optional | Array of recipients objects | See [recipients object](https://www.braze.com/docs/api/objects_filters/recipient_object/). | | `send_id` | Optional | String | See [send identifier](https://www.braze.com/docs/api/identifier_types/). | | `override_messaging_limits` | Optional | Boolean | Ignore global rate limits for campaigns, defaults to false | | `recipient_subscription_state` | Optional | String | Use this to send messages to only users who have opted in (`opted_in`), only users who have subscribed or are opted in (`subscribed`) or to all users, including unsubscribed users (`all`).

Using `all` users is useful for transactional email messaging. Defaults to `subscribed`. | | `schedule` | Required | Schedule object | See [schedule object](https://www.braze.com/docs/api/objects_filters/schedule_object/) | | `messages` | Optional | Messaging object | See available [messaging objects](https://www.braze.com/docs/api/objects_filters/#messaging-objects). | ## Response ### Example success response ``` json { "dispatch_id": (string) the dispatch identifier, "schedule_id": (string) the schedule identifier, "message": "success" } ``` requestBody: content: application/json: schema: type: object example: broadcast: false external_user_ids: external_user_identifiers user_aliases: alias_name: example_name alias_label: example_label segment_id: segment_identifiers audience: AND: - custom_attribute: custom_attribute_name: eye_color comparison: equals value: blue - custom_attribute: custom_attribute_name: favorite_foods comparison: includes_value value: pizza - OR: - custom_attribute: custom_attribute_name: last_purchase_time comparison: less_than_x_days_ago value: 2 - push_subscription_status: comparison: is value: opted_in - email_subscription_status: comparison: is_not value: subscribed - last_used_app: comparison: after value: 2019-07-22T13:17:55+0000 campaign_id: campaign_identifier send_id: send_identifier override_messaging_limits: false recipient_subscription_state: subscribed schedule: time: '' in_local_time: true at_optimal_time: true messages: apple_push: {} android_push: {} windows_push: {} windows8_push: {} kindle_push: {} web_push: {} email: {} webhook: {} content_card: {} properties: broadcast: type: boolean external_user_ids: type: string user_aliases: type: object properties: alias_name: type: string alias_label: type: string segment_id: type: string audience: type: object properties: AND: type: array items: type: object campaign_id: type: string send_id: type: string override_messaging_limits: type: boolean recipient_subscription_state: type: string schedule: type: object properties: time: type: string in_local_time: type: boolean at_optimal_time: type: boolean messages: type: object properties: apple_push: type: object android_push: type: object windows_push: type: object windows8_push: type: object kindle_push: type: object web_push: type: object email: type: object webhook: type: object content_card: type: object 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' /campaigns/trigger/schedule/create: post: tags: - Messaging > Schedule Mesages summary: Schedule API Triggered Campaigns description: >- > Use this endpoint to send dashboard created campaign messages (up to 90 days in advance) via API-triggered delivery, allowing you to decide what action should trigger the message to be sent. To use this endpoint, youll need to generate an API key with the `campaigns.trigger.schedule.create` permission. You can pass in `trigger_properties` that will be templated into the message itself. Note that to send messages with this endpoint, you must have a [Campaign ID](https://www.braze.com/docs/api/identifier_types/), created when you build an [API-Triggered Campaign](https://www.braze.com/docs/api/api_campaigns/). ### Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). Braze endpoints support [batching API requests](https://www.braze.com/docs/api/api_limits/#batching-api-requests). A single request to the messaging endpoints can reach any of the following: - Up to 50 specific external_ids, each with individual message parameters - A segment of any size created in the Braze dashboard, specified by its `segment_id` - An ad-hoc audience segment of any size, defined in the request as a [Connected Audience](https://www.braze.com/docs/api/objects_filters/connected_audience/) object ### Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `campaign_id` | Required | String | See [campaign identifier](https://www.braze.com/docs/api/identifier_types/) | | `send_id` | Optional | String | See [send identifier](https://www.braze.com/docs/api/identifier_types/). | | `recipients` | Optional | Array of recipient objects | See [recipients object](https://www.braze.com/docs/api/objects_filters/recipient_object/). | | `audience` | Optional | Connected audience object | See [connected audience](https://www.braze.com/docs/api/objects_filters/connected_audience/). | | `broadcast` | Optional | Boolean | See [broadcast](https://www.braze.com/docs/api/parameters/#broadcast). This parameter defaults to false (as of August 31, 2017).

If `recipients` is omitted, `broadcast` must be set to true. However, use caution when setting `broadcast: true`, as unintentionally setting this flag may cause you to send your message to a larger than expected audience. | | `trigger_properties` | Optional | Object | Personalization key-value pairs for all users in this send. See [trigger properties](https://www.braze.com/docs/api/objects_filters/trigger_properties_object/). | | `schedule` | Required | Schedule object | See [schedule object](https://www.braze.com/docs/api/objects_filters/schedule_object/). | ## Response ### Example success response ``` json Content-Type: application/json Authorization: Bearer YOUR-API-KEY-HERE { { "dispatch_id": "dispatch_identifier", "schedule_id": "schedule_identifier", "message": "success" } ``` requestBody: content: application/json: schema: type: object example: campaign_id: campaign_identifier send_id: send_identifier recipients: - user_alias: example_alias external_user_id: external_user_identifier trigger_properties: {} audience: AND: - custom_attribute: custom_attribute_name: eye_color comparison: equals value: blue - custom_attribute: custom_attribute_name: favorite_foods comparison: includes_value value: pizza - OR: - custom_attribute: custom_attribute_name: last_purchase_time comparison: less_than_x_days_ago value: 2 - push_subscription_status: comparison: is value: opted_in - email_subscription_status: comparison: is_not value: subscribed - last_used_app: comparison: after value: 2019-07-22T13:17:55+0000 broadcast: false trigger_properties: {} schedule: time: '' in_local_time: false at_optimal_time: false properties: campaign_id: type: string send_id: type: string recipients: type: array items: type: object properties: user_alias: type: string external_user_id: type: string trigger_properties: type: object audience: type: object properties: AND: type: array items: type: object broadcast: type: boolean trigger_properties: type: object schedule: type: object properties: time: type: string in_local_time: type: boolean at_optimal_time: type: boolean 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' /canvas/trigger/schedule/create: post: tags: - Messaging > Schedule Mesages summary: Schedule API Triggered Canvases description: >- > Use this endpoint to schedule Canvas messages (up to 90 days in advance) via API-triggered delivery, allowing you to decide what action should trigger the message to be sent. To use this endpoint, youll need to generate an API key with the `canvas.trigger.schedule.create` permission. You can pass in `canvas_entry_properties` that will be templated into the messages sent by the first steps of the Canvas. Note that to send messages with this endpoint, you must have a [Canvas ID](https://www.braze.com/docs/api/identifier_types/#canvas-api-identifier) created when you build a Canvas. ### Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). Braze endpoints support [batching API requests](https://www.braze.com/docs/api/api_limits/#batching-api-requests). A single request to the messaging endpoints can reach any of the following: - Up to 50 specific external_ids, each with individual message parameters - A segment of any size created in the Braze dashboard, specified by its `segment_id` - An ad-hoc audience segment of any size, defined in the request as a [Connected Audience](https://www.braze.com/docs/api/objects_filters/connected_audience/) object ### Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `canvas_id` | Required | String | See [Canvas identifier](https://www.braze.com/docs/api/identifier_types/). | | `send_id` | Optional | String | See [send identifier](https://www.braze.com/docs/api/identifier_types/). | | `recipients` | Optional | Array of recipient objects | See [recipients object](https://www.braze.com/docs/api/objects_filters/recipient_object/). | | `audience` | Optional | Connected audience object | See [connected audience](https://www.braze.com/docs/api/objects_filters/connected_audience/). | | `broadcast` | Optional | Boolean | See [broadcast](https://www.braze.com/docs/api/parameters/#broadcast). This parameter defaults to false (as of August 31, 2017).

If `recipients` is omitted, `broadcast` must be set to true. However, use caution when setting `broadcast: true`, as unintentionally setting this flag may cause you to send your message to a larger than expected audience. | | `trigger_properties` | Optional | Object | Personalization key-value pairs for all users in this send. See [trigger properties](https://www.braze.com/docs/api/objects_filters/trigger_properties_object/). | | `schedule` | Required | Schedule object | See [schedule object](https://www.braze.com/docs/api/objects_filters/schedule_object/). | requestBody: content: application/json: schema: type: object example: canvas_id: canvas_identifier recipients: - user_alias: example_alias external_user_id: external_user_identifier trigger_properties: {} canvas_entry_properties: {} audience: AND: - custom_attribute: custom_attribute_name: eye_color comparison: equals value: blue - custom_attribute: custom_attribute_name: favorite_foods comparison: includes_value value: pizza - OR: - custom_attribute: custom_attribute_name: last_purchase_time comparison: less_than_x_days_ago value: 2 - push_subscription_status: comparison: is value: opted_in - email_subscription_status: comparison: is_not value: subscribed - last_used_app: comparison: after value: 2019-07-22T13:17:55+0000 broadcast: false canvas_entry_properties: {} schedule: time: '' in_local_time: false at_optimal_time: false properties: canvas_id: type: string recipients: type: array items: type: object properties: user_alias: type: string external_user_id: type: string trigger_properties: type: object canvas_entry_properties: type: object audience: type: object properties: AND: type: array items: type: object broadcast: type: boolean canvas_entry_properties: type: object schedule: type: object properties: time: type: string in_local_time: type: boolean at_optimal_time: type: boolean 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' /messages/schedule/update: post: tags: - Messaging > Schedule Mesages summary: Update Scheduled Messages description: >- > Use this endpoint to update scheduled messages. To use this endpoint, youll need to generate an API key with the `messages.schedule.update` permission. This endpoint accepts updates to either the `schedule` or `messages` parameter or both. Your request must contain at least one of those two keys. ### Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ### Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `schedule_id` | Required | String | The `schedule_id` to update (obtained from the response to create schedule). | | `schedule` | Optional | Object | See [schedule object](https://www.braze.com/docs/api/objects_filters/schedule_object/). | | `messages` | Optional | Object | See available [message objects](https://www.braze.com/docs/api/objects_filters/#messaging-objects). | requestBody: content: application/json: schema: type: object example: schedule_id: schedule_identifier schedule: time: '2017-05-24T20:30:36Z' messages: apple_push: alert: Updated Message! badge: 1 android_push: title: Updated title! alert: Updated message! sms: subscription_group_id: subscription_group_identifier message_variation_id: message_variation_identifier body: This is my SMS body. app_id: app_identifier properties: schedule_id: type: string schedule: type: object properties: time: type: string format: date-time messages: type: object properties: apple_push: type: object properties: alert: type: string badge: type: integer android_push: type: object properties: title: type: string alert: type: string sms: type: object properties: subscription_group_id: type: string message_variation_id: type: string body: type: string app_id: 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' /campaigns/trigger/schedule/update: post: tags: - Messaging > Schedule Mesages summary: Update Scheduled API Triggered Campaigns description: >- > Use this endpoint to update scheduled API-triggered campaigns created in the dashboard, allowing you to decide what action should trigger the message to be sent. To use this endpoint, youll need to generate an API key with the `campaigns.trigger.schedule.update` permission. You can pass in `trigger_properties` that will be templated into the message itself. Note that to send messages with this endpoint, you must have a campaign ID, created when you build an [API-triggered campaign](https://www.braze.com/docs/api/api_campaigns/). Any schedule will completely overwrite the one that you provided in the create schedule request or in previous update schedule requests. For example, if you originally provide `"schedule" : {"time" : "2015-02-20T13:14:47", "in_local_time" : true}` and then in your update you provide `"schedule" : {"time" : "2015-02-20T14:14:47"}`, your message will now be sent at the provided time in UTC, not in the user's local time. Scheduled triggers that are updated very close to or during the time they were supposed to be sent will be updated with best efforts, so last-second changes could be applied to all, some, or none of your targeted users. ### Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ### Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `campaign_id` | Required | String | See [campaign identifier](https://www.braze.com/docs/api/identifier_types/) | | `schedule_id` | Optional | String | The `schedule_id` to update (obtained from the response to create schedule). | | `schedule` | Required | Object | See [schedule object](https://www.braze.com/docs/api/objects_filters/schedule_object/). | requestBody: content: application/json: schema: type: object example: campaign_id: campaign_identifier schedule_id: schedule_identifier schedule: time: '2017-05-24T21:30:00Z' in_local_time: true properties: campaign_id: type: string schedule_id: type: string schedule: type: object properties: time: type: string format: date-time in_local_time: type: boolean 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' /canvas/trigger/schedule/update: post: tags: - Messaging > Schedule Mesages summary: Update Scheduled API Triggered Canvases description: >- > Use this endpoint to update scheduled API-triggered Canvases that were created in the dashboard. To use this endpoint, youll need to generate an API key with the `canvas.trigger.schedule.update` permission. This allows you to decide what action should trigger the message to be sent. You can pass in `trigger_properties` that will be templated into the message itself. Note that to send messages with this endpoint, you must have a Canvas ID, created when you build a [Canvas](https://www.braze.com/docs/api/identifier_types/#canvas-api-identifier). Any schedule will completely overwrite the one that you provided in the create schedule request or in previous update schedule requests. For example, if you originally provide `"schedule" : {"time" : "2015-02-20T13:14:47", "in_local_time" : true}` and then in your update you provide `"schedule" : {"time" : "2015-02-20T14:14:47"}`, your message will now be sent at the provided time in UTC, not in the user's local time. Scheduled triggers that are updated very close to or during the time they were supposed to be sent will be updated with best efforts, so last-second changes could be applied to all, some, or none of your targeted users. ### Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ### Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `canvas_id` | Required | String | See [Canvas identifier](https://www.braze.com/docs/api/identifier_types/). | | `schedule_id` | Optional | String | The `schedule_id` to update (obtained from the response to create schedule). | | `schedule` | Required | Object | See [schedule object](https://www.braze.com/docs/api/objects_filters/schedule_object/). | requestBody: content: application/json: schema: type: object example: canvas_id: canvas_identifier schedule_id: schedule_identifier schedule: time: '2017-05-24T21:30:00Z' in_local_time: true properties: canvas_id: type: string schedule_id: type: string schedule: type: object properties: time: type: string format: date-time in_local_time: type: boolean 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' /sends/id/create: post: tags: - Messaging > Send Messages summary: Create Send IDs For Message Send Tracking description: >- > Use this endpoint to create send IDs that can be used to send messages and track message performance programatically, without campaign creation for each send. To use this endpoint, youll need to generate an API key with the `sends.id.create` permission. Using the send identifier to track and send messages is useful if you are planning to programmatically generate and send content. ## Rate limit The daily maximum number of custom send identifiers that can be created via this endpoint is 100 for a given app group. Each `send_id` and `campaign_id` combination that you create will count towards your daily limit. The response headers for any valid request include the current rate limit status, see [API rate limits](https://www.braze.com/docs/api/api_limits/) for details. ### Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `campaign_id` | Required | String | See [campaign identifier]({{site.baseurl}}/api/identifier_types/). | | `send_id` | Optional | String | See [send identifier]({{site.baseurl}}/api/identifier_types/). | ## Response ### Example success response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "message": "success", "send_id" : (string) the send identifier } ``` requestBody: content: application/json: schema: type: object example: campaign_id: campaign_identifier send_id: send_identifier properties: campaign_id: type: string send_id: 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' /messages/send: post: tags: - Messaging > Send Messages summary: Send Messages Immediately via API Only description: >- > Use this endpoint to send immediate, ad-hoc messages to designated users via the Braze API. To use this endpoint, youll need to generate an API key with the `messages.send` permission. Be sure to include Messaging Objects in your body to complete your requests. If you are targeting a segment, a record of your request will be stored in the [Developer Console](https://dashboard.braze.com/app_settings/developer_console/activitylog/). ## Rate limit When specifying a segment or Connected Audience in your request, we apply a rate limit of 250 requests per minute to this endpoint. Otherwise, if specifying an `external_id`, this endpoint has a default rate limit of 250,000 requests per hour, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). Braze endpoints support [batching API requests](https://www.braze.com/docs/api/api_limits/#batching-api-requests). A single request to the messaging endpoints can reach any of the following: - Up to 50 specific `external_ids`, each with individual message parameters - A segment of any size created in the Braze dashboard, specified by its `segment_id` - An ad-hoc audience segment of any size, defined in the request as a [Connected Audience](https://www.braze.com/docs/api/objects_filters/connected_audience/) object ### Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `broadcast` | Optional | Boolean | See [broadcast](https://www.braze.com/docs/api/parameters/#broadcast). This parameter defaults to false (as of August 31, 2017).

If `recipients` is omitted, `broadcast` must be set to true. However, use caution when setting `broadcast: true`, as unintentionally setting this flag may cause you to send your messages to a larger than expected audience. | | `external_user_ids` | Optional | Array of strings | See [external user ID](https://www.braze.com/docs/api/parameters/#external-user-id). | | `user_aliases` | Optional | Array of user alias objects | See [user alias object](https://www.braze.com/docs/api/objects_filters/user_alias_object/). | | `segment_id` | Optional | String | See [segment identifier](https://www.braze.com/docs/api/identifier_types/). | | `audience` | Optional | Connected audience object | See [connected audience](https://www.braze.com/docs/api/objects_filters/connected_audience/). | | `campaign_id` | Optional\* | String | See [campaign identifier](https://www.braze.com/docs/api/identifier_types/) for more information.

\*Required if you wish to track campaign stats (e.g. sends, clicks, bounces, etc) on the Braze dashboard. | | `send_id` | Optional | String | See [send identifier](https://www.braze.com/docs/api/identifier_types/) | | `override_frequency_capping` | Optional | Boolean | Ignore \`frequency_capping\` for campaigns, defaults to false. | | `recipient_subscription_state` | Optional | String | Use this to send messages to only users who have opted in (`opted_in`), only users who have subscribed or are opted in (`subscribed`) or to all users, including unsubscribed users (`all`).

Using `all` users is useful for transactional email messaging. Defaults to `subscribed`. | | `messages` | Optional | Messaging objects | See available [messaging objects](https://www.braze.com/docs/api/endpoints/messaging/send_messages/post_send_messages/#available-messaging-objects). | ## Response details Message sending endpoint responses will include the messages `dispatch_id` for reference back to the dispatch of the message. The `dispatch_id` is the id of the message dispatch (unique id for each transmission sent from the Braze platform). For more, information refer to [Dispatch ID behavior](https://www.braze.com/docs/help/help_articles/data/dispatch_id/). requestBody: content: application/json: schema: type: object example: broadcast: 'false' external_user_ids: external_user_identifiers user_aliases: alias_name: example_name alias_label: example_label segment_id: segment_identifier audience: AND: - custom_attribute: custom_attribute_name: eye_color comparison: equals value: blue - custom_attribute: custom_attribute_name: favorite_foods comparison: includes_value value: pizza - OR: - custom_attribute: custom_attribute_name: last_purchase_time comparison: less_than_x_days_ago value: 2 - push_subscription_status: comparison: is value: opted_in - email_subscription_status: comparison: is_not value: subscribed - last_used_app: comparison: after value: 2019-07-22T13:17:55+0000 campaign_id: campaign_identifier send_id: send_identifier override_frequency_capping: 'false' recipient_subscription_state: all messages: android_push: (optional, Android Push Object) apple_push: (optional, Apple Push Object) content_card: (optional, Content Card Object) email: (optional, Email Object) kindle_push: (optional, Kindle/FireOS Push Object) web_push: (optional, Web Push Object) windows_phone8_push: (optional, Windows Phone 8 Push Object) windows_universal_push: (optional, Windows Universal Push Object) properties: broadcast: type: string external_user_ids: type: string user_aliases: type: object properties: alias_name: type: string alias_label: type: string segment_id: type: string audience: type: object properties: AND: type: array items: type: object campaign_id: type: string send_id: type: string override_frequency_capping: type: string recipient_subscription_state: type: string messages: type: object properties: android_push: type: string apple_push: type: string content_card: type: string email: type: string kindle_push: type: string web_push: type: string windows_phone8_push: type: string windows_universal_push: 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' /transactional/v1/campaigns/{campaign_id}/send: post: tags: - Messaging > Send Messages summary: Send Transactional Email via API Triggered Delivery description: >- > Use this endpoint to send immediate, ad-hoc transactional messages to a designated user. To use this endpoint, youll need to generate an API key with the `transactional.send` permission. This endpoint is used alongside the creation of a [Transactional Email campaign](https://www.braze.com/docs/api/api_campaigns/transactional_campaigns) and corresponding campaign ID. > **Important:** Transactional Email is currently available as part of select Braze packages. Reach out to your Braze customer success manager for more details. Similar to the [Send triggered campaign endpoint](https://www.braze.com/docs/api/endpoints/messaging/send_messages/post_send_triggered_campaigns/), this campaign type allows you to house message content inside of the Braze dashboard while dictating when and to whom a message is sent via your API. Unlike the Send triggered campaign endpoint, which accepts an audience or segment to send messages to, a request to this endpoint must specify a single user either by `external_user_id` or `user_alias`, as this campaign type is purpose-built for 1:1 messaging of alerts like order confirmations or password resets. ## Rate limit Transactional Emails are not subject to a rate limit. Depending on your chosen package, a set number of Transactional Emails is covered per hour by SLA. Requests that exceed that rate will still send, but are not covered by SLA. 99.9% of emails will send in less than one minute. ## Path parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `campaign_id` | Required | String | ID of the campaign | ## Request Parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `external_send_id` | Optional | String | A Base64 compatible string. Validated against the following regex `/^[a-zA-Z0-9-_+\/=]+$/`. This optional field allows you to pass an internal identifier for this particular send which will be included in events sent from the Transactional HTTP event postback. When passed, this identifier will also be used as a deduplication key, which Braze will store for 24 hours. Passing the same identifier in another request will not result in a new instance of a send by Braze for 24 hours. | | `trigger_properties` | Optional | Object | See [trigger properties](https://www.braze.com/docs/api/objects_filters/trigger_properties_object/). Personalization key-value pairs that will apply to the user in this request. | | `recipients` | Required | Object | The user you are targeting this message to. Can contain `attributes` and a single `external_user_id` or `user_alias`.

Note that if you provide an external user ID that doesnt already exist in Braze, passing any fields to the `attributes` object will create this user profile in Braze and send this message to the newly created user.

If you send multiple requests to the same user with different data in the `attributes` object, Braze will ensure that `first_name`, `last_name`, and `email` attributes will be updated synchronously and templated into your message. Custom attributes dont have this same protection, so proceed with caution when updating a user through this API and passing different custom attribute values in quick succession. | ## Response The send transactional email endpoint will respond with the messages `dispatch_id` which represents the instance of this message send. This identifier can be used along with events from the Transactional HTTP event postback to trace the status of an individual email sent to a single user. ### Example response ``` json { "dispatch_id": Out-of-the-box generated Unique ID of the instance of this send "status": Current status of the message "metadata": Object containing additional information about the send instance } ``` ## Troubleshooting The endpoint may also return an error code and a human-readable message in some cases, most of which are validation errors. Here are some common errors you may get when making invalid requests. | Error | Troubleshooting | | --- | --- | | `The campaign is not a transactional campaign. Only transactional campaigns may use this endpoint` | The campaign ID provided is not for a transactional campaign. | | `The external reference has been queued. Please retry to obtain send_id.` | The external_send_id has been created recently, try a new external_send_id if you are intending to send a new message. | | `Campaign does not exist` | The campaign ID provided does not correspond to an existing campaign. | | `The campaign is archived. Unarchive the campaign to ensure trigger requests will take effect.` | The campaign ID provided corresponds to an archived campaign. | | `The campaign is paused. Resume the campaign to ensure trigger requests will take effect.` | The campaign ID provided corresponds to a paused campaign. | | `campaign_id must be a string of the campaign api identifier` | The campaign ID provided is not a valid format. | | `Error authenticating credentials` | The API key provided is invalid | | `Invalid whitelisted IPs` | The IP address sending the request is not on the IP whitelist (if it is being utilized) | | `You do not have permission to access this resource` | The API key used does not have permission to take this action | Most endpoints at Braze have a rate limit implementation that will return a 429 response code if you have made too many requests. The transactional sending endpoint works differently -- if you exceed your allotted rate limit, our system will continue to ingest the API calls, return success codes, and send the messages, however those messages may not be subject to the contractual SLA for the feature. Please reach out if you need more information about this functionality. ## Transactional HTTP Event Postback All transactional emails are complemented with event status postbacks sent as an HTTP request back to your specified URL. This will allow you to evaluate the message status in real-time and take action to reach the user on another channel if the message goes undelivered, or fallback to an internal system if Braze is experiencing latency. In order to associate the incoming events to a particular instance of send, you can choose to either capture and store the Braze `dispatch_id` returned in the [API response](https://www.braze.com/docs/api/endpoints/messaging/send_messages/post_send_transactional_message/#example-response), or pass your own identifier to the `external_send_id` field. An example of a value you may choose to pass to that field may be an order ID, where after completing order 1234, an order confirmation message is triggered to the user through Braze, and `external_send_id : 1234` is included in the request. All following event postbacks such as `Sent` and `Delivered` will include `external_send_id : 1234` in the payload allowing you to confirm that user successfully received their order confirmation email. To get started using the Transactional HTTP Event Postback, navigate to **Settings** > **Workspace Settings** > **Email Preferences**. in your Braze dashboard and input your desired URL to receive postbacks. Note: If you are using our [older navigation](https://www.braze.com/docs/navigation), **Email Preferences** can be found at ****Manage Settings** > **Email Settings****. ### Postback body ``` json // Sent Event { "dispatch_id": "acf471119f7449d579e8089032003ded", "status": "sent", "metadata": { "received_at": "2020-08-31T18:58:41.000+00:00", "enqueued_at": "2020-08-31T18:58:41.000+00:00", "executed_at": "2020-08-31T18:58:41.000+00:00", "sent_at": "2020-08-31T18:58:42.000+00:00", "campaign_api_id": "417220e4-5a2a-b634-7f7d-9ec891532368", "external_send_id" : "34a2ceb3cf6184132f3d816e9984269a" } } // Processed Event { "dispatch_id": "acf471119f7449d579e8089032003ded", "status": "processed", "metadata": { "processed_at": "2020-08-31T18:58:42.000+00:00", "campaign_api_id": "417220e4-5a2a-b634-7f7d-9ec891532368", "external_send_id" : "34a2ceb3cf6184132f3d816e9984269a" } } // Aborted { "dispatch_id": "acf471119f7449d579e8089032003ded", "status": "aborted", "metadata": { "reason": "User not emailable", "aborted_at": "2020-08-31T19:04:51.000+00:00", "campaign_api_id": "417220e4-5a2a-b634-7f7d-9ec891532368", "external_send_id" : "34a2ceb3cf6184132f3d816e9984269a" } } // Delivered Event { "dispatch_id": "acf471119f7449d579e8089032003ded", "status": "delivered", "metadata": { "delivered_at": "2020-08-31T18:27:32.000+00:00", "campaign_api_id": "417220e4-5a2a-b634-7f7d-9ec891532368", "external_send_id" : "34a2ceb3cf6184132f3d816e9984269a" } } // Bounced Event { "dispatch_id": "acf471119f7449d579e8089032003ded", "status": "bounced", "metadata": { "bounced_at": "2020-08-31T18:58:43.000+00:00", "reason": "550 5.1.1 The email account that you tried to reach does not exist", "campaign_api_id": "417220e4-5a2a-b634-7f7d-9ec891532368", "external_send_id" : "34a2ceb3cf6184132f3d816e9984269a" } } ``` #### Message status | **Status** | **Description** | | --- | --- | | `sent` | Message successfully dispatched to Brazes email sending partner | | `processed` | Email sending partner has successfully received and prepared the message for sending to the users inbox provider | | `aborted` | Braze was unable to successfully dispatch the message due to the user not having an emailable address, or Liquid abort logic was called in the message body. All aborted events include a reason field within the metadata object indicating why the message was aborted | | `delivered` | Message was accepted by the users email inbox provider | | `bounced` | Message was rejected by the users email inbox provider. All bounced events include a reason field within the metadata object reflecting the bounce error code provided by the inbox provider | ### Example postback ``` json // Sent Event { "dispatch_id": "acf471119f7449d579e8089032003ded", "status": "sent", "metadata": { "received_at": "2020-08-31T18:58:41.000+00:00", "enqueued_at": "2020-08-31T18:58:41.000+00:00", "executed_at": "2020-08-31T18:58:41.000+00:00", "sent_at": "2020-08-31T18:58:42.000+00:00", "campaign_api_id": "417220e4-5a2a-b634-7f7d-9ec891532368", "external_send_id" : "34a2ceb3cf6184132f3d816e9984269a" } } // Processed Event { "dispatch_id": "acf471119f7449d579e8089032003ded", "status": "processed", "metadata": { "processed_at": "2020-08-31T18:58:42.000+00:00", "campaign_api_id": "417220e4-5a2a-b634-7f7d-9ec891532368", "external_send_id" : "34a2ceb3cf6184132f3d816e9984269a" } } // Aborted { "dispatch_id": "acf471119f7449d579e8089032003ded", "status": "aborted", "metadata": { "reason": "User not emailable", "aborted_at": "2020-08-31T19:04:51.000+00:00", "campaign_api_id": "417220e4-5a2a-b634-7f7d-9ec891532368", "external_send_id" : "34a2ceb3cf6184132f3d816e9984269a" } } // Delivered Event { "dispatch_id": "acf471119f7449d579e8089032003ded", "status": "delivered", "metadata": { "delivered_at": "2020-08-31T18:27:32.000+00:00", "campaign_api_id": "417220e4-5a2a-b634-7f7d-9ec891532368", "external_send_id" : "34a2ceb3cf6184132f3d816e9984269a" } } // Bounced Event { "dispatch_id": "acf471119f7449d579e8089032003ded", "status": "bounced", "metadata": { "bounced_at": "2020-08-31T18:58:43.000+00:00", "reason": "550 5.1.1 The email account that you tried to reach does not exist", "campaign_api_id": "417220e4-5a2a-b634-7f7d-9ec891532368", "external_send_id" : "34a2ceb3cf6184132f3d816e9984269a" } } ``` requestBody: content: application/json: schema: type: object example: external_send_id: YOUR_BASE64_COMPATIBLE_ID trigger_properties: example_string_property: YOUR_EXAMPLE_STRING example_integer_property: YOUR_EXAMPLE_INTEGER recipient: - external_user_id: TARGETED_USER_ID_STRING properties: external_send_id: type: string trigger_properties: type: object properties: example_string_property: type: string example_integer_property: type: string recipient: type: array items: type: object properties: external_user_id: 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}} - name: campaign_id in: path schema: type: string required: true 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' /campaigns/trigger/send: post: tags: - Messaging > Send Messages summary: Send Campaign Messages via API Triggered Delivery description: >- > Use this endpoint to send immediate, ad-hoc messages to designated users via API-triggered delivery. To use this endpoint, youll need to generate an API key with the `campaigns.trigger.send` permission. API-triggered delivery allows you to house message content inside of the Braze dashboard while dictating when a message is sent, and to whom via your API. If you are targeting a segment, a record of your request will be stored in the [Developer Console](https://dashboard.braze.com/app_settings/developer_console/activitylog/). Note that to send messages with this endpoint, you must have a [campaign ID](https://www.braze.com/docs/api/identifier_types/) created when you build an [API-triggered campaign](https://www.braze.com/docs/api/api_campaigns/). ## Rate limit When specifying a segment or Connected Audience in your request, we apply a rate limit of 250 requests per minute to this endpoint. Otherwise, if specifying an `external_id`, this endpoint has a default rate limit of 250,000 requests per hour, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). Braze endpoints support [batching API requests](https://www.braze.com/docs/api/api_limits/#batching-api-requests). A single request to the messaging endpoints can reach any of the following: - Up to 50 specific `external_ids`, each with individual message parameters - A segment of any size created in the Braze dashboard, specified by its `segment_id` - An ad-hoc audience segment of any size, defined in the request as a [Connected Audience](https://www.braze.com/docs/api/objects_filters/connected_audience/) object ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `campaign_id` | Required | String | See [campaign identifier](https://www.braze.com/docs/api/identifier_types/). | | `send_id` | Optional | String | See [send identifier](https://www.braze.com/docs/api/identifier_types/). | | `trigger_properties` | Optional | Object | See [trigger properties](https://www.braze.com/docs/api/objects_filters/trigger_properties_object/). Personalization key-value pairs that will apply to all users in this request. | | `broadcast` | Optional | Boolean | See [broadcast](https://www.braze.com/docs/api/parameters/#broadcast). This parameter defaults to false (as of August 31, 2017).

If `recipients` is omitted, `broadcast` must be set to true. However, use caution when setting `broadcast: true`, as unintentionally setting this flag may cause you to send your campaign to a larger than expected audience. | | `audience` | Optional | Connected audience object | See [connected audience](https://www.braze.com/docs/api/objects_filters/connected_audience/). | | `recipients` | Optional | Array | See [recipients object](https://www.braze.com/docs/api/objects_filters/recipient_object/). If not provided and `broadcast` is set to true, the message will send to the entire segment targeted by the campaign. | The recipients array may contain up to 50 objects, with each object containing a single `external_user_id` string and `trigger_properties` object. When `send_to_existing_only` is `true`, Braze will only send the message to existing users. When `send_to_existing_only` is `false` and a user with the given `id` does not exist, Braze will create a user with that id and attributes before sending the message. > Important: A users subscription group status can be updated via the inclusion of a subscription_groups parameter within the attributes object. This is currently in early access. Contact your Braze customer success manager if youre interested in participating in the early access. More details can be found in the [User attributes object](https://www.braze.com/docs/api/objects_filters/user_attributes_object). ## Response details Message sending endpoint responses will include the messages `dispatch_id` for reference back to the dispatch of the message. The `dispatch_id` is the ID of the message dispatch, a unique ID for each transmission sent from the Braze platform. When using this endpoint, you receive a single `dispatch_id` for an entire batched set of users. For more information on `dispatch_id` check out out our documentation on [Dispatch ID Behavior](https://www.braze.com/docs/help/help_articles/data/dispatch_id/). ## Create send endpoint **Using the attributes object in campaigns** Braze has a Messaging Object called `Attributes` that will allow you to add, create, or update attributes and values for a user before you send them an API-triggered campaigns using the `campaign/trigger/send` endpoint as this API call will process the User Attributes object before it processes and sends the campaign. This helps minimize the risk of there being issues caused by [race conditions](https://www.braze.com/docs/help/best_practices/race_conditions/). > **Important:** Looking for the Canvas version of this endpoint? Check out [Sending Canvas messages via API-triggered delivery](https://www.braze.com/docs/api/endpoints/messaging/send_messages/post_send_triggered_canvases/#create-send-endpoint). requestBody: content: application/json: schema: type: object example: campaign_id: campaign_identifier send_id: send_identifier trigger_properties: {} broadcast: false audience: AND: - custom_attribute: custom_attribute_name: eye_color comparison: equals value: blue - custom_attribute: custom_attribute_name: favorite_foods comparison: includes_value value: pizza - OR: - custom_attribute: custom_attribute_name: last_purchase_time comparison: less_than_x_days_ago value: 2 - push_subscription_status: comparison: is value: opted_in - email_subscription_status: comparison: is_not value: subscribed - last_used_app: comparison: after value: 2019-07-22T13:17:55+0000 recipients: - user_alias: alias_name: example_name alias_label: example_label external_user_id: external_user_identifier trigger_properties: {} send_to_existing_only: true attributes: first_name: Alex properties: campaign_id: type: string send_id: type: string trigger_properties: type: object broadcast: type: boolean audience: type: object properties: AND: type: array items: type: object recipients: type: array items: type: object properties: user_alias: type: object properties: alias_name: type: string alias_label: type: string external_user_id: type: string trigger_properties: type: object send_to_existing_only: type: boolean attributes: type: object properties: first_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' /canvas/trigger/send: post: tags: - Messaging > Send Messages summary: Send Canvas Messages via API Triggered Delivery description: >- > Use this endpoint to send Canvas messages via API-triggered delivery. To use this endpoint, youll need to generate an API key with the `canvas.trigger.send` permission. API-triggered delivery allows you to house message content inside of the Braze dashboard while dictating when a message is sent, and to whom via your API. Note that to send messages with this endpoint, you must have a [Canvas ID](https://www.braze.com/docs/api/identifier_types/#canvas-api-identifier) created when you build a Canvas. ## Rate limit When specifying a segment or Connected Audience in your request, we apply a rate limit of 250 requests per minute to this endpoint. Otherwise, if specifying an `external_id`, this endpoint has a default rate limit of 250,000 requests per hour, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). Braze endpoints support [batching API requests](https://www.braze.com/docs/api/api_limits/#batching-api-requests). A single request to the messaging endpoints can reach any of the following: - Up to 50 specific `external_ids`, each with individual message parameters - A segment of any size created in the Braze dashboard, specified by its `segment_id` - An ad-hoc audience segment of any size, defined in the request as a [Connected Audience](https://www.braze.com/docs/api/objects_filters/connected_audience/) object ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `canvas_id` | Required | String | See [Canvas identifier](https://www.braze.com/docs/api/identifier_types/). | | `canvas_entry_properties` | Optional | Object | See [Canvas entry properties](https://www.braze.com/docs/api/objects_filters/canvas_entry_properties_object/). Personalization key-value pairs that will apply to all users in this request. The Canvas entry properties object has a maximum size limit of 50 KB. | | `broadcast` | Optional | Boolean | You must set `broadcast` to true when sending a message to an entire segment that a campaign or Canvas targets. This parameter defaults to false (as of August 31, 2017).

If `broadcast` is set to true, a recipients list cannot be included. However, use caution when setting `broadcast: true`, as unintentionally setting this flag may cause you to send your message to a larger than expected audience. | | `audience` | Optional | Connected audience object | See [Connected audience](https://braze.com/docs/api/objects_filters/connected_audience/). | | `recipients` | Optional | Array | See [Recipients object](https://www.braze.com/docs/api/objects_filters/recipient_object/). If not provided and `broadcast` is set to true, the message will send to the entire segment targeted by the Canvas.

The `recipients` array may contain up to 50 objects, with each object containing a single `external_user_id` string and `canvas_entry_properties` object. Either `external_user_id` or user_alias is required for this call. Requests must specify only one.

When `send_to_existing_only` is true, Braze will only send the message to existing usershowever this flag cant be used with user aliases. When `send_to_existing_only` is `false` and a user with the given `id` does not exist, Braze will create a user with that ID and attributes before sending the message. | Customers using the API for server-to-server calls may need to whitelist the appropriate API URL if theyre behind a firewall. > **Note:** If you include both specific users in your API call and a target segment in the dashboard, the message will send to specifically the user profiles that are in the API call and qualify for the segment filters. ## Response details Message sending endpoint responses will include the messages `dispatch_id` for reference back to the dispatch of the message. The `dispatch_id` is the ID of the message dispatch (unique ID for each transmission sent from the Braze platform). Check out [Dispatch ID behavior](https://www.braze.com/docs/help/help_articles/data/dispatch_id/) for more information. ## Create send endpoint **Using the Attributes Object in Canvas** Braze has a Messaging Object called `Attributes` that allows you to add, create, or update attributes and values for a user before sending them an API-Triggered Canvas using the `canvas/trigger/send` endpoint as this API call will process the User Attributes object before it processes and sends the Canvas. This helps minimize the risk of there being issues caused by [race conditions](https://www.braze.com/docs/help/best_practices/race_conditions/). > **Important:** Looking for the camaigns version of this endpoint? Check out [Sending campaign messages via API-triggered delivery](https://www.braze.com/docs/api/endpoints/messaging/send_messages/post_send_triggered_campaigns/). requestBody: content: application/json: schema: type: object example: canvas_id: canvas_identifier canvas_entry_properties: product_name: shoes product_price: 79.99 broadcast: false audience: AND: - custom_attribute: custom_attribute_name: eye_color comparison: equals value: blue - custom_attribute: custom_attribute_name: favorite_foods comparison: includes_value value: pizza - OR: - custom_attribute: custom_attribute_name: last_purchase_time comparison: less_than_x_days_ago value: 2 - push_subscription_status: comparison: is value: opted_in - email_subscription_status: comparison: is_not value: subscribed - last_used_app: comparison: after value: 2019-07-22T13:17:55+0000 recipients: - user_alias: alias_name: example_name alias_label: example_label external_user_id: user_identifier trigger_properties: {} canvas_entry_properties: '' send_to_existing_only: true attributes: first_name: Alex properties: canvas_id: type: string canvas_entry_properties: type: object properties: product_name: type: string product_price: type: number broadcast: type: boolean audience: type: object properties: AND: type: array items: type: object recipients: type: array items: type: object properties: user_alias: type: object properties: alias_name: type: string alias_label: type: string external_user_id: type: string trigger_properties: type: object canvas_entry_properties: type: string send_to_existing_only: type: boolean attributes: type: object properties: first_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' /preference_center_v1/{PreferenceCenterExternalID}/url/{UserID}: get: tags: - Preference Center summary: Generate Preference Center URL description: >- > Use this endpoint to generate a URL for a preference center. To use this endpoint, youll need to generate an API key with the `preference_center.user.get` permission. Each preference center URL is unique to each user. ## Rate limit This endpoint has a rate limit of 1,000 requests per minute, per workspace. ## Path parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `preferenceCenterExternalID` | Required | String | The ID for your preference center. | | `userID` | Required | String | The user ID. | ## Example request ``` curl --location --request GET 'https://rest.iad-01.braze.com/preference_center/v1/$preference_center_external_id/url/$user_external_id' \ --header 'Authorization: Bearer YOUR-API-KEY-HERE' ``` ## Response ``` json { "preference_center_url": "https://www.example.com/preferences" } ``` parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: preference_center_api_id in: query schema: type: string example: '{{preference_center_api_id}}' - name: external_id in: query schema: type: string description: (Required) String example: '{{external_id}}' - name: PreferenceCenterExternalID in: path schema: type: string required: true - name: UserID in: path schema: type: string required: true responses: '200': 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' /preference_center/v1/list: get: tags: - Preference Center summary: List Preference Centers description: >- > Use this endpoint to list your available preference centers. To use this endpoint, youll need to generate an API key with the `preference_center.list` permission. ## Rate limit This endpoint has a rate limit of 1,000 requests per minute, per workspace. ## Path and request parameters There are no path or request parameters for this endpoint. ## Example request ``` curl --location -g --request GET https://rest.iad-01.braze.com/preference_center/v1/list \ --header 'Authorization: Bearer YOUR-REST-API-KEY' ``` ## Response ``` json { "preference_centers": [ { "name": "My Preference Center 1", "preference_center_api_id": "preference_center_api_id", "created_at": "2022-08-17T15:46:10Z", "updated_at": "2022-08-17T15:46:10Z" }, { "name": "My Preference Center 2", "preference_center_api_id": "preference_center_api_id", "created_at": "2022-08-19T11:13:06Z", "updated_at": "2022-08-19T11:13:06Z" }, { "name": "My Preference Center 3", "preference_center_api_id": "preference_center_api_id", "created_at": "2022-08-19T11:30:50Z", "updated_at": "2022-08-19T11:30:50Z" }, { "name": "My Preference Center 4", "preference_center_api_id": "preference_center_api_id", "created_at": "2022-09-13T20:41:34Z", "updated_at": "2022-09-13T20:41:34Z" } ] } ``` parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} responses: '200': 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' /preference_center/v1/{PreferenceCenterExternalID}: get: tags: - Preference Center summary: View Details for Preference Center description: >- > Use this endpoint to view the details for your preference centers, including when it was created and updated. To use this endpoint, youll need to generate an API key with the `preference_center.get` permission. ## Rate limit This endpoint has a rate limit of 1,000 requests per minute, per workspace. ## Path parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `preferenceCenterExternalID` | Required | String | The ID for your preference center. | ## Request parameters There are no request parameters for this endpoint. ## Example request ``` curl --location -g --request GET https://rest.iad-01.braze.com/preference_center/v1/preference_center_external_id \ --header 'Authorization: Bearer YOUR-REST-API-KEY' ``` ## Response ``` json { "name": "My Preference Center", "preference_center_api_id": "preference_center_api_id", "created_at": "example_time_created", "updated_at": "example_time_updated", "preference_center_title": "Example preference center title", "preference_center_page_html": "HTML for preference center here", "confirmation_page_html": "HTML for confirmation page here", "redirect_page_html": null, "preference_center_options": { "meta-viewport-content": "width=device-width, initial-scale=2" }, "state": "active" } ``` parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: PreferenceCenterExternalID in: path schema: type: string required: true responses: '200': 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' put: tags: - Preference Center summary: Update Preference Center description: >- > Use this endpoint to update a preference center. To use this endpoint, youll need to generate an API key with the `preference_center.update` permission. ## Rate limit This endpoint has a rate limit of 10 requests per minute, per workspace. ## Path parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `preferenceCenterExternalID` | Required | String | The ID for your preference center. | ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `preference_center_page_html` | Required | String | The HTML for the preference center page. | | `preference_center_title` | Optional | String | The title for the preference center and confirmation pages. If a title is not specified, the title of the pages will default to "Preference Center". | | `confirmation_page_html` | Required | String | The HTML for the confirmation page. | | `state` | Optional | String | Choose `active` or `draft`. | | `options` | Optional | Object | Attributes: `meta-viewport-content`. When present, a `viewport` meta tag will be added to the page with `content=` . | ## Example request ``` curl --location --request POST 'https://rest.iad-01.braze.com/preference_center/v1/{preferenceCenterExternalId}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR-API-KEY-HERE' \ --data-raw '{ "name": "Example", "preference_center_title": "Example Preference Center Title", "preference_center_page_html": "HTML for preference center here", "confirmation_page_html": "HTML here with a message to users here", "state": "active" } ' ``` ## Example response ``` { "preference_center_api_id": "8efc52aa-935e-42b7-bd6b-98f43bb9b0f1", "created_at": "2022-09-22T18:28:07Z", "updated_at": "2022-09-22T18:32:07Z", "message": "success" } ``` requestBody: content: application/json: schema: type: object example: external_send_id: YOUR_BASE64_COMPATIBLE_ID trigger_properties: example_string_property: YOUR_EXAMPLE_STRING example_integer_property: YOUR_EXAMPLE_INTEGER recipient: - external_user_id: TARGETED_USER_ID_STRING properties: external_send_id: type: string trigger_properties: type: object properties: example_string_property: type: string example_integer_property: type: string recipient: type: array items: type: object properties: external_user_id: 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}} - name: PreferenceCenterExternalID in: path schema: type: string required: true responses: '200': 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' /preference_center/v1: post: tags: - Preference Center summary: Create Preference Center description: >- > Use this endpoint to create a preference center to allow users to manage their notification preferences for email campaigns. To use this endpoint, youll need to generate an API key with the `preference_center.update` permission. Check out [Creating a preference center via API](https://www.braze.com/docs/user_guide/message_building_by_channel/email/preference_center/) for details on how to include this in your email campaigns. ## Rate limit This endpoint has a rate limit of 10 requests per minute, per workspace. ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `name` | Required | String | The name of the preference center that meets the following requirements:
\- Only contains letters, numbers, hyphens, and underscores
\- Does not have spaces | | `preference_center_title` | Optional | String | The title for the preference center and confirmation pages. If a title is not specified, the title of the pages will default to "Preference Center". | | `preference_center_page_html` | Required | String | The HTML for the preference center page. | | `confirmation_page_html` | Required | String | The HTML for the confirmation page. | | `state` | Optional | String | Choose `active` or `draft`. Defaults to `active` if not specified. | | `options` | Optional | Object | Attributes: `meta-viewport-content`. When present, a `viewport` meta tag will be added to the page with `content=` . | > **Note:** The preference center name can't be edited once created. ### Liquid tags Refer to the following Liquid tags that can be included in your HTML to generate a user's subscription state on the preference center page. #### User subscription state | Liquid | Description | | --- | --- | | `{{subscribed_state.${email_global}}}` | Get the global email subscribed state for the user (i.e., "opted_in", "subscribed", or "unsubscribed". | | `{{subscribed_state.${}}}` | Get the subscribed state of the specified subscription group for the user (i.e., "subscribed" or "unsubscribed"). | #### Form inputs and action | Liquid | Description | | --- | --- | | `{% form_field_name :email_global_state %}` | Indicates that a specific form input element corresponds to the user's global email subscribed state. The user's selection state should be "opted_in", "subscribed", or "unsubscribed" when the form is submitted with selection data for the global email subscribed state. If it's a checkbox, the user will either be "opted_in" or "unsubscribed". For a hidden input, the "subscribed" state will also be valid. | | `{% form_field_name :subscription_group %}` | Indicates that a specific form input element corresponds to a given subscription group. The user's selection state should be either "subscribed" or "unsubscribed" when the form is submitted with selection data for a specific subscription group. | | `{{preference_center_submit_url}}` | Generates URL for form submission. | ## Example response ``` { "preference_center_api_id": "preference_center_api_id_example", "liquid_tag": "{{preference_center.${MyPreferenceCenter2022-09-22}}}", "created_at": "2022-09-22T18:28:07+00:00", "message": "success" } ``` requestBody: content: application/json: schema: type: object example: name: string preference_center_title: string preference_center_page_html: string confirmation_page_html: string state: active options: meta-viewport-content: string properties: name: type: string preference_center_title: type: string preference_center_page_html: type: string confirmation_page_html: type: string state: type: string options: type: object properties: meta-viewport-content: 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' /scim/v2/Users/{id}: delete: tags: - SCIM summary: Remove Dashboard User Account description: >- > This endpoint allows you to permanently delete an existing dashboard user by specifying the resource `id` returned by the SCIM [`POST`](https://www.braze.com/docs/scim/post_create_user_account/) method. This is similar to deleting a user in the **Manage Users** section of the Braze dashboard. For information on how to obtain a SCIM token, visit [Automated user provisioning](https://www.braze.com/docs/scim/automated_user_provisioning/). ## Rate limit This endpoint has a rate limit of 5000 requests per day, per company. This rate limit is shared with the `/scim/v2/Users/` PUT, GET, and POST endpoints as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Path parameters | Parameter | Required | Data type | Description | | --- | --- | --- | --- | | `id` | Required | String | The users resource ID. This parameter is returned by the `POST` `/scim/v2/Users/` or `GET` `/scim/v2/Users?filter=userName eq "[user@test.com](mailto:user@test.com)"` methods. | ## Request parameters There is no request body for this endpoint. ## Response ### Example error response ``` json HTTP/1.1 204 Not Found Content-Type: text/html; charset=UTF-8 ``` If a developer with this ID doesnt exist in Braze, the endpoint will respond with: ``` json HTTP/1.1 404 Not Found Content-Type: text/html; charset=UTF-8 { "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "detail": "User not found", "status": 404 } ``` parameters: - name: Content-Type in: header schema: type: string example: application/json - name: X-Request-Origin in: header schema: type: string example: YOUR-REQUEST-ORIGIN-HERE - name: Authorization in: header schema: type: string example: Bearer YOUR-SCIM-TOKEN-HERE - name: id in: path schema: type: string required: true responses: '200': 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' get: tags: - SCIM summary: Look Up an Existing Dashboard User Account description: >- > This endpoint allows you to look up an existing dashboard user account by specifying the resource `id` returned by the SCIM [`POST`](https://www.braze.com/docs/scim/post_create_user_account/) method. For information on how to obtain a SCIM token, visit [Automated user provisioning](https://www.braze.com/docs/scim/automated_user_provisioning/). ## Rate limit This endpoint has a rate limit of 5000 requests per day, per company. This rate limit is shared with the `/scim/v2/Users/` PUT, GET, DELETE, and POST endpoints as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Path parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `id` | Required | String | The user's resource ID. This parameter is returned by the `POST` `/scim/v2/Users/` or `GET` `/scim/v2/Users?filter=userName eq "user@test.com"` methods. | ## Request parameters There is no request body for this endpoint. ## Response ``` json { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "dfa245b7-24195aec-887bb3ad-602b3340", "userName": "user@test.com", "name": { "givenName": "Test", "familyName": "User" }, "department": "finance", "lastSignInAt": "Thursday, January 1, 1970 12:00:00 AM", "permissions": { "companyPermissions": ["manage_company_settings"], "appGroup": [ { "appGroupId": "241adcd25789fabcded", "appGroupName": "Test App Group", "appGroupPermissions": ["basic_access","send_campaigns_canvases"], "team": [ { "teamId": "241adcd25789fabcded", "teamName": "Test Team", "teamPermissions": ["admin"] } ] } ] } } ``` parameters: - name: Content-Type in: header schema: type: string example: application/json - name: X-Request-Origin in: header schema: type: string example: YOUR-REQUEST-ORIGIN-HERE - name: Authorization in: header schema: type: string example: Bearer YOUR-SCIM-TOKEN-HERE - name: id in: path schema: type: string required: true responses: '200': 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' put: tags: - SCIM summary: Update Dashboard User Account description: >- > This endpoint allows you to update an existing dashboard user account by specifying the resource `id` returned by the SCIM [`POST`](https://www.braze.com/docs/scim/post_create_user_account/) method. It allows you to update of given and family names, permissions (for setting permissions at the company, app group, and team level) and department. For information on how to obtain a SCIM token, visit [Automated user provisioning](https://www.braze.com/docs/scim/automated_user_provisioning/). For security reasons, `userName` (email address) cannot be updated through this endpoint. If you would like to change the `userName` (email address) for a user, contact [Support](https://www.braze.com/docs/support_contact/). ## Rate limit This endpoint has a rate limit of 5000 requests per day, per company. This rate limit is shared with the `/scim/v2/Users/` GET, DELETE, and POST endpoints as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Path parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `id` | Required | String | The user's resource ID. This parameter is returned by the `POST` `/scim/v2/Users/` or `GET` `/scim/v2/Users?filter=userName eq "user@test.com"` methods. | ## Request parameters | Parameter | Required | Data type | Description | | --- | --- | --- | --- | | `schemas` | Required | Array of strings | Expected SCIM 2.0 schema name for user object. | | `name` | Required | JSON object | This object contains the user's given name and family name. | | `department` | Required | String | Valid department string from the [department string documentation]({{site.baseurl}}/scim_api_appendix/#department-strings). | | `permissions` | Required | JSON object | Permissions object as described in the [permissions object documentation]({{site.baseurl}}/scim_api_appendix/#permissions-object). | ## Response ``` json { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "dfa245b7-24195aec-887bb3ad-602b3340", "userName": "user@test.com", "name": { "givenName": "Test", "familyName": "User" }, "department": "finance", "lastSignInAt": "Thursday, January 1, 1970 12:00:00 AM", "permissions": { "companyPermissions": ["manage_company_settings"], "appGroup": [ { "appGroupId": "241adcd25789fabcded", "appGroupName": "Test App Group", "appGroupPermissions": ["basic_access","send_campaigns_canvases"], "team": [ { "teamId": "2519dafcdba238ae7", "teamName": "Test Team", "teamPermissions": ["admin"] } ] } ] } } ``` ### Error states If a user with this ID doesnt exist in Braze, the endpoint will respond with: ``` json HTTP/1.1 404 Not Found Content-Type: text/html; charset=UTF-8 { "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "detail": "User not found", "status": 404 } ``` requestBody: content: application/json: schema: type: object example: schemas: - urn:ietf:params:scim:schemas:core:2.0:User name: givenName: Test familyName: User department: finance permissions: companyPermissions: - manage_company_settings appGroup: - appGroupName: Test App Group appGroupPermissions: - basic_access - send_campaigns_canvases team: - teamName: Test Team teamPermissions: - admin properties: schemas: type: array items: type: string name: type: object properties: givenName: type: string familyName: type: string department: type: string permissions: type: object properties: companyPermissions: type: array items: type: string appGroup: type: array items: type: object properties: appGroupName: type: string appGroupPermissions: type: array items: type: string team: type: array items: type: object properties: teamName: type: string teamPermissions: type: array items: type: string parameters: - name: Content-Type in: header schema: type: string example: application/json - name: X-Request-Origin in: header schema: type: string example: YOUR-REQUEST-ORIGIN-HERE - name: Authorization in: header schema: type: string example: Bearer YOUR-SCIM-TOKEN-HERE - name: id in: path schema: type: string required: true responses: '200': 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' /scim/v2/Users: get: tags: - SCIM summary: Search Existing Dashboard User by Email description: >- > This endpoint allows you to look up an existing dashboard user account by specifying their email in the filter query parameter. Note that when the query parameter is URL encoded it will read like this: `/scim/v2/Users?filter=userName eq "user@test.com"` For information on how to obtain a SCIM token, visit [Automated user provisioning](https://www.braze.com/docs/scim/automated_user_provisioning/). ## Rate limit This endpoint has a rate limit of 5000 requests per day, per company. This rate limit is shared with the `/scim/v2/Users/` PUT, GET, DELETE, and POST endpoints as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Path parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `userName@example.com` | Required | String | The user's email. | ## Request parameters There is no request body for this endpoint. ## Response ``` json Content-Type: application/json X-Request-Origin: YOUR-REQUEST-ORIGIN-HERE Authorization: Bearer YOUR-SCIM-TOKEN-HERE { "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], "totalResults": 1, "Resources": [ { "userName": "user@test.com", "id": "dfa245b7-24195aec-887bb3ad-602b3340", "name": { "givenName": "Test", "familyName": "User" }, "department": "finance", "lastSignInAt": "Thursday, January 1, 1970 12:00:00 AM", "permissions": { "companyPermissions": ["manage_company_settings"], "appGroup": [ { "appGroupId": "241adcd25789fabcded", "appGroupName": "Test App Group", "appGroupPermissions": ["basic_access","send_campaigns_canvases"], "team": [ { "teamId": "241adcd25789fabcded", "teamName": "Test Team", "teamPermissions": ["admin"] } ] } ] } } ] } ``` parameters: - name: Content-Type in: header schema: type: string example: application/json - name: X-Request-Origin in: header schema: type: string example: YOUR-REQUEST-ORIGIN-HERE - name: Authorization in: header schema: type: string example: Bearer YOUR-SCIM-TOKEN-HERE - name: filter in: query schema: type: string example: '{userName@example.com}' responses: '200': 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' post: tags: - SCIM summary: Create New Dashboard User Account description: >- > This endpoint allows you to create a new dashboard user account by specifying email, given and family names, permissions (for setting permissions at the company, app group, and team level). For information on how to obtain a SCIM token, visit [Automated user provisioning](https://www.braze.com/docs/scim/automated_user_provisioning/). ## Rate limit This endpoint has a rate limit of 5000 requests per day, per company. This rate limit is shared with the `/scim/v2/Users/` PUT, GET, and DELETE endpoints as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Request parameters | Parameter | Required | Data type | Description | | --- | --- | --- | --- | | `schemas` | Required | Array of strings | Expected SCIM 2.0 schema name for user object. | | `userName` | Required | String | The users email address. | | `name` | Required | JSON object | This object contains the user's given name and family name. | | `department` | Required | String | Valid department string from the [department string documentation]({{site.baseurl}}/scim_api_appendix/#department-strings). | | `permissions` | Required | JSON object | Permissions object as described in the [permissions object documentation]({{site.baseurl}}/scim_api_appendix/#permissions-object). | ## Response ``` json { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "dfa245b7-24195aec-887bb3ad-602b3340", "userName": "user@test.com", "name": { "givenName": "Test", "familyName": "User" }, "department": "finance", "lastSignInAt": "Thursday, January 1, 1970 12:00:00 AM", "permissions": { "companyPermissions": ["manage_company_settings"], "appGroup": [ { "appGroupId": "241adcd25789fabcded", "appGroupName": "Test App Group", "appGroupPermissions": ["basic_access","send_campaigns_canvases"], "team": [ { "teamId": "2519dafcdba238ae7", "teamName": "Test Team", "teamPermissions": ["basic_access","export_user_data"] } ] } ] } } ``` ### Error states If a user with this email address already exists in Braze, the endpoint will respond with: ``` json HTTP/1.1 409 Conflict Date: Tue, 10 Sep 2019 02:22:30 GMT Content-Type: text/json;charset=UTF-8 { "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "detail": "User already exists in the database.", "status": 409 } ``` requestBody: content: application/json: schema: type: object example: schemas: - urn:ietf:params:scim:schemas:core:2.0:User userName: user@test.com name: givenName: Test familyName: User department: finance permissions: companyPermissions: - manage_company_settings appGroup: - appGroupName: Test App Group appGroupPermissions: - basic_access - send_campaigns_canvases team: - teamName: Test Team teamPermissions: - basic_access - export_user_data properties: schemas: type: array items: type: string userName: type: string format: email name: type: object properties: givenName: type: string familyName: type: string department: type: string permissions: type: object properties: companyPermissions: type: array items: type: string appGroup: type: array items: type: object properties: appGroupName: type: string appGroupPermissions: type: array items: type: string team: type: array items: type: object properties: teamName: type: string teamPermissions: type: array items: type: string parameters: - name: Content-Type in: header schema: type: string example: application/json - name: X-Request-Origin in: header schema: type: string example: YOUR-REQUEST-ORIGIN-HERE - name: Authorization in: header schema: type: string example: Bearer YOUR-SCIM-TOKEN-HERE 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' /sms/invalid_phone_numbers: get: tags: - SMS summary: Query Invalid Phone Numbers description: >- > Use this endpoint to pull a list of phone numbers that have been deemed invalid within a certain time frame. To use this endpoint, youll need to generate an API key with the `sms.invalid_phone_numbers` permission. - If you provide a `start_date`, an `end_date`, and `phone_numbers`, we prioritize the given phone numbers and disregard the date range. - If your date range has more than the `limit` number of invalid phone numbers, you will need to make multiple API calls with increasing the `offset` each time until a call returns either fewer than `limit` or zero results. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Response Entries are listed in descending order. ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "sms": [ { "phone": "12345678900", "invalid_detected_at": "2016-08-25 15:24:32 +0000" }, { "phone": "12345678901", "invalid_detected_at": "2016-08-24 17:41:58 +0000" }, { "phone": "12345678902", "invalid_detected_at": "2016-08-24 12:01:13 +0000" } ], "message": "success" } ``` parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: start_date in: query schema: type: string description: > (Optional*) String in YYYY-MM-DD format Start date of the range to retrieve invalid phone numbers, must be earlier than `end_date`. This is treated as midnight in UTC time by the API. example: '2018-09-01' - name: end_date in: query schema: type: string description: > (Optional*) String in YYYY-MM-DD format End date of the range to retrieve invalid phone numbers. This is treated as midnight in UTC time by the API. example: '2018-09-01' - name: limit in: query schema: type: integer description: >- (Optional) Integer Optional field to limit the number of results returned. Defaults to 100, maximum is 500. example: 100 - name: offset in: query schema: type: integer description: |- (Optional) Integer Optional beginning point in the list to retrieve from. example: 1 - name: phone_numbers in: query schema: type: integer description: > (Optional*) Array of Strings in e.164 format If provided, we will return the phone number if it has been found to be invalid. example: 12345678901 responses: '200': 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' /sms/invalid_phone_numbers/remove: post: tags: - SMS summary: Remove Invalid Phone Numbers description: >- > Use this endpoint to remove invalid phone numbers from Brazes invalid list. To use this endpoint, youll need to generate an API key with the `sms.invalid_phone_numbers.remove` permission. This can be used to re-validate phone numbers after they have been marked as invalid. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `phone_number` | Required | Array of strings in e.164 format | An array of up to 50 phone numbers to modify. | requestBody: content: application/json: schema: type: object example: phone_numbers: - '12183095514' - '14255551212' properties: phone_numbers: type: array items: type: string parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: Content-Type in: header schema: type: string example: application/json 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' /subscription/status/get: get: tags: - Subscription Groups > SMS and WhatsApp summary: List User's Subscription Group Status - SMS description: >- > Use this endpoint to get the subscription state of a user in a subscription group. To use this endpoint, youll need to generate an API key with the `subscription.status.get` permission. These groups will be available on the **Subscription Group** page. The response from this endpoint will include the external ID and either subscribed, unsubscribed, or unknown for the specific subscription group requested in the API call. This can be used to update the subscription group state in subsequent API calls or to be displayed on a hosted web page. \*Either `external_id` or `phone` are required. When both are submitted, only the external_id is used for querying and the phone number is applied to that user. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Response All successful responses will return `subscribed`, `unsubscribed`, or `unknown` depending on status and user history with the subscription group. ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "status": { "1": "Unsubscribed", "2": "Subscribed" }, "message": "success" } ``` parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: subscription_group_id in: query schema: type: string description: |- (Required) String The `id` of your subscription group. example: '{{subscription_group_id}}' - name: external_id in: query schema: type: string description: > (Required*) String The `external_id` of the user (must include at least one and at most 50 `external_ids`). When both an `external_id` and `phone` are submitted, only the external_id(s) provided will be applied to the result query. example: '{{external_identifier}}' - name: phone in: query schema: type: string description: >- (Required*) String in [E.164](https://en.wikipedia.org/wiki/E.164) format The phone number of the user (must include at least one phone number and at most 50 phone numbers). example: '+11112223333' responses: '200': 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' /subscription/user/status: get: tags: - Subscription Groups > SMS and WhatsApp summary: List User's Subscription Group - SMS description: >- > Use this endpoint to list and get the subscription groups of a certain user. To use this endpoint, youll need to generate an API key with the `subscription.groups.get` permission. If there are multiple users (multiple external IDs) who share the same email address, all users will be returned as a separate user (even if they have the same email address or subscription group). ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: external_id in: query schema: type: string description: >- (Required*) String The `external_id` of the user (must include at least one and at most 50 `external_ids`). example: '{{external_id}}' - name: limit in: query schema: type: integer description: >- (Optional) Integer The limit on the maximum number of results returned. Default (and max) limit is 100. example: 100 - name: offset in: query schema: type: integer description: "(Optional) Integer\n\n\tNumber of templates to skip before returning the rest of the templates that fit the search criteria." example: 1 - name: phone in: query schema: type: string description: >- (Required*) String in [E.164](https://en.wikipedia.org/wiki/E.164) format The phone number of the user. Must include at least one phone number (with a max of 50). example: '+11112223333' responses: '200': 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' /subscription/status/set: post: tags: - Subscription Groups > SMS and WhatsApp summary: Update User's Subscription Group Status - SMS description: >- > Use this endpoint to batch update the subscription state of up to 50 users on the Braze dashboard. To use this endpoint, youll need to generate an API key with the `subscription.status.set` permission. You can access a subscription groups `subscription_group_id` by navigating to the **Subscription Group** page. Tip: When creating new users via the [/users/track](https://www.braze.com/docs/api/endpoints/user_data/post_user_track/) endpoint, you can set subscription groups within the user attributes object, which allows you to create a user and set the subscription group state in one API call. \*Only `external_id` or `phone` is accepted for SMS subscription groups. ### Rate limit For customers who onboarded with Braze on or after January 6, 2022, we apply a rate limit of 5,000 requests per minute shared across the `/subscription/status/set` and `/v2/subscription/status/set` endpoint as documented in [API rate limits](http://localhost:4000/docs/api/api_limits/). ### Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `subscription_group_id` | Required | String | The `id` of your subscription group. | | `subscription_state` | Required | String | Available values are `unsubscribed` (not in subscription group) or `subscribed` (in subscription group). | | `external_id` | Required\* | Array of strings | The `external_id` of the user or users, may include up to 50 `id`s. | | `phone` | Required\* | String in [E.164](https://en.wikipedia.org/wiki/E.164) format | The phone number of the user, can be passed as an array of strings. Must include at least one phone number (with a max of 50). | ### Example successful response The status code `201` could return the following response body. ``` json { "message": "success" } ``` Important: The endpoint only accepts the `email` or `phone` value, not both. If given both, you will receive this response: `{"message":"Either an email address or a phone number should be provided, but not both."}` requestBody: content: application/json: schema: type: object example: subscription_group_id: subscription_group_identifier subscription_state: unsubscribed external_id: external_identifier phone: - '+12223334444' - '+11112223333' properties: subscription_group_id: type: string subscription_state: type: string external_id: type: string phone: type: array items: 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' /v2/subscription/status/set: post: tags: - Subscription Groups > SMS and WhatsApp summary: Update User's Subscription Group Status V2 description: >- > Use this endpoint to batch update the subscription state of up to 50 users on the Braze dashboard. To use this endpoint, youll need to generate an API key with the `subscription.status.set` permission. You can access a subscription groups `subscription_group_id` by navigating to the **Subscriptions Group** page. ## Rate limit For customers who onboarded with Braze on or after January 6, 2022, we apply a rate limit of 5,000 requests per minute shared across the `/subscription/status/set` and `/v2/subscription/status/set` endpoint as documented in [API rate limits](http://localhost:4000/docs/api/api_limits/). ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `subscription_group_id` | Required | String | The `id` of your subscription group. | | `subscription_state` | Required | String | Available values are `unsubscribed` (not in subscription group) or `subscribed` (in subscription group). | | `external_ids` | Required\* | Array of strings | The `external_id` of the user or users, may include up to 50 `id`s. | | `phones` | Required\* | String in [E.164](https://en.wikipedia.org/wiki/E.164) format | The phone numbers of the user, can be passed as an array of strings. Must include at least one phone number (with a max of 50). | ### Example successful response Response: (status 201) ``` json { "message": "success" } ``` requestBody: content: application/json: schema: type: object example: subscription_groups: - subscription_group_id: subscription_group_identifier subscription_state: subscribed emails: - example1@email.com - example2@email.com properties: subscription_groups: type: array items: type: object properties: subscription_group_id: type: string subscription_state: type: string emails: type: array items: type: string format: email 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' /content_blocks/list: get: tags: - Templates > Content Blocks summary: List Available Content Blocks description: >- > Use this endpoint to list your existing [Content Blocks](https://www.braze.com/docs/user_guide/engagement_tools/templates_and_media/content_blocks/) information. To use this endpoint, youll need to generate an API key with the `content_blocks.list` permission. ### Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ### Response ``` json Content-Type: application/json Authorization: Bearer YOUR_REST_API_KEY { "count": "integer", "content_blocks": [ { "content_block_id": "string", "name": "string", "content_type": "html or text", "liquid_tag": "string", "inclusion_count" : "integer", "created_at": "time-in-iso", "last_edited": "time-in-iso", "tags" : "array of strings" } ] } ``` ## Troubleshooting The following table lists possible returned errors and their associated troubleshooting steps. | Error | Troubleshooting | | --- | --- | | `Modified after time is invalid` | The provided date is not a valid or parsable date. Reformat this value as a string in ISO 8601 format (`yyyy-mm-ddThh:mm:ss.ffffff`). | | `Modified before time is invalid` | The provided date is not a valid or parsable date. Reformat this value as a string in ISO 8601 format (`yyyy-mm-ddThh:mm:ss.ffffff`). | | `Modified after time must be earlier than or the same as modified before time.` | Change the `modified_after` value to a time that is earlier than the `modified_before` time. | | `Content Block number limit is invalid` | The `limit` parameter must be an integer (positive number) greater than 0. | | `Content Block number limit must be greater than 0` | Change the `limit` parameter to an integer greater than 0. | | `Content Block number limit exceeds maximum of 1000` | Change the `limit` parameter to an integer less than 1000. | | `Offset is invalid` | The `offset` parameter must be an integer greater than 0. | | Offset must be greater than 0 | Change the `offset` parameter to an integer greater than 0. | parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: modified_after in: query schema: type: string description: >- (Optional) String in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) Retrieve only content blocks updated at or after the given time. example: '2020-01-01T01:01:01.000000' - name: modified_before in: query schema: type: string description: >- (Optional) String in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) Retrieve only content blocks updated at or before the given time. example: '2020-02-01T01:01:01.000000' - name: limit in: query schema: type: integer description: >- (Optional) Positive Number Maximum number of content blocks to retrieve. Default to 100 if not provided, with a maximum acceptable value of 1000. example: 100 - name: offset in: query schema: type: integer description: >- (Optional) Positive Number Number of content blocks to skip before returning rest of the templates that fit the search criteria. example: 1 responses: '200': 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' /content_blocks/info: get: tags: - Templates > Content Blocks summary: See Content Block Information description: >- > Use this endpoint to call information for your existing [Content Blocks](https://www.braze.com/docs/user_guide/engagement_tools/templates_and_media/content_blocks/). To use this endpoint, youll need to generate an API key with the `content_blocks.info` permission. **Note:** If you are using our [older navigation](https://www.braze.com/docs/navigation), `content_block_id`can be found at ****Developer Console** > **API Settings****. ### Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ### Response ``` json Content-Type: application/json Authorization: Bearer YOUR_REST_API_KEY { "content_block_id": "string", "name": "string", "content": "string", "description": "string", "content_type": "html or text", "tags": "array of strings", "created_at": "time-in-iso", "last_edited": "time-in-iso", "inclusion_count" : "integer", "message": "success" } ``` ## Troubleshooting The following table lists possible returned errors and their associated troubleshooting steps. | Error | Troubleshooting | | --- | --- | | `Content Block ID cannot be blank` | Make sure that a Content Block is listed in your request and is encapsulated in quotes (`""`). | | `Content Block ID is invalid for this App Group` | This Content Block doesn't exist or is in a different company account or app group. | | `Content Block has been deletedcontent not available` | This Content Block, though it may have existed earlier, has been deleted. | | `Include Inclusion Dataerror` | This parameter only accepts boolean values (true or false). Make sure the value for `include_inclusion_data` is not encapsulated in quotes (`""`), which causes the value to be sent as a string instead. See [request parameters](#request-parameters) for details. | parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: content_block_id in: query schema: type: string description: >- (Required) String The content block identifier. You can find this by either listing content block information through an API call or going to **Settings > Setup and Testing > API Keys**, then scrolling to the bottom and searching for your content block API identifier. example: '{{content_block_id}}' - name: include_inclusion_data in: query schema: type: boolean description: >- (Optional) Boolean When set to `true`, the API returns back the Message Variation API identifier of campaigns and Canvases where this content block is included, to be used in subsequent calls. The results exclude archived or deleted Campaigns or Canvases. responses: '200': 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' /content_blocks/create: post: tags: - Templates > Content Blocks summary: Create Content Block description: >- > Use this endpoint to create a [Content Block](https://www.braze.com/docs/user_guide/engagement_tools/templates_and_media/content_blocks/). To use this endpoint, youll need to generate an API key with the `content_blocks.create` permission. ### Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ### Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `name` | Required | String | Name of the content block. Must be less than 100 characters. | | `description` | Optional | String | Description of the content block. Must be less than 250 characters. | | `content` | Required | String | HTML or text content within the Content Block. | | `state` | Optional | String | Choose `active` or `draft`. Defaults to `active` if not specified. | | `tags` | Optional | Array of strings | [Tags](https://www.braze.com/docs/user_guide/administrative/app_settings/manage_app_group/tags/) must already exist. | ### Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "content_block_id": (string) Your newly generated block id, "liquid_tag": (string) The generated block tag from the Content Block name, "created_at": (string) The time the Content Block was created in ISO 8601, "message": "success" } ``` ## Troubleshooting The following table lists possible returned errors and their associated troubleshooting steps. | Error | Troubleshooting | | --- | --- | | `Content cannot be blank` | | | `Content must be a string` | Make sure your content is encapsulated in quotes (`""`). | | `Content must be smaller than 50kb` | The content in your Content Block must be less than 50kb total. | | `Content contains malformed liquid` | The Liquid provided is not valid or parsable. Try again with valid Liquid or reach out to support. | | `Content Block cannot be referenced within itself` | | | `Content Block description cannot be blank` | | | `Content Block description must be a string` | Make sure your Content Block description is encapsulated in quotes (`""`). | | `Content Block description must be shorter than 250 characters` | | | `Content Block name cannot be blank` | | | `Content Block name must be shorter than 100 characters` | | | `Content Block name can only contain alphanumeric characters` | Content Block names can include any of the following characters: the letters (capitalized or lowercase) `A` through `Z`, the numbers `0` through `9`, dashes `-`, and underscores `_`. It cannot contain non-alphanumeric characters like emojis, `!`, `@`, `~`, `&`, and other "special" characters. | | `Content Block with this name already exists` | Try a different name. | | `Content Block state must be either active or draft` | | | `Tags must be an array` | Tags must be formatted as an array of strings, for example `["marketing", "promotional", "transactional"]`. | | `All tags must be strings` | Make sure your tags are encapsulated in quotes (`""`). | | `Some tags could not be found` | To add a tag when creating a Content Block, the tag must already exist in Braze. | requestBody: content: application/json: schema: type: object example: name: content_block description: This is my content block content: HTML content within block state: draft tags: - marketing properties: name: type: string description: type: string content: type: string state: type: string tags: type: array items: 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' /content_blocks/update: post: tags: - Templates > Content Blocks summary: Update Content Block description: >- > Use this endpoint to update a [Content Block](https://www.braze.com/docs/user_guide/engagement_tools/templates_and_media/content_blocks/). To use this endpoint, youll need to generate an API key with the `content_blocks.update` permission. ### Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/) ### Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `content_block_id` | Required | String | Your content block's API identifier. | | `name` | Required | String | Name of the content block. Must be less than 100 characters. | | `description` | Optional | String | Description of the content block. Must be less than 250 characters. | | `content` | Required | String | HTML or text content within content blocks. | | `state` | Optional | String | Choose `active` or `draft`. Defaults to `active` if not specified. | | `tags` | Optional | Array of strings | [Tags](https://www.braze.com/docs/user_guide/administrative/app_settings/manage_app_group/tags/) must already exist. | ### Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "content_block_id": (string) Your newly generated block id, "liquid_tag": (string) The generated block tag from the Content Block name, "created_at": (string) The time the Content Block was created in ISO 8601, "message": "success" } ``` ## Troubleshooting The following table lists possible returned errors and their associated troubleshooting steps. | Error | Troubleshooting | | --- | --- | | `Content cannot be blank` | | | `Content must be a string` | Make sure your content is encapsulated in quotes (`""`). | | `Content must be smaller than 50kb` | The content in your Content Block must be less than 50kb total. | | `Content contains malformed liquid` | The Liquid provided is not valid or parsable. Try again with valid Liquid or reach out to support. | | `Content Block cannot be referenced within itself` | | | `Content Block description cannot be blank` | | | `Content Block description must be a string` | Make sure your Content Block description is encapsulated in quotes (`""`). | | `Content Block description must be shorter than 250 characters` | | | `Content Block name cannot be blank` | | | `Content Block name must be shorter than 100 characters` | | | `Content Block name can only contain alphanumeric characters` | Content Block names can include any of the following characters: the letters (capitalized or lowercase) `A` through `Z`, the numbers `0` through `9`, dashes `-`, and underscores `_`. It cannot contain non-alphanumeric characters like emojis, `!`, `@`, `~`, `&`, and other "special" characters. | | `Content Block with this name already exists` | Try a different name. | | `Content Block name cannot be updated for active Content Blocks` | | | `Content Block state must be either active or draft` | | | `Active Content Block can not be updated to Draft. Create a new Content Block.` | | | `Tags must be an array` | Tags must be formatted as an array of strings, for example `["marketing", "promotional", "transactional"]`. | | `All tags must be strings` | Make sure your tags are encapsulated in quotes (`""`). | | `Some tags could not be found` | To add a tag when creating a Content Block, the tag must already exist in Braze. | requestBody: content: application/json: schema: type: object example: content_block_id: content_block_id name: content_block description: This is my content block content: HTML or text content within block state: draft tags: - marketing properties: content_block_id: type: string name: type: string description: type: string content: type: string state: type: string tags: type: array items: 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' /templates/email/list: get: tags: - Templates > Email Templates summary: List Available Email Templates description: >- > Use this endpoint to get a list of available templates in your Braze account. To use this endpoint, youll need to generate an API key with the `templates.email.list` permission. ### Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ### Response > **Important:** Templates built using the Drag & Drop Editor for email are not provided in this response. ``` json { "count": number of templates returned "templates": [template with the following properties]: "email_template_id": (string) your email template's API Identifier, "template_name": (string) the name of your email template, "created_at": (string, in ISO 8601), "updated_at": (string, in ISO 8601), "tags": (array of strings) tags appended to the template } ``` parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: modified_after in: query schema: type: string description: >- (Optional) String in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) Retrieve only templates updated at or after the given time. example: '2020-01-01T01:01:01.000000' - name: modified_before in: query schema: type: string description: >- (Optional) String in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) Retrieve only templates updated at or before the given time. example: '2020-02-01T01:01:01.000000' - name: limit in: query schema: type: integer description: >- (Optional) Positive Number Maximum number of templates to retrieve. Default to 100 if not provided, with a maximum acceptable value of 1000. example: 1 - name: offset in: query schema: type: integer description: >- (Optional) Positive Number Number of templates to skip before returning rest of the templates that fit the search criteria. responses: '200': 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' /templates/email/info: get: tags: - Templates > Email Templates summary: See Email Template Information description: >- > Use this endpoint to get information on your email templates. To use this endpoint, youll need to generate an API key with the `templates.email.info` permission. > **Important:** Templates built using the drag-and-drop editor for email are not accepted. ### Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ### Response ``` json Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "email_template_id": (string) your email template's API Identifier, "template_name": (string) the name of your email template, "description": (string) email template description, "subject": (string) the email template subject line, "preheader": (optional, string) the email preheader used to generate previews in some clients), "body": (optional, string) the email template body that may include HTML, "plaintext_body": (optional, string) a plaintext version of the email template body, "should_inline_css": (optional, boolean) whether there is inline CSS in the body of the template - defaults to the css inlining value for the App Group, "tags": (string) tag names, "created_at": (string, in ISO 8601), "updated_at": (string, in ISO 8601) } ``` Images in this response will show in the `body` variable as HTML. parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: email_template_id in: query schema: type: string description: >- (Required) String See [email template's API identifier](https://www.braze.com/docs/api/identifier_types/). example: '{{email_template_id}}' responses: '200': 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' /templates/email/create: post: tags: - Templates > Email Templates summary: Create Email Template description: >- > Use this endpoint to create email templates on the Braze dashboard. To use this endpoint, youll need to generate an API key with the `templates.email.create` permission. These templates will be available on the **Templates & Media** page. The response from this endpoint will include a field for `email_template_id`, which can be used to update the template in subsequent API calls. Users email subscription status can be updated and retrieved via Braze using a RESTful API. You can use the API to set up bi-directional sync between Braze and other email systems or your own database. All API requests are made over HTTPS. ### Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ### Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `template_name` | Required | String | Name of your email template. | | `subject` | Required | String | Email template subject line. | | `body` | Required | String | Email template body that may include HTML. | | `plaintext_body` | Optional | String | A plaintext version of the email template body. | | `preheader` | Optional | String | Email preheader used to generate previews in some clients. | | `tags` | Optional | String | [Tags](https://www.braze.com/docs/user_guide/administrative/app_settings/manage_app_group/tags/) must already exist. | | `should_inline_css` | Optional | Boolean | Enables or disables the `inline_css` feature per template. If not provided, Braze will use the default setting for the app group. One of `true` or `false` is expected. | ### Possible errors The following table lists possible returned errors and their associated troubleshooting steps, if applicable. | Error | Troubleshooting | | --- | --- | | Template name is required | Enter a template name. | | Tags must be an array | Tags must be formatted as an array of strings, for example `["marketing", "promotional", "transactional"]`. | | All tags must be strings | Make sure your tags are encapsulated in quotes (`""`). | | Some tags could not be found | To add a tag when creating an email template, the tag must already exist in Braze. | | Email must have valid Content Block names | The email contains Content Blocks that don't exist in this environment. | | Invalid value for `should_inline_css`. One of `true` or `false` was expected | This parameter only accepts boolean values (true or false). Make sure the value for `should_inline_css` is not encapsulated in quotes (`""`), which causes the value to be sent as a string instead. | requestBody: content: application/json: schema: type: object example: template_name: email_template_name subject: Welcome to my email template! body: >- This is the text within my email body and https://www.braze.com/ here is a link to Braze.com. plaintext_body: >- This is the text within my email body and here is a link to https://www.braze.com/. preheader: My preheader is pretty cool. tags: - Tag1 - Tag2 properties: template_name: type: string subject: type: string body: type: string plaintext_body: type: string preheader: type: string tags: type: array items: 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' /users/external_ids/rename: post: tags: - User Data > External ID Migration summary: Rename External ID description: >- > Use this endpoint to rename your users external IDs. To use this endpoint, youll need to generate an API key with the `users.external_ids.rename` permission. You can send up to 50 rename objects per request. You will need to create a new [API key](https://www.braze.com/docs/api/api_key/) with permissions for this endpoint. This endpoint sets a new (primary) `external_id` for the user and deprecates their existing `external_id`. This means that the user can be identified by either `external_id` until the deprecated one is removed. Having multiple external IDs allows for a migration period so that older versions of your apps that use the previous external ID naming schema don't break. After your old naming schema is no longer in use, we highly recommend removing deprecated external IDs using the [`/users/external_ids/remove` endpoint](https://www.braze.com/docs/api/endpoints/user_data/external_id_migration/post_external_ids_remove). > **Warning:** Make sure to remove deprecated external IDs with the ## Rate limit We apply a rate limit of 1,000 requests per minute to this endpoint, as documented in [API rate limits](http://braze.com/docs/api/api_limits/). ### Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `external_id_renames` | Required | Array of external ID rename objects | View request example and the following limitations for structure of external ID rename object | - The `current_external_id` must be the users primary ID, and cannot be a deprecated ID - The `new_external_id` must not already be in use as either a primary ID or a deprecated ID - The `current_external_id` and `new_external_id` cannot be the same ## Response The response will confirm all successful renames, as well as unsuccessful renames with any associated errors. Error messages in the `rename_errors` field will reference the index of the object in the array of the original request. ``` json { "message" : (string) status message, "external_ids" : (array of successful Rename Operations), "rename_errors": (array of any ) } ``` The `message` field will return `success` for any valid request. More specific errors are captured in the `rename_errors` array. The `message` field returns an error in the case of: - Invalid API key - Empty `external_id_renames` array - `external_id_renames` array with more than 50 objects - Rate limit hit (>1,000 requests/minute) ## Frequently Asked Questions **Does this impact MAU?** No, since the number of users will stay the same, theyll just have a new `external_id`. **Does user behavior change historically?** No, since the user is still the same user, and all their historical behavior is still connected to them. **Can it be run on dev/staging app groups?** Yes. In fact, we highly recommend running a test migration on a staging or development app group, and ensuring everything has gone smoothly before executing on production data. **Does this consume data points?** This feature does not cost data points. **What is the recommended deprecation period?** We have no hard limit on how long you can keep deprecated external IDs around, but we highly recommend removing them once there is no longer a need to reference users by the deprecated ID. requestBody: content: application/json: schema: type: object example: external_id_renames: - current_external_id: existing_external_id new_external_id: new_external_id properties: external_id_renames: type: array items: type: object properties: current_external_id: type: string new_external_id: 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' /users/external_ids/remove: post: tags: - User Data > External ID Migration summary: Remove External ID description: >- > Use this endpoint to remove your users' old deprecated external IDs. To use this endpoint, youll need to generate an API key with the `users.external_ids.remove` permission. You can send up to 50 external IDs per request. You will need to create a new [API key](https://www.braze.com/docs/api/api_key/) with permissions for this endpoint. > **Warning:** This endpoint completely removes the deprecated ID and cannot be undone. Using this endpoint to remove deprecated \`external_ids\` that are still associated with users in your system can permanently prevent you from finding those users' data. ## Rate limit We apply a rate limit of 1,000 requests per minute to this endpoint, as documented in [API rate limits](http://braze.com/docs/api/api_limits/). ### Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `external_ids` | Required | Array of strings | External identifiers for the users to remove | > Important: Only deprecated IDs can be removed; attempting to remove a primary external ID will result in an error. ## Response 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. ``` json { "message" : (string) status message, "removed_ids" : (array of successful Remove Operations), "removal_errors": (array of any ) } ``` 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 (>1,000 requests/minute) requestBody: content: application/json: schema: type: object example: external_ids: - existing_deprecated_external_id_string properties: external_ids: type: array items: 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' /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](https://www.braze.com/docs/api/api_limits/). ### Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `alias_updates` | Required | Array of update user alias objects | See [user alias object](https://www.braze.com/docs/api/objects_filters/user_alias_object/).

For more information on `old_alias_name`, `new_alias_name`, and `alias_label`, refer to [User aliases](https://www.braze.com/docs/user_guide/data_and_analytics/user_data_collection/user_profile_lifecycle/#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' /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](https://www.braze.com/docs/api/api_limits/). ### Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `user_aliases` | Required | Array of new user alias objects | See [user alias object](https://www.braze.com/docs/api/objects_filters/user_alias_object/).

For more information on `alias_name` and `alias_label`, check out our [User Aliases](https://www.braze.com/docs/user_guide/data_and_analytics/user_data_collection/user_profile_lifecycle/#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' /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](https://braze.com/docs/help/help_articles/api/delete_user/) 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](https://www.braze.com/docs/api/api_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](https://www.braze.com/docs/api/objects_filters/user_alias_object/) 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' /users/identify: post: tags: - User Data summary: Identify Users description: >- > Use this endpoint to identify an unidentified (alias-only) user. To use this endpoint, youll need to generate an API key with the `users.identify` permission. Calling `/users/identify` combines the alias-only profile with the identified profile and removes the alias-only profile. Identifying a user requires an `external_id` to be included in the `aliases_to_identify` object. If there is no user with that `external_id`, the `external_id` will simply be added to the aliased user's record, and the user will be considered identified. You can add up to 50 user aliases per request. Subsequently, you can associate multiple additional user aliases with a single `external_id`. - When these subsequent associations are made with the `merge_behavior` field set to `none`, only the push tokens and message history associated with the user alias are retained; any attributes, events, or purchases will be "orphaned" and not available on the identified user. One workaround is to export the aliased user's data before identification using the [`/users/export/ids` endpoint](https://www.braze.com/docs/api/endpoints/export/user_data/post_users_identifier/), then re-associate the attributes, events, and purchases with the identified user. - When associations are made with the `merge_behavior` field set to `merge`, this endpoint will merge [specific fields](#merge) found on the anonymous user to the identified user. > Note: To prevent unexpected loss of data when identifying users, we highly recommend that you first refer to [data collection best practices](https://www.braze.com/docs/user_guide/data_and_analytics/user_data_collection/best_practices/#capturing-user-data-when-alias-only-user-info-is-already-present) to learn about capturing user data when alias-only user info is already present. ### 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/alias/new` endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ### Parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `aliases_to_identify` | Required | Array of aliases to identify object | See [alias to identify object](https://www.braze.com/docs/api/objects_filters/aliases_to_identify/) and [user alias object](https://www.braze.com/docs/api/objects_filters/user_alias_object/). | | `merge_behavior` | Optional | String | One of `none` or `merge` is expected. | #### Merge_behavior field Setting the `merge_behavior` field to `merge` sets the endpoint to merge any of the following fields found **exclusively** on the anonymous user to the identified user. - First name - Last name - Email - Gender - Date of birth - Phone number - Time zone - Home city - Country - Language - Session count (the sum of sessions from both profiles) - Date of first session (Braze will pick the earlier date of the two dates) - Date of last session (Braze will pick the later date of the two dates) - Custom attributes - Custom event and purchase event data (excluding event properties) - Custom event and purchase event properties for "X times in Y days" segmentation (where X<=50 and Y<=30) - Segmentable custom events summary - Event count (the sum from both profiles) - Event first occurred (Braze will pick the earlier date of the two dates) - Event last occurred (Braze will pick the later date of the two dates) - In-app purchase total in cents (the sum from both profiles) - Total number of purchases (the sum from both profiles) - Date of first purchase (Braze will pick the earlier date of the two dates) - Date of last purchase (Braze will pick the later date of the two dates) - App summaries - Last_X_at fields (Braze will update the fields if the orphaned profile fields are more recent) - Campaign summaries (Braze will pick the most recent date fields) - Workflow summaries (Braze will pick the most recent date fields) - Message and message engagement history Any of the following fields found on the anonymous user to the identified user: - Custom event and purchase event count and first date and last date timestamps - These merged fields will update "for X events in Y days" filters. For purchase events, these filters include "number of purchases in Y days" and "money spent in last Y days". Session data will only be merged if the app exists on both user profiles. For example, if our target user doesn't have an app summary for "ABCApp" but our original user does, the target user will have the "ABCApp" app summary on their profile after the merge. Setting the field to `none` will not merge any user data to the identified user profile. ### Aliases to Identify object specification ``` json { "external_id" : (required, string) see External User ID below, // external_ids for users that do not exist will return a non-fatal error. // See Server Responses for details. "user_alias" : { "alias_name" : (required, string), "alias_label" : (required, string) } } ``` 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' /users/merge: post: tags: - User Data summary: Merge Users description: >- > Use this endpoint to merge one user into another user. To use this endpoint, youll need to generate an API key with the `users.merge` permission. Up to 50 merges may be specified per request. This endpoint is asynchronous. ## 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/alias/new`, `/users/identify`, and `/users/alias/update` endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/). ## Request parameters | Parameter | Required | Data Type | Description | | --- | --- | --- | --- | | `merge_updates` | Required | Array | An object array. Each object should contain an `identifier_to_merge` object and an `identifier_to_keep` object, which should each reference a user either by `external_id` or `user_alias`. Both users being merged must be identified using the same method. | ### Merge_updates behavior This endpoint will merge any of the following fields found exclusively on the original user to the target user. - First name - Last name - Email - Gender - Date of birth - Phone number - Time zone - Home city - Country - Language - Session count (the sum of sessions from both profiles) - Date of first session (Braze will pick the earlier date of the two dates) - Date of last session (Braze will pick the later date of the two dates) - Custom attributes - Custom event and purchase event data (excluding event properties) - Custom event and purchase event properties for "X times in Y days" segmentation (where X<=50 and Y<=30) - Segmentable custom events summary - Event count (the sum from both profiles) - Event first occurred (Braze will pick the earlier date of the two dates) - Event last occurred (Braze will pick the later date of the two dates) - In-app purchase total in cents (the sum from both profiles) - Total number of purchases (the sum from both profiles) - Date of first purchase (Braze will pick the earlier date of the two dates) - Date of last purchase (Braze will pick the later date of the two dates) - App summaries - Last_X_at fields (Braze will update the fields if the orphaned profile fields are more recent) - Campaign summaries (Braze will pick the most recent date fields) - Workflow summaries (Braze will pick the most recent date fields) Any of the following fields found on one user to the other user: - Custom event and purchase event count and first date and last date timestamps - These merged fields will update "for X events in Y days" filters. For purchase events, these filters include "number of purchases in Y days" and "money spent in last Y days". Session data will only be merged if the app exists on both user profiles. For example, if our target user doesn't have an app summary for "ABCApp" but our original user does, the target user will have the "ABCApp" app summary on their profile after the merge. Note that message and message engagement history aren't retained after both user profiles are merged. The endpoint does not guarantee the sequence of `merge_updates` objects being updated. ## Example request ``` curl --location --request POST 'https://rest.iad-03.braze.com/users/merge' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR-REST-API-KEY' \ --data-raw '{ "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" } } } ] }' ``` ## Response There are two status code responses for this endpoint: `202` and `400`. ### Example success response The status code `202` could return the following response body. ``` json { "message": "success" } ``` ### Example error response The status code `400` could return the following response body. Refer to Troubleshooting (below) for more information about errors you may encounter. ``` json { "message": "'merge_updates' must be an array of objects" } ``` ## Troubleshooting The following table lists possible error messages that may occur. | Error | Troubleshooting | | --- | --- | | `'merge_updates' must be an array of objects` | Ensure that `merge_updates` is an array of objects. | | `a single request may not contain more than 50 merge updates` | You can only specify up to 50 merge updates in a single request. | | `identifiers must be objects with an 'external_id' property that is a string, or 'user_alias' property that is an object` | Check the identifiers in your request. | | `identifiers must be objects of the same type` | Ensure that the identifier object types match. | | `'merge_updates' must only have 'identifier_to_merge' and 'identifier_to_keep'` | Ensure that `merge_updates` only contains the two objects `identifier_to_merge` and `identifier_to_keep`. | 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' security: - BearerAuth: []