Braze provides a high-performance REST API to allow you to track users, send messages, export data, and more. This reference article covers what a REST API is, the terminology, a brief overview of API keys, and API limits.
\nA REST API is a way to programmatically transfer information over the web using a predefined schema. Braze has created many different endpoints which perform various actions and/or return various data.
\nBraze manages a number of different instances for our dashboard and REST Endpoints. When your account is provisioned you will log in to one of the following URLs. Use the correct REST endpoint based on which instance you are provisioned to. If you are unsure, open a support ticket or use the following table to match the URL of the dashboard you use to the correct REST Endpoint.
\n\n\nCustomers using Braze’s EU database should use the
\nhttps://rest.fra-01.braze.eu/endpoint. This endpoint will be used when configuring the Braze iOS, Android, and Web SDKs.
If you have a Postman account (you can download macOS, Windows, and Linux versions from the Postman website ), you can open our Postman documentation in your own Postman app by clicking the orange Run in Postman button. You can then create an environment, or use our Braze REST API environment as a template, and edit the available POST and GET requests to suit your own needs.
The Braze Postman Collection uses a templating variable, {{instance_url}}, to substitute the REST API URL of your Braze instance into the pre-built requests, and the {{api_key}} variable for your API Key. Rather than having to manually edit all requests in the Collection, you can set up this variable in your Postman environment. You can either select our templated environment (Braze REST API Environment Template) from the dropdown and replace the variable values with your own, or you can set up your own environment.
To set up your own environment, perform the following steps:
\nFrom the Workspaces tab, select Environments.
\nClick the + plus button to create a new environment.
\nGive this environment a name (e.g., “Braze API Requests”) and add keys for instance_url and api_key with values corresponding to your Braze instance and Braze REST API Key.
Click Save.
\nOnce you have configured your environment. You can use any of the pre-built requests in the collection as a template for building new API requests. To start using one of the pre-built requests, click on it within the Collections menu of Postman. This will open the request as a new tab in the main window of the Postman app.
\nIn general, there are two types of requests that Braze’s API endpoints accept - GET and POST. Depending on which HTTP method the endpoint uses, you’ll need to edit the pre-built request differently.
When editing a POST request, open the request and navigate to the Body section in the request editor. For readability, select the raw radio button to format the JSON request body.
When editing a GET request, edit the parameters passed in the request URL. To do so, select the Params tab and edit the key-value pairs in the fields that appear.
Once your API request is ready, click Send. The request sends and the response data populates in a section underneath the request editor. From here, you can view the raw data returned from Braze’s API, see the HTTP response code, see how long the request took to process, and view header information.
\nThe following documentation can be found on the Braze documentation site:
\n\n\nUse this endpoint to delete a catalog.
\n
To use this endpoint, you’ll need an API key with the catalogs.delete permission.
This endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog endpoints, as documented in API rate limits.
\nThere are two status code responses for this endpoint: 200 and 404.
The status code 200 could return the following response body.
{\n \"message\": \"success\"\n}\n\nThe status code 404 could return the following response body. Refer to Troubleshooting for more information about errors you may encounter.
{\n \"errors\": [\n {\n \"id\": \"catalog-not-found\",\n \"message\": \"Could not find catalog\",\n \"parameters\": [\n \"catalog_name\"\n ],\n \"parameter_values\": [\n \"restaurants\"\n ]\n }\n ],\n \"message\": \"Invalid Request\"\n}\n\nThe following table lists possible returned errors and their associated troubleshooting steps.
\n","urlObject":{"protocol":"https","path":["catalogs","{catalog_name}"],"host":["{{instance_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"c0915a86-797a-4486-8217-24cd1c689d0f"},{"name":"List catalogs","id":"7d65fb86-ccf7-423f-9eb2-f68ab36df824","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/catalogs","description":"\n\nUse this endpoint to return a list of catalogs in a workspace.
\n
To use this endpoint, you’ll need an API key with the catalogs.get permission.
This endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog endpoints, as documented in API rate limits.
\nThere are no path or request parameters for this endpoint.
\ncurl --location --request GET 'https://rest.iad-03.braze.com/catalogs' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY'\n\nThe status code 200 could return the following response body.
{\n \"catalogs\": [\n {\n \"description\": \"My Restaurants\",\n \"fields\": [\n {\n \"name\": \"id\",\n \"type\": \"string\"\n },\n {\n \"name\": \"Name\",\n \"type\": \"string\"\n },\n {\n \"name\": \"City\",\n \"type\": \"string\"\n },\n {\n \"name\": \"Cuisine\",\n \"type\": \"string\"\n },\n {\n \"name\": \"Rating\",\n \"type\": \"number\"\n },\n {\n \"name\": \"Loyalty_Program\",\n \"type\": \"boolean\"\n },\n {\n \"name\": \"Created_At\",\n \"type\": \"time\"\n }\n ],\n \"name\": \"restaurants\",\n \"num_items\": 10,\n \"updated_at\": \"2022-11-02T20:04:06.879+00:00\"\n },\n {\n \"description\": \"My Catalog\",\n \"fields\": [\n {\n \"name\": \"id\",\n \"type\": \"string\"\n },\n {\n \"name\": \"string_field\",\n \"type\": \"string\"\n },\n {\n \"name\": \"number_field\",\n \"type\": \"number\"\n },\n {\n \"name\": \"boolean_field\",\n \"type\": \"boolean\"\n },\n {\n \"name\": \"time_field\",\n \"type\": \"time\"\n },\n ],\n \"name\": \"my_catalog\",\n \"num_items\": 3,\n \"updated_at\": \"2022-11-02T09:03:19.967+00:00\"\n },\n ],\n \"message\": \"success\"\n}\n\n\n\nUse this endpoint to create a catalog.
\n
To use this endpoint, you’ll need an API key with the catalogs.create permission.
This endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog endpoints, as documented in API rate limits.
\ncurl --location --request POST 'https://rest.iad-03.braze.com/catalogs' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY' \\\n--data-raw '{\n \"catalogs\": [\n {\n \"name\": \"restaurants\",\n \"description\": \"My Restaurants\",\n \"fields\": [\n {\n \"name\": \"id\",\n \"type\": \"string\"\n },\n {\n \"name\": \"Name\",\n \"type\": \"string\"\n },\n {\n \"name\": \"City\",\n \"type\": \"string\"\n },\n {\n \"name\": \"Cuisine\",\n \"type\": \"string\"\n },\n {\n \"name\": \"Rating\",\n \"type\": \"number\"\n },\n {\n \"name\": \"Loyalty_Program\",\n \"type\": \"boolean\"\n },\n {\n \"name\": \"Created_At\",\n \"type\": \"time\"\n }\n ]\n }\n ]\n}'\n\nThere are two status code responses for this endpoint: 201 and 400.
The status code 201 could return the following response body.
{\n \"catalogs\": [\n {\n \"description\": \"My Restaurants\",\n \"fields\": [\n {\n \"name\": \"id\",\n \"type\": \"string\"\n },\n {\n \"name\": \"Name\",\n \"type\": \"string\"\n },\n {\n \"name\": \"City\",\n \"type\": \"string\"\n },\n {\n \"name\": \"Cuisine\",\n \"type\": \"string\"\n },\n {\n \"name\": \"Rating\",\n \"type\": \"number\"\n },\n {\n \"name\": \"Loyalty_Program\",\n \"type\": \"boolean\"\n },\n {\n \"name\": \"Created_At\",\n \"type\": \"time\"\n }\n ],\n \"name\": \"restaurants\",\n \"num_items\": 0,\n \"updated_at\": \"2022-11-02T20:04:06.879+00:00\"\n }\n ],\n \"message\": \"success\"\n}\n\nThe status code 400 could return the following response body. Refer to Troubleshooting for more information about errors you may encounter.
{\n \"errors\": [\n {\n \"id\": \"catalog-name-already-exists\",\n \"message\": \"A catalog with that name already exists\",\n \"parameters\": [\n \"name\"\n ],\n \"parameter_values\": [\n \"restaurants\"\n ]\n }\n ],\n \"message\": \"Invalid Request\"\n}\n\nThe following table lists possible returned errors and their associated troubleshooting steps.
\n","urlObject":{"protocol":"https","path":["catalogs"],"host":["{{instance_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"af9f3e2d-b7e7-49e7-aa64-f4652892be6e"}],"id":"d12978e6-4b76-40d6-a5c1-0a27e5fdb1ca","_postman_id":"d12978e6-4b76-40d6-a5c1-0a27e5fdb1ca","description":""}],"id":"850d5c37-e893-4edc-99d5-4ce241e15843","_postman_id":"850d5c37-e893-4edc-99d5-4ce241e15843","description":""},{"name":"Catalog Items","item":[{"name":"Asynchronous","item":[{"name":"Delete multiple catalog items","id":"647c82e8-8b38-4df2-bde2-b1d8e19fd332","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/catalogs/{catalog_name}/items","description":"\n\nUse this endpoint to delete multiple items in your catalog.
\n
Each request can support up to 50 items. This endpoint is asynchronous.
\nTo use this endpoint, you’ll need an API key with the catalogs.delete_items permission.
This endpoint has a shared rate limit of 16,000 requests per minute between all asynchronous catalog item endpoints, as documented in API rate limits.
\ncurl --location --request DELETE 'https://rest.iad-03.braze.com/catalogs/restaurants/items' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY' \\\n--data-raw '{\n \"items\": [\n {\"id\": \"restaurant1\"},\n {\"id\": \"restaurant2\"},\n {\"id\": \"restaurant3\"}\n ]\n}'\n\nThere are three status code responses for this endpoint: 202, 400, and 404.
The status code 202 could return the following response body.
{\n \"message\": \"success\"\n}\n\nThe status code 400 could return the following response body. Refer to Troubleshooting for more information about errors you may encounter.
{\n \"errors\": [\n {\n \"id\": \"items-missing-ids\",\n \"message\": \"There are 1 item(s) that do not have ids\",\n \"parameters\": [],\n \"parameter_values\": []\n }\n ],\n \"message\": \"Invalid Request\",\n}\n\nThe following table lists possible returned errors and their associated troubleshooting steps.
\n","urlObject":{"protocol":"https","path":["catalogs","{catalog_name}","items"],"host":["{{instance_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"647c82e8-8b38-4df2-bde2-b1d8e19fd332"},{"name":"Edit multiple catalog items","id":"03f3548e-4139-4f60-812d-7e1a695a738a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PATCH","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/catalogs/{catalog_name}/items","description":"\n\nUse this endpoint to delete multiple items in your catalog.
\n
Each request can support up to 50 items. This endpoint is asynchronous.
\nTo use this endpoint, you’ll need an API key with the catalogs.update_items permission.
This endpoint has a shared rate limit of 16,000 requests per minute between all asynchronous catalog item endpoints, as documented in API rate limits.
\ncurl --location --request PATCH 'https://rest.iad-03.braze.com/catalogs/restaurants/items' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY' \\\n--data-raw '{\n \"items\": [\n {\n \"id\": \"restaurant1\",\n \"Name\": \"Restaurant\",\n \"Loyalty_Program\": false,\n \"Location\": {\n \"Latitude\": 33.6112,\n \"Longitude\": -117.8711\n },\n \"Top_Dishes\": {\n \"$add\": [\n \"Biscuits\",\n \"Coleslaw\"\n ],\n \"$remove\": [\n \"French Fries\"\n ]\n },\n \"Open_Time\": \"2021-09-03T09:03:19.967+00:00\"\n },\n {\n \"id\": \"restaurant3\",\n \"City\": \"San Francisco\",\n \"Rating\": 2,\n \"Top_Dishes\": [\n \"Buffalo Wings\",\n \"Philly Cheesesteak\"\n ]\n }\n ]\n}'\n\n\n\nNote: The $
\naddand$removeoperators are only applicable to array type fields, and are only supported by PATCH endpoints.
There are three status code responses for this endpoint: 202, 400, and 404.
The status code 202 could return the following response body.
{\n \"message\": \"success\"\n}\n\nThe status code 400 could return the following response body. Refer to Troubleshooting for more information about errors you may encounter.
{\n \"errors\": [\n {\n \"id\": \"invalid-fields\",\n \"message\": \"Some of the fields given do not exist in the catalog\",\n \"parameters\": [\n \"id\"\n ],\n \"parameter_values\": [\n \"restaurant1\"\n ]\n }\n ],\n \"message\": \"Invalid Request\"\n}\n\nThe following table lists possible returned errors and their associated troubleshooting steps.
\n","urlObject":{"protocol":"https","path":["catalogs","{catalog_name}","items"],"host":["{{instance_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"03f3548e-4139-4f60-812d-7e1a695a738a"},{"name":"Create multiple catalog items","id":"cea18bb3-b83a-4160-81fe-8cd42aa6e7cc","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/catalogs/{catalog_name}/items","description":"\n\nUse this endpoint to create multiple items in your catalog.
\n
Each request can support up to 50 items. This endpoint is asynchronous.
\nTo use this endpoint, you’ll need an API key with the catalogs.add_items permission.
This endpoint has a shared rate limit of 16,000 requests per minute between all asynchronous catalog item endpoints, as documented in API rate limits.
\ncurl --location --request POST 'https://rest.iad-03.braze.com/catalogs/restaurants/items' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY' \\\n--data-raw '{\n \"items\": [\n {\n \"id\": \"restaurant1\",\n \"Name\": \"Restaurant1\",\n \"City\": \"New York\",\n \"Cuisine\": \"American\",\n \"Rating\": 5,\n \"Loyalty_Program\": true,\n \"Location\": {\n \"Latitude\": 33.6112,\n \"Longitude\": -117.8711\n },\n \"Top_Dishes\": [\n \"Hamburger\",\n \"Deluxe Cheeseburger\"\n ],\n \"Created_At\": \"2022-11-01T09:03:19.967+00:00\"\n },\n {\n \"id\": \"restaurant2\",\n \"Name\": \"Restaurant2\",\n \"City\": \"New York\",\n \"Cuisine\": \"American\",\n \"Rating\": 10,\n \"Loyalty_Program\": true,\n \"Location\": {\n \"Latitude\": 40.7413,\n \"Longitude\": -73.9764\n },\n \"Top_Dishes\": [\n \"Hot Dog\",\n \"French Fries\"\n ],\n \"Created_At\": \"2022-11-02T09:03:19.967+00:00\"\n },\n {\n \"id\": \"restaurant3\",\n \"Name\": \"Restaurant3\",\n \"City\": \"New York\",\n \"Cuisine\": \"American\",\n \"Rating\": 3,\n \"Loyalty_Program\": false,\n \"Location\": {\n \"Latitude\": 40.7489,\n \"Longitude\": -73.9972\n },\n \"Top_Dishes\": [\n \"Buffalo Wings\",\n \"Philly Cheesesteak\"\n ],\n \"Created_At\": \"2022-11-03T09:03:19.967+00:00\"\n }\n ]\n}'\n\nThere are three status code responses for this endpoint: 202, 400, and 404.
The status code 202 could return the following response body.
{\n \"message\": \"success\"\n}\n\nThe status code 400 could return the following response body. Refer to Troubleshooting for more information about errors you may encounter.
{\n \"errors\": [\n {\n \"id\": \"fields-do-not-match\",\n \"message\": \"Fields do not match with fields on the catalog\",\n \"parameters\": [\n \"id\"\n ],\n \"parameter_values\": [\n \"restaurant2\"\n ]\n }\n ],\n \"message\": \"Invalid Request\"\n}\n\nThe following table lists possible returned errors and their associated troubleshooting steps.
\n","urlObject":{"protocol":"https","path":["catalogs","{catalog_name}","items"],"host":["{{instance_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"cea18bb3-b83a-4160-81fe-8cd42aa6e7cc"},{"name":"Update multiple catalog items","id":"ab30a4fc-60bc-4460-885c-1b92af8bc061","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PUT","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"items\": [\n {\n \"Name\": \"Restaurant\",\n \"Loyalty_Program\": false,\n \"Location\": {\n \"Latitude\": 33.6112,\n \"Longitude\": -117.8711\n },\n \"Open_Time\": \"2021-09-03T09:03:19.967+00:00\"\n }\n ]\n}"},"url":"https://{{instance_url}}/catalogs/{catalog_name}/items","description":"\n\nUse this endpoint to update multiple items in your catalog.
\n
If a catalog item doesn’t exist, this endpoint will create the item in your catalog. Each request can support up to 50 catalog items. This endpoint is asynchronous.
\nTo use this endpoint, you'll need an API key with the catalogs.replace_item permission.
This endpoint has a shared rate limit of 16,000 requests per minute between all asynchronous catalog item endpoints, as documented in API rate limits.
\ncurl --location --request PUT 'https://rest.iad-03.braze.com/catalogs/restaurants/items' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY' \\\n--data-raw '{\n \"items\": [\n {\n \"id\": \"restaurant1\",\n \"Name\": \"Restaurant\",\n \"Loyalty_Program\": false,\n \"Location\": {\n \"Latitude\": 33.6112,\n \"Longitude\": -117.8711\n },\n \"Top_Dishes\": [\n \"Hamburger\",\n \"Deluxe Cheeseburger\"\n ],\n \"Open_Time\": \"2021-09-03T09:03:19.967+00:00\"\n },\n {\n \"id\": \"restaurant3\",\n \"City\": \"San Francisco\",\n \"Rating\": 2,\n \"Top_Dishes\": [\n \"Hot Dog\",\n \"French Fries\"\n ]\n }\n ]\n}'\n\nThere are three status code responses for this endpoint: 202, 400, and 404.
The status code 202 could return the following response body.
{\n \"message\": \"success\"\n}\n\nThe status code 400 could return the following response body. Refer to Troubleshooting for more information about errors you may encounter.
{\n \"errors\": [\n {\n \"id\": \"invalid-fields\",\n \"message\": \"Some of the fields given do not exist in the catalog\",\n \"parameters\": [\n \"id\"\n ],\n \"parameter_values\": [\n \"restaurant1\"\n ]\n }\n ],\n \"message\": \"Invalid Request\"\n}\n\nThe following table lists possible returned errors and their associated troubleshooting steps.
\n","urlObject":{"protocol":"https","path":["catalogs","{catalog_name}","items"],"host":["{{instance_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"ab30a4fc-60bc-4460-885c-1b92af8bc061"}],"id":"7549210a-6b3e-4748-a22f-caa2e605066e","_postman_id":"7549210a-6b3e-4748-a22f-caa2e605066e","description":""},{"name":"Synchronous","item":[{"name":"Delete a catalog item","id":"0dcce797-1346-472f-9384-082f14541689","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/catalogs/{catalog_name}/items/{item_id}","description":"\n\nUse this endpoint to delete an item in your catalog.
\n
To use this endpoint, you’ll need an API key with the catalogs.delete_item permission.
This endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog item endpoints, as documented in API rate limits.
\nThere is no request body for this endpoint.
\ncurl --location --request DELETE 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY'\n\nThere are three status code responses for this endpoint: 202, 400, and 404.
The status code 202 could return the following response body.
{\n \"message\": \"success\"\n}\n\nThe status code 400 could return the following response body. Refer to Troubleshooting for more information about errors you may encounter.
{\n \"errors\": [\n {\n \"id\": \"item-not-found\",\n \"message\": \"Could not find item\",\n \"parameters\": [\n \"item_id\"\n ],\n \"parameter_values\": [\n \"restaurant34\"\n ]\n }\n ],\n \"message\": \"Invalid Request\"\n}\n\nThe following table lists possible returned errors and their associated troubleshooting steps.
\n","urlObject":{"protocol":"https","path":["catalogs","{catalog_name}","items","{item_id}"],"host":["{{instance_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"0dcce797-1346-472f-9384-082f14541689"},{"name":"List catalog item details","id":"52c6631c-7366-48e5-9e0e-16de7b6285cc","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/catalogs/{catalog_name}/items/{item_id}","description":"\n\nUse this endpoint to return a catalog item and its content.
\n
To use this endpoint, you’ll need an API key with the catalogs.get_item permission.
This endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog item endpoints, as documented in API rate limits.
\nThere is no request body for this endpoint.
\ncurl --location --request GET 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY'\n\nThere are two status code responses for this endpoint: 200 and 404.
The status code 200 could return the following response body.
{\n \"items\": [\n {\n \"id\": \"restaurant3\",\n \"Name\": \"Restaurant1\",\n \"City\": \"New York\",\n \"Cuisine\": \"American\",\n \"Rating\": 5,\n \"Loyalty_Program\": true,\n \"Open_Time\": \"2022-11-01T09:03:19.967Z\"\n }\n ],\n \"message\": \"success\"\n}\n\nThe status code 404 could return the following response. Refer to Troubleshooting for more information about errors you may encounter.
{\n \"errors\": [\n {\n \"id\": \"item-not-found\",\n \"message\": \"Could not find item\",\n \"parameters\": [\n \"item_id\"\n ],\n \"parameter_values\": [\n \"restaurant34\"\n ]\n }\n ],\n \"message\": \"Invalid Request\"\n}\n\nThe following table lists possible returned errors and their associated troubleshooting steps, if applicable.
\n","urlObject":{"protocol":"https","path":["catalogs","{catalog_name}","items","{item_id}"],"host":["{{instance_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"52c6631c-7366-48e5-9e0e-16de7b6285cc"},{"name":"List multiple catalog item details","id":"63a19dd5-10e0-4649-bdf0-097216748bbb","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/catalogs/{catalog_name}/items","description":"\n\nUse this endpoint to return multiple catalog items and their content.
\n
To use this endpoint, you’ll need an API key with the catalogs.get_items permission.
This endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog item endpoints, as documented in API rate limits.
\nNote 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.
There is no request body for this endpoint.
\ncurl --location --request GET 'https://rest.iad-03.braze.com/catalogs/restaurants/items' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY'\n\ncurl --location --request GET 'https://rest.iad-03.braze.com/catalogs/restaurants/items?cursor=c2tpcDow' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY'\n\nThere are three status code responses for this endpoint: 200, 400, and 404.
The status code 200 could return the following response header and body.
\n\nNote: The
\nLinkheader won't exist if the catalog has less than or equal to 50 items. For calls without a cursor,prevwill not show. When looking at the last page of items,nextwill not show.
Link: </catalogs/all_restaurants/items?cursor=c2tpcDow>; rel=\"prev\",</catalogs/all_restaurants/items?cursor=c2tpcDoxMDA=>; rel=\"next\"\n\n{\n \"items\": [\n {\n \"id\": \"restaurant1\",\n \"Name\": \"Restaurant1\",\n \"City\": \"New York\",\n \"Cuisine\": \"American\",\n \"Rating\": 5,\n \"Loyalty_Program\": true,\n \"Open_Time\": \"2022-11-02T09:03:19.967Z\"\n },\n {\n \"id\": \"restaurant2\",\n \"Name\": \"Restaurant2\",\n \"City\": \"New York\",\n \"Cuisine\": \"American\",\n \"Rating\": 10,\n \"Loyalty_Program\": true,\n \"Open_Time\": \"2022-11-02T09:03:19.967Z\"\n },\n {\n \"id\": \"restaurant3\",\n \"Name\": \"Restaurant3\",\n \"City\": \"New York\",\n \"Cuisine\": \"American\",\n \"Rating\": 5,\n \"Loyalty_Program\": false,\n \"Open_Time\": \"2022-11-02T09:03:19.967Z\"\n }\n ],\n \"message\": \"success\"\n}\n\nThe status code 400 could return the following response body. Refer to Troubleshooting for more information about errors you may encounter.
{\n \"errors\": [\n {\n \"id\": \"invalid-cursor\",\n \"message\": \"'cursor' is not valid\",\n \"parameters\": [\n \"cursor\"\n ],\n \"parameter_values\": [\n \"bad-cursor\"\n ]\n }\n ],\n \"message\": \"Invalid Request\"\n}\n\nThe following table lists possible returned errors and their associated troubleshooting steps.
\n","urlObject":{"protocol":"https","path":["catalogs","{catalog_name}","items"],"host":["{{instance_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"63a19dd5-10e0-4649-bdf0-097216748bbb"},{"name":"Edit catalog items","id":"e35976ae-ff77-42b7-b691-a883c980d8c0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PATCH","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"items\": [\n {\n \"Name\": \"Restaurant\",\n \"Loyalty_Program\": false,\n \"Open_Time\": \"2021-09-03T09:03:19.967+00:00\"\n }\n ]\n}"},"url":"https://{{instance_url}}/catalogs/{catalog_name}/items/{item_id}","description":"\n\nUse this endpoint to edit an item in your catalog.
\n
To use this endpoint, you’ll need an API key with the catalogs.update_item permission.
This endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog item endpoints, as documented in API rate limits.
\ncurl --location --request PATCH 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY' \\\n--data-raw '{\n \"items\": [\n {\n \"Name\": \"Restaurant\",\n \"Loyalty_Program\": false,\n \"Location\": {\n \"Latitude\": 33.6112,\n \"Longitude\": -117.8711\n },\n \"Top_Dishes\": {\n \"$add\": [\n \"Biscuits\",\n \"Coleslaw\"\n ],\n \"$remove\": [\n \"French Fries\"\n ]\n },\n \"Open_Time\": \"2021-09-03T09:03:19.967+00:00\"\n }\n ]\n}'\n\n\n\nNote: The $
\naddand$removeoperators are only applicable to array type fields, and are only supported by PATCH endpoints.
There are three status code responses for this endpoint: 200, 400, and 404.
The status code 200 could return the following response body.
{\n \"message\": \"success\"\n}\n\nThe status code 400 could return the following response body. Refer to Troubleshooting for more information about errors you may encounter.
{\n \"errors\": [\n {\n \"id\": \"invalid-fields\",\n \"message\": \"Some of the fields given do not exist in the catalog\",\n \"parameters\": [\n \"id\"\n ],\n \"parameter_values\": [\n \"restaurant1\"\n ]\n }\n ],\n \"message\": \"Invalid Request\"\n}\n\nThe following table lists possible returned errors and their associated troubleshooting steps.
\n","urlObject":{"protocol":"https","path":["catalogs","{catalog_name}","items","{item_id}"],"host":["{{instance_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"e35976ae-ff77-42b7-b691-a883c980d8c0"},{"name":"Create catalog item","id":"820c305b-ea6a-4b71-811a-55003a212a40","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"items\": [\n {\n \"Name\": \"Restaurant1\",\n \"City\": \"New York\",\n \"Cuisine\": \"American\",\n \"Rating\": 5,\n \"Loyalty_Program\": true,\n \"Created_At\": \"2022-11-01T09:03:19.967+00:00\"\n }\n ]\n}"},"url":"https://{{instance_url}}/catalogs/{catalog_name}/items/{item_id}","description":"\n\nUse this endpoint to create an item in your catalog.
\n
To use this endpoint, you’ll need an API key with the catalogs.create_item permission.
This endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog item endpoints, as documented in API rate limits.
\ncurl --location --request POST 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' \\\ncurl --location --request POST 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY' \\\n--data-raw '{\n \"items\": [\n {\n \"Name\": \"Restaurant1\",\n \"City\": \"New York\",\n \"Cuisine\": \"American\",\n \"Rating\": 5,\n \"Loyalty_Program\": true,\n \"Location\": {\n \"Latitude\": 33.6112,\n \"Longitude\": -117.8711\n },\n \"Top_Dishes\": [\n \"Hamburger\",\n \"Deluxe Cheeseburger\"\n ],\n \"Created_At\": \"2022-11-01T09:03:19.967+00:00\"\n }\n ]\n}'\n\nThere are three status code responses for this endpoint: 201, 400, and 404.
The status code 201 could return the following response body.
{\n \"message\": \"success\"\n}\n\nThe status code 400 could return the following response body. Refer to Troubleshooting for more information about errors you may encounter.
{\n \"errors\": [\n {\n \"id\": \"invalid-fields\",\n \"message\": \"Some of the fields given do not exist in the catalog\",\n \"parameters\": [\n \"id\"\n ],\n \"parameter_values\": [\n \"restaurant1\"\n ]\n }\n ],\n \"message\": \"Invalid Request\"\n}\n\nThe following table lists possible returned errors and their associated troubleshooting steps.
\n","urlObject":{"protocol":"https","path":["catalogs","{catalog_name}","items","{item_id}"],"host":["{{instance_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"820c305b-ea6a-4b71-811a-55003a212a40"},{"name":"Update catalog item","id":"b2871ed7-734e-4a37-b8f1-e11584e569f5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PUT","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"items\": [\n {\n \"Name\": \"Restaurant\",\n \"Loyalty_Program\": false,\n \"Location\": {\n \"Latitude\": 33.6112,\n \"Longitude\": -117.8711\n },\n \"Open_Time\": \"2021-09-03T09:03:19.967+00:00\"\n }\n ]\n}"},"url":"https://{{instance_url}}/catalogs/{catalog_name}/items/{item_id}","description":"\n\nUse this endpoint to update an item in your catalog.
\n
If the item_id isn't found, this endpoint will create the item. This endpoint is synchronous.
To use this endpoint, you'll need an API key with the catalogs.replace_item permission.
This endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog item endpoints, as documented in API rate limits.
\ncurl --location --request PUT 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY' \\\n--data-raw '{\n \"items\": [\n {\n \"Name\": \"Restaurant\",\n \"Loyalty_Program\": false,\n \"Location\": {\n \"Latitude\": 33.6112,\n \"Longitude\": -117.8711\n },\n \"Top_Dishes\": [\n \"Hamburger\",\n \"Deluxe Cheeseburger\"\n ],\n \"Open_Time\": \"2021-09-03T09:03:19.967+00:00\"\n }\n ]\n}'\n\nThere are three status code responses for this endpoint: 200, 400, and 404.
The status code 200 could return the following response body.
{\n \"message\": \"success\"\n}\n\nThe status code 400 could return the following response body. Refer to Troubleshooting for more information about errors you may encounter.
{\n \"errors\": [\n {\n \"id\": \"invalid-fields\",\n \"message\": \"Some of the fields given do not exist in the catalog\",\n \"parameters\": [\n \"id\"\n ],\n \"parameter_values\": [\n \"restaurant1\"\n ]\n }\n ],\n \"message\": \"Invalid Request\"\n}\n\nThe following table lists possible returned errors and their associated troubleshooting steps.
\n","urlObject":{"protocol":"https","path":["catalogs","{catalog_name}","items","{item_id}"],"host":["{{instance_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"b2871ed7-734e-4a37-b8f1-e11584e569f5"}],"id":"4d5f85a9-fbaa-4304-af83-a9a71206b5ed","_postman_id":"4d5f85a9-fbaa-4304-af83-a9a71206b5ed","description":""}],"id":"ab52029c-d19c-4241-b59a-f3c08f2815e8","_postman_id":"ab52029c-d19c-4241-b59a-f3c08f2815e8","description":""}],"id":"dbe0b381-5d9b-4e6d-9622-c934727d4b47","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.
\nLooking for guidance on creating a catalog? Check out our article for creating and using catalogs.
\n","_postman_id":"dbe0b381-5d9b-4e6d-9622-c934727d4b47"},{"name":"Email Lists & Addresses","item":[{"name":"Query hard bounced emails","id":"7c2ef84f-ddf5-451a-a72c-beeabc06ad9d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/email/hard_bounces?start_date=2019-01-01&end_date=2019-02-01&limit=100&offset=1&email=example@braze.com","description":"\n\nUse this endpoint to pull a list of email addresses that have “hard bounced” your email messages within a certain time frame.
\n
\n\nNote: You must provide an
\nend_date, as well as either anstart_date. If you provide all three,start_date,end_date, and an
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.
To use this endpoint, you’ll need an API key with the email.hard_bounces permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\ncurl --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' \\\n--header 'Authorization: Bearer YOUR-API-KEY-HERE'\n\nEntries are listed in descending order.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"emails\": [\n {\n \"email\": \"example1@braze.com\",\n \"hard_bounced_at\": \"2016-08-25 15:24:32 +0000\"\n },\n {\n \"email\": \"example2@braze.com\",\n \"hard_bounced_at\": \"2016-08-24 17:41:58 +0000\"\n },\n {\n \"email\": \"example3@braze.com\",\n \"hard_bounced_at\": \"2016-08-24 12:01:13 +0000\"\n }\n ],\n \"message\": \"success\"\n}\n\n(Optional*) String in YYYY-MM-DD format
\nStart 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.
(Optional*) String in YYYY-MM-DD format
\nString 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.
\n*You must provide either an email or a start_date, and an end_date.
(Optional) Integer
\nOptional field to limit the number of results returned. Defaults to 100, maximum is 500.
\n","type":"text/plain"},"key":"limit","value":"100"},{"description":{"content":"(Optional) Integer
\nOptional beginning point in the list to retrieve from.
\n","type":"text/plain"},"key":"offset","value":"1"},{"description":{"content":"(Optional*) String
\nIf provided, we will return whether or not the user has hard bounced.
\n*You must provide either an email or a start_date, and an end_date.
\n\nUse this endpoint to return emails that have unsubscribed during the time period from
\nstart_datetoend_date.
You can use this endpoint to set up a bi-directional sync between Braze and other email systems or your own database.
\n\n\nNote: You must provide an
\nend_date, as well as either anstart_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.
To use this endpoint, you’ll need an API key with the email.unsubscribe permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\ncurl --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' \\\n--header 'Authorization: Bearer YOUR-API-KEY-HERE'\n\nEntries are listed in descending order.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"emails\": [\n {\n \"email\": \"example1@braze.com\",\n \"unsubscribed_at\": \"2016-08-25 15:24:32 +0000\"\n },\n {\n \"email\": \"example2@braze.com\",\n \"unsubscribed_at\": \"2016-08-24 17:41:58 +0000\"\n },\n {\n \"email\": \"example3@braze.com\",\n \"unsubscribed_at\": \"2016-08-24 12:01:13 +0000\"\n }\n ],\n \"message\": \"success\"\n}\n\n(Optional*) String in YYYY-MM-DD format
\nStart date of the range to retrieve unsubscribes, must be earlier than end_date. This is treated as midnight in UTC time by the API.
\n","type":"text/plain"},"key":"start_date","value":"2020-01-01"},{"description":{"content":"(Optional*) String in YYYY-MM-DD format
\nEnd date of the range to retrieve unsubscribes. This is treated as midnight in UTC time by the API.
\n","type":"text/plain"},"key":"end_date","value":"2020-02-01"},{"description":{"content":"(Optional) Integer
\nOptional field to limit the number of results returned. Limit must be greater than 1. Defaults to 100, maximum is 500.
\n","type":"text/plain"},"key":"limit","value":"1"},{"description":{"content":"(Optional) Integer
\nOptional beginning point in the list to retrieve from.
\n","type":"text/plain"},"key":"offset","value":"1"},{"description":{"content":"(Optional) String
\nPass 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.
(Optional*) String
\nIf provided, we will return whether or not the user has unsubscribed.
\n","type":"text/plain"},"key":"email","value":"example@braze.com"}],"variable":[]}},"response":[],"_postman_id":"d2966b81-188a-407b-ba7e-e6c252c44b4a"},{"name":"Change email subscription status","id":"be852462-0cda-4a48-b68b-85bd8a9f2147","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","type":"text","value":"Bearer {{api_key}}"}],"body":{"mode":"raw","raw":"{\n \"email\": \"example@braze.com\",\n \"subscription_state\": \"subscribed\"\n}"},"url":"https://{{instance_url}}/email/status","description":"\n\nUse this endpoint to set the email subscription state for your users. Users can be
\nopted_in,unsubscribed, orsubscribed(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.
\nTo use this endpoint, you’ll need an API key with the email.status permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\n\n\nUse this endpoint to remove email addresses from your Braze bounce list and bounce list maintained by your email provider.
\n
To use this endpoint, you’ll need an API key with the email.bounce.remove permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\n\n\nUse this endpoint to remove email addresses from your Braze spam list and spam list maintained by your email provider.
\n
To use this endpoint, you’ll need an API key with the email.spam.remove permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\n\n\nUse this endpoint to unsubscribe a user from email and mark them as hard bounced.
\n
To use this endpoint, you’ll need an API key with the email.blacklist permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\n\n\nUse this endpoint to unsubscribe a user from email and mark them as hard bounced.
\n
To use this endpoint, you’ll need an API key with the email.blacklist permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nUsing this set of endpoints, you can update a user’s email subscription status, and use the Braze API to set up bi-directional sync between Braze and other email systems or your own database.
\n","_postman_id":"e4c30d01-354b-49db-8772-b86d64484600"},{"name":"Export","item":[{"name":"Campaign","item":[{"name":"Export campaign analytics","id":"c07b5ebd-0246-471e-b154-416d63ae28a1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/campaigns/data_series?campaign_id={{campaign_identifier}}&length=7&ending_at=2020-06-28T23:59:59-5:00","description":"\n\nUse this endpoint to retrieve a daily series of various stats for a campaign over time.
\n
Data returned includes how many messages were sent, opened, clicked, or converted by messaging channel.
\n\n\nNote: If you are using our older navigation,
\ncampaign_idcan be found at Developer Console > API Settings.
To use this endpoint, you’ll need an API key with the campaigns.data_series permission.
This endpoint has a rate limit of 50,000 requests per minute, as documented in API rate limits.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors,\n \"data\" : [\n {\n \"time\" : (string) date as ISO 8601 date,\n \"messages\" : {\n \"ios_push\" : [\n {\n \"variation_name\": \"iOS_Push\",\n \"sent\" : (int),\n \"direct_opens\" : (int),\n \"total_opens\" : (int),\n \"bounces\" : (int),\n \"body_clicks\" : (int)\n \"revenue\": 0,\n \"unique_recipients\": 1,\n \"conversions\": 0,\n \"conversions_by_send_time\": 0,\n \"conversions1\": 0,\n \"conversions1_by_send_time\": 0,\n \"conversions2\": 0,\n \"conversions2_by_send_time\": 0,\n \"conversions3\": 0,\n \"conversions3_by_send_time\": 0,\n \"carousel_slide_[NUM]_[TITLE]_click\": (optional, int),\n \"notif_button_[NUM]_[TITLE]_click\": (optional, int)\n }\n ],\n \"android_push\" : [\n {\n \"sent\" : (int),\n \"direct_opens\" : (int),\n \"total_opens\" : (int),\n \"bounces\" : (int),\n \"body_clicks\" : (int)\n }\n ],\n \"webhook\": [\n {\n \"sent\": (int),\n \"errors\": (int)\n }\n ],\n \"email\" : [\n {\n \"sent\": (int),\n \"opens\": (int),\n \"unique_opens\": (int),\n \"clicks\": (int),\n \"unique_clicks\": (int),\n \"unsubscribes\": (int),\n \"bounces\": (int),\n \"delivered\": (int),\n \"reported_spam\": (int)\n }\n ],\n \"sms\" : [\n {\n \"sent\": (int),\n \"delivered\": (int),\n \"undelivered\": (int),\n \"delivery_failed\": (int)\n }\n ]\n },\n \"conversions_by_send_time\": (optional, int),\n \"conversions1_by_send_time\": (optional, int),\n \"conversions2_by_send_time\": (optional, int),\n \"conversions3_by_send_time\": (optional, int),\n \"conversions\": (int),\n \"conversions1\": (optional, int),\n \"conversions2\": (optional, int),\n \"conversions3\": (optional, int),\n \"unique_recipients\": (int),\n \"revenue\": (optional, float)\n },\n ...\n ],\n ...\n}\n\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"data\" : [\n {\n \"time\" : (string) date as ISO 8601 date,\n \"conversions\" : (int),\n \"revenue\": (float),\n \"conversions_by_send_time\": (int),\n \"messages\" : {\n \"trigger_in_app_message\": [{\n \"variation_name\": (optional, string),\n \"impressions\": (int),\n \"clicks\": (int),\n \"first_button_clicks\": (int),\n \"second_button_clicks\": (int),\n \"revenue\": (optional, float),,\n \"unique_recipients\": (int),\n \"conversions\": (optional, int),\n \"conversions_by_send_time\": (optional, int),\n \"conversions1\": (optional, int),\n \"conversions1_by_send_time\": (optional, int),\n \"conversions2\": (optional, int),\n \"conversions2_by_send_time\": (optional, int),\n \"conversions3\": (optional, int),\n \"conversions3_by_send_time\": (optional, int)\n }, {\n \"variation_name\": (optional, string),\n \"impressions\": (int),\n \"clicks\": (int),\n \"first_button_clicks\": (int),\n \"second_button_clicks\": (int),\n \"revenue\": (optional, float),,\n \"unique_recipients\": (int),\n \"conversions\": (optional, int),\n \"conversions_by_send_time\": (optional, int),\n \"conversions1\": (optional, int),\n \"conversions1_by_send_time\": (optional, int),\n \"conversions2\": (optional, int),\n \"conversions2_by_send_time\": (optional, int),\n \"conversions3\": (optional, int).\n \"conversions3_by_send_time\": (optional, int)\n }, {\n \"variation_name\": (optional, string),\n \"revenue\": (optional, float),,\n \"unique_recipients\": (int),\n \"conversions\": (optional, int),\n \"conversions_by_send_time\": (optional, int),\n \"conversions1\": (optional, int),\n \"conversions1_by_send_time\": (optional, int),\n \"conversions2\": (optional, int),\n \"conversions2_by_send_time\": (optional, int),\n \"conversions3\": (optional, int),\n \"conversions3_by_send_time\": (optional, int),\n \"enrolled\": (optional, int)\n }]\n },\n \"conversions_by_send_time\": (optional, int),\n \"conversions1_by_send_time\": (optional, int),\n \"conversions2_by_send_time\": (optional, int),\n \"conversions3_by_send_time\": (optional, int),\n \"conversions\": (optional, int,\n \"conversions1\": (optional, int),\n \"conversions2\": (optional, int),\n \"conversions3\": (optional, int),\n \"unique_recipients\": (int),\n \"revenue\": (optional, float)\n }],\n ...\n}\n\nPossible 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.
\n\n","urlObject":{"protocol":"https","path":["campaigns","data_series"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Required) String
\n\nThe 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.
(Required) Integer
\nMax number of days before ending_at to include in the returned series. Must be between 1 and 100 (inclusive).
(Optional) Datetime (ISO 8601 string)
\nDate on which the data series should end. Defaults to time of the request.
\n","type":"text/plain"},"key":"ending_at","value":"2020-06-28T23:59:59-5:00"}],"variable":[]}},"response":[],"_postman_id":"c07b5ebd-0246-471e-b154-416d63ae28a1"},{"name":"Export campaign details","id":"aad2a811-7237-43b1-9d64-32042eabecd9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/campaigns/details?campaign_id={{campaign_identifier}}","description":"\n\nUse this endpoint to retrieve relevant information on a specified campaign, which can be identified by the
\ncampaign_id.
If you want to retrieve Canvas data, refer to the Canvas Details endpoint.
\n\n\nNote: If you are using our older navigation,
\ncampaign_idcan be found at Developer Console > API Settings
To use this endpoint, you’ll need an API key with the campaign.details permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\n{\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors,\n \"created_at\" : (string) the date created as ISO 8601 date,\n \"updated_at\" : (string) the date last updated as ISO 8601 date,\n \"archived\": (boolean) whether this campaign is archived,\n \"draft\": (boolean) whether this campaign is a draft,\n \"enabled\": (boolean) whether this campaign is active or not,\n \"has_post_launch_draft\": (boolean) whether this campaign has a post-launch draft,\n \"name\" : (string) the campaign name,\n \"description\" : (string) the campaign description,\n \"schedule_type\" : (string) the type of scheduling action,\n \"channels\" : (array) the list of channels to send via,\n \"first_sent\" : (string) the date and hour of first sent as ISO 8601 date,\n \"last_sent\" : (string) the date and hour of last sent as ISO 8601 date,\n \"tags\" : (array) the tag names associated with the campaign,\n \"teams\" : (array) the names of the Teams associated with the campaign,\n \"messages\": {\n \"message_variation_id\": (string) { // <=This is the actual id\n \"channel\": (string) the channel type of the message, must be either email, ios_push, webhook, content_card, in-app_message, or sms,\n \"name\": (string) the name of the message in the dashboard (for example, \"Variation 1\"),\n \"has_translatable_content\": (boolean) whether the message has translatable content (only present if `include_has_translatable_content` is true); `true` if locales are configured and the message contains at least one translation tag; `false` if no locales are configured or no translation tags detected; `null` if detection could not be completed,\n ... channel-specific fields for this message, see the following messages section ...\n }\n },\n \"conversion_behaviors\": (array) the conversion event behaviors assigned to the campaign, see the following conversions behavior section.\n}\n\nThe messages response will contain information about each message. The following includes example message responses for each channel:
{\n \"channel\": (string) description of the channel, such as \"ios_push\" or \"android_push\"\n \"alert\": (string) alert body text,\n \"extras\": (hash) any key value pairs provided\n}\n\n{\n \"channel\": \"email\",\n \"subject\": (string) subject,\n \"body\": (string) HTML body,\n \"from\": (string) from address and display name,\n \"reply_to\": (string) reply-to for message, if different than \"from\" address,\n \"title\": (string) name of the email,\n \"extras\": (hash) any key value pairs provided\n}\n\nThe response format depends on the type of in-app message. Survey in-app messages return type and data fields. Other in-app message types (slideup, modal, and fullscreen) return name, message, and extras fields.
{\n \"type\": (string) description of in-app message type, such as \"survey\",\n \"data\": {\n \"pages\": [\n {\n \"header\": \n {\n \"text\":(string) display text for the header of the survey,\n }\n \"choices\": [\n {\n \"choice_id\": (string) choice identifier,\n \"text\": (string) display text, \n \"custom_attribute_key\": (string) custom attribute key, \n \"custom_attribute_value\": (sting) custom attribute value,\n \"deleted\": (boolean) deleted from live campaign, \n },\n ...\n ]\n }\n ]\n }\n}\n\n{\n \"channel\": \"in_app_message\",\n \"name\": (string) the name of the variant,\n \"message\": (string, optional) the body text,\n \"extras\": (hash, optional) any key-value pairs provided; only present if at least one key-value pair has been set\n}\n\n{\n \"channel\": \"content_cards\",\n \"name\": (string) name of variant,\n \"extras\": (hash) any key value pairs provided; only present if at least one key-value pair has been set\n}\n\n{\n \"channel\": \"webhook\",\n \"url\": (string) url for webhook,\n \"body\": (string) payload body,\n \"type\": (string) body content type,\n \"headers\": (hash) specified request headers,\n \"method\": (string) HTTP method (e.g., \"POST\" or \"GET\"),\n}\n\n{\n \"channel\": \"sms\",\n \"body\": (string) payload body,\n \"from\": (string) list of numbers associated with the subscription group,\n \"subscription_group_id\": (string) API id of the subscription group targeted in the SMS message\n}\n\n{\n \"channel\": \"whats_app\",\n \"subscription_group_id\": (string) the API ID of the subscription group selected in the WhatsApp message\n \"from\": (array) the list of strings of the numbers associated with the subscription group,\n \"template_name\": (string) the name of the WhatsApp template being sent,\n \"template_language_code\": (string) the language code of the WhatsApp template being sent,\n \"header_variables\": (array) the list of strings, if present, of Liquid variables being inserted into header of WhatsApp template being sent,\n \"body_variables\": (array) the list of strings, if present, of Liquid variables being inserted into body of WhatsApp template being sent,\n \"button_variables\": (array) the list of strings, if present, of Liquid variables being inserted into buttons of WhatsApp template being sent\n}\n\n{\n \"channel\": \"whats_app\",\n \"subscription_group_id\": (string) the API ID of the subscription group selected in the WhatsApp message,\n \"from\": (array) list of strings of the numbers associated with the subscription group,\n \"layout\": (string) the name of the WhatsApp template being sent (text or media or quick-reply),\n \"header_text\": (string, optional) the text, if present, of the header of the message being sent,\n \"body_text\": (string, optional) the text, if present, of the body of the message being sent,\n \"footer_text\": (string, optional) the text, if present, of the footer of the message being sent,\n \"buttons\": (array) list of button objects in the message being sent ({\"text\": (string) the text of the button})\n}\n\n{\n \"channel\": (string) description of the channel that the control is for,\n \"type\": \"control\"\n}\n\nThe 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:
{\n \"type\": \"Clicks Email\",\n \"window\": (integer) number of seconds during which the user can convert on this event, i.e. - 86400, which is 24 hours\n}\n\n{\n \"type\": \"Opens Email\",\n \"window\": (integer) number of seconds during which the user can convert on this event, i.e. - 86400, which is 24 hours\n}\n\n{\n \"type\": \"Makes Any Purchase\",\n \"window\": (integer) number of seconds during which the user can convert on this event, i.e. - 86400, which is 24 hours\n}\n\n{\n \"type\": \"Makes Specific Purchase\",\n \"window\": (integer) number of seconds during which the user can convert on this event, i.e. - 86400, which is 24 hours,\n \"product\": (string) name of the product, i.e. - \"Feline Body Armor\"\n}\n\n{\n \"type\": \"Performs Custom Event\",\n \"window\": (integer) number of seconds during which the user can convert on this event, i.e. - 86400, which is 24 hours,\n \"custom_event_name\": (string) name of the event, i.e. - \"Used Feline Body Armor\"\n}\n\n{\n \"type\": \"Upgrades App\",\n \"window\": (integer) number of seconds during which the user can convert on this event, i.e. - 86400, which is 24 hours,\n \"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\n}\n\n{\n \"type\": \"Starts Session\",\n \"window\": (integer) number of seconds during which the user can convert on this event, i.e. - 86400, which is 24 hours,\n \"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\n}\n\n\n\n","urlObject":{"protocol":"https","path":["campaigns","details"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Required) String
\n\nThe 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.
(Optional) Boolean
\n","type":"text/plain"},"key":"post_launch_draft_version","value":null},{"disabled":true,"description":{"content":"(Optional) Boolean
\n","type":"text/plain"},"key":"include_has_translatable_content","value":null}],"variable":[]}},"response":[],"_postman_id":"aad2a811-7237-43b1-9d64-32042eabecd9"},{"name":"Export campaign list","id":"f3b0b3ef-04fb-4a31-8570-e6ad88dacb18","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/campaigns/list?page=0&include_archived=false&sort_direction=desc&last_edit.time[gt]=2020-06-28T23:59:59-5:00","description":"\n\nUse 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.
\n
The campaigns are returned in groups of 100 sorted by time of creation (oldest to newest by default).
\nTo use this endpoint, you’ll need an API key with the campaigns.list permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors,\n \"campaigns\" : [\n {\n \"id\" : (string) Campaign API Identifier,\n \"last_edited\": (ISO 8601 string) the last edited time for the message \n \"name\" : (string) campaign name,\n \"is_api_campaign\" : (boolean) whether the campaign is an API Campaign,\n \"tags\" : (array) tag names associated with the campaign\n },\n ...\n ]\n}\n\n\n\n","urlObject":{"protocol":"https","path":["campaigns","list"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Optional) Integer
\nThe page of campaigns to return, defaults to 0 (returns the first set of up to 100).
\n","type":"text/plain"},"key":"page","value":"0"},{"description":{"content":"(Optional) Boolean
\nWhether or not to include archived campaigns, defaults to false.
\n","type":"text/plain"},"key":"include_archived","value":"false"},{"description":{"content":"(Optional) String
\ndesc.asc.If sort_direction is not included, the default order is oldest to newest.
(Optional) Datetime (ISO 8601 string)
\nFilters the results and only returns campaigns that were edited greater than the time provided till now. Format is yyyy-MM-DDTHH:mm:ss.
\n\nUse this endpoint to retrieve a daily series of various stats for a tracked
\nsend_idfor API campaigns.
Braze stores send analytics for 14 days after the send. Campaign conversions will be attributed toward the most recent send_id that a given user has received from the campaign.
This endpoint is for API campaigns only. To use this endpoint, you'll need an API key with the sends.data_series permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"variation_name\": (string) variation name,\n \"sent\": (int) the number of sends,\n \"delivered\": (int) the number of messages successfully delivered,\n \"undelivered\": (int) the number of undelivered,\n \"delivery_failed\": (int) the number of rejected,\n \"direct_opens\": (int) the number of direct opens,\n \"total_opens\": (int) the number of total opens,\n \"bounces\": (int) the number of bounces,\n \"body_clicks\": (int) the number of body clicks,\n \"revenue\": (float) the number of dollars of revenue (USD),\n \"unique_recipients\": (int) the number of unique recipients,\n \"conversions\": (int) the number of conversions,\n \"conversions_by_send_time\": (int) the number of conversions,\n \"conversions1\": (int, optional) the number of conversions for the second conversion event,\n \"conversions1_by_send_time\": (int, optional) the number of conversions for the second conversion event by send time,\n \"conversions2\": (int, optional) the number of conversions for the third conversion event,\n \"conversions2_by_send_time\": (int, optional) the number of conversions for the third conversion event by send time,\n \"conversions3\": (int, optional) the number of conversions for the fourth conversion event,\n \"conversions3_by_send_time\": (int, optional) the number of conversions for the fourth conversion event by send time\n }\n ]\n },\n \"conversions_by_send_time\": 0,\n \"conversions1_by_send_time\": 0,\n \"conversions2_by_send_time\": 0,\n \"conversions3_by_send_time\": 0,\n \"conversions\": 0,\n \"conversions1\": 0,\n \"conversions2\": 0,\n \"conversions3\": 0,\n \"unique_recipients\": 1,\n \"revenue\": 0\n }\n ],\n \"message\": \"success\"\n}\n\n\n\n","urlObject":{"protocol":"https","path":["sends","data_series"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Required) String
\n\n","type":"text/plain"},"key":"campaign_id","value":"{{campaign_identifier}}"},{"description":{"content":"(Required) String
\nSee Send API identifier.
\n","type":"text/plain"},"key":"send_id","value":"{{send_identifier}}"},{"description":{"content":"(Required) Integer
\nMax number of days before ending_at to include in the returned series. Must be between 1 and 100 (inclusive).
(Optional) Datetime (ISO 8601 string)
\nDate on which the data series should end. Defaults to time of the request.
\n","type":"text/plain"},"key":"ending_at","value":"2014-12-10T23:59:59-05:00"}],"variable":[]}},"response":[],"_postman_id":"76f822a8-a13b-4bfb-b20e-72b5013dfe86"}],"id":"5cbed14c-dca8-4af6-abf1-dc5144bc48f5","_postman_id":"5cbed14c-dca8-4af6-abf1-dc5144bc48f5","description":""},{"name":"Canvas","item":[{"name":"Export Canvas data series analytics","id":"0fd61e93-7edf-4d87-a8dc-052420aefb73","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/canvas/data_series?canvas_id={{canvas_id}}&ending_at=2018-05-30T23:59:59-5:00&starting_at=2018-05-28T23:59:59-5:00&length=10&include_variant_breakdown=true&include_step_breakdown=true&include_deleted_step_data=true","description":"\n\nUse this endpoint to export time series data for a Canvas.
\n
To use this endpoint, you’ll need an API key with the canvas.data_series permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"data\": {\n \"name\": (string) Canvas name,\n \"stats\": [\n {\n \"time\": (string) date as ISO 8601 date,\n \"total_stats\": {\n \"revenue\": (float),\n \"conversions\": (int),\n \"conversions_by_entry_time\": (int),\n \"entries\": (int)\n },\n \"variant_stats\": (optional) {\n \"00000000-0000-0000-0000-0000000000000\": (API identifier for variant) {\n \"name\": (string) name of variant,\n \"revenue\": (int),\n \"conversions\": (int),\n \"conversions_by_entry_time\": (int),\n \"entries\": (int)\n },\n ... (more variants)\n },\n \"step_stats\": (optional) {\n \"00000000-0000-0000-0000-0000000000000\": (API identifier for step) {\n \"name\": (string) name of step,\n \"revenue\": (float),\n \"conversions\": (int),\n \"conversions_by_entry_time\": (int),\n \"messages\": {\n \"email\": [\n {\n \"sent\": (int),\n \"opens\": (int),\n \"unique_opens\": (int),\n \"clicks\": (int),\n ... (more stats)\n }\n ],\n ... (more channels)\n }\n },\n ... (more steps)\n }\n },\n ... (more stats by time)\n ]\n },\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors\n}\n\n\n\n","urlObject":{"protocol":"https","path":["canvas","data_series"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Required) String
\n\n","type":"text/plain"},"key":"canvas_id","value":"{{canvas_id}}"},{"description":{"content":"(Required) Datetime (ISO 8601 string)
\nDate on which the data export should end. Defaults to time of the request.
\n","type":"text/plain"},"key":"ending_at","value":"2018-05-30T23:59:59-5:00"},{"description":{"content":"(Optional*) Datetime (ISO 8601 string)
\nDate on which the data export should begin.
\n*Either length or starting_at is required.
(Optional*) String
\nMaximum 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.
(Optional) Boolean
\nWhether or not to include variant stats (defaults to false).
\n","type":"text/plain"},"key":"include_variant_breakdown","value":"true"},{"description":{"content":"(Optional) Boolean
\nWhether or not to include step stats (defaults to false).
\n","type":"text/plain"},"key":"include_step_breakdown","value":"true"},{"description":{"content":"(Optional) Boolean
\nWhether or not to include step stats for deleted steps (defaults to false).
\n","type":"text/plain"},"key":"include_deleted_step_data","value":"true"}],"variable":[]}},"response":[],"_postman_id":"0fd61e93-7edf-4d87-a8dc-052420aefb73"},{"name":"Export Canvas data analytics summary","id":"1eb1b760-6b00-4c03-bcfb-12646f2ba6da","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","type":"text","value":"Bearer {{api_key}}"}],"url":"https://{{instance_url}}/canvas/data_summary?canvas_id={{canvas_id}}&ending_at=2018-05-30T23:59:59-5:00&starting_at=2018-05-28T23:59:59-5:00&length=5&include_variant_breakdown=true&include_step_breakdown=true&include_deleted_step_data=true","description":"\n\nUse this endpoint to export rollups of time series data for a Canvas, providing a concise summary of a Canvas’ results.
\n
To use this endpoint, you’ll need an API key with the canvas.data_summary permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"data\": {\n \"name\": (string) Canvas name,\n \"total_stats\": {\n \"revenue\": (float),\n \"conversions\": (int),\n \"conversions_by_entry_time\": (int),\n \"entries\": (int)\n },\n \"variant_stats\": (optional) {\n \"00000000-0000-0000-0000-0000000000000\": (API identifier for variant) {\n \"name\": (string) name of variant,\n \"revenue\": (float),\n \"conversions\": (int),\n \"entries\": (int)\n },\n ... (more variants)\n },\n \"step_stats\": (optional) {\n \"00000000-0000-0000-0000-0000000000000\": (API identifier for step) {\n \"name\": (string) name of step,\n \"revenue\": (float),\n \"conversions\": (int),\n \"conversions_by_entry_time\": (int),\n \"messages\": {\n \"android_push\": (name of channel) [\n {\n \"sent\": (int),\n \"opens\": (int),\n \"influenced_opens\": (int),\n \"bounces\": (int)\n ... (more stats for channel)\n }\n ],\n ... (more channels)\n }\n },\n ... (more steps)\n }\n },\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors\n}\n\n\n\n","urlObject":{"protocol":"https","path":["canvas","data_summary"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Required) String
\n\n","type":"text/plain"},"key":"canvas_id","value":"{{canvas_id}}"},{"description":{"content":"(Required) Datetime (ISO 8601 string)\nDate on which the data export should end. Defaults to time of the request
\n","type":"text/plain"},"key":"ending_at","value":"2018-05-30T23:59:59-5:00"},{"description":{"content":"(Optional*) Datetime (ISO 8601 string)
\nDate on which the data export should begin.
\n*Either length or starting_at is required.
(Optional*) Integer
\nMax 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.
(Optional) Boolean
\nWhether or not to include variant stats (defaults to false).
\n","type":"text/plain"},"key":"include_variant_breakdown","value":"true"},{"description":{"content":"(Optional) Boolean
\nWhether or not to include step stats (defaults to false).
\n","type":"text/plain"},"key":"include_step_breakdown","value":"true"},{"description":{"content":"(Optional) Boolean
\nWhether or not to include step stats for deleted steps (defaults to false).
\n","type":"text/plain"},"key":"include_deleted_step_data","value":"true"}],"variable":[]}},"response":[],"_postman_id":"1eb1b760-6b00-4c03-bcfb-12646f2ba6da"},{"name":"Export Canvas details","id":"5188873c-13a3-4aaf-a54b-9fa1daeac5f8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/canvas/details?canvas_id={{canvas_identifier}}","description":"\n\nUse this endpoint to export metadata about a Canvas, such as the name, time created, current status, and more.
\n
To use this endpoint, you’ll need an API key with the canvas.details permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\n\n\nNote: All Canvas steps have a next_paths field, which is an array of
\n{name, next_step_id}data. For full steps and Message steps, thenext_step_idsfield will be present, but will not contain data for other Canvas Flow steps.
{\n \"created_at\": (string) the date created as ISO 8601 date,\n \"updated_at\": (string) the date updated as ISO 8601 date,\n \"name\": (string) the Canvas name,\n \"description\": (string) the Canvas description,\n \"archived\": (boolean) whether this Canvas is archived,\n \"draft\": (boolean) whether this Canvas is a draft,\n \"enabled\": (boolean) whether this Canvas is active or not,\n \"has_post_launch_draft\": (boolean) whether this Canvas has a post-launch draft,\n \"schedule_type\": (string) the type of scheduling action,\n \"first_entry\": (string) the date of first entry as ISO 8601 date,\n \"last_entry\": (string) the date of last entry as ISO 8601 date,\n \"channels\": (array of strings) step channels used with Canvas,\n \"variants\": [\n {\n \"name\": (string) the name of variant,\n \"id\": (string) the API identifier of the variant,\n \"first_step_ids\": (array of strings) the API identifiers for first steps in variant,\n \"first_step_id\": (string) the API identifier of first step in variant (deprecated in November 2017, only included if the variant has only one first step)\n },\n ... (more variations)\n ],\n \"tags\": (array of strings) the tag names associated with the Canvas,\n \"teams\" : (array) the names of the Teams associated with the Canvas,\n \"steps\": [\n {\n \"name\": (string) the name of step,\n \"type\" (string) the type of Canvas component,\n \"id\": (string) the API identifier of the step,\n \"next_step_ids\": (array of strings) IDs for next steps that are full steps or Message steps,\n \"next_paths\": { (array of objects)\n // for Decision Splits, this property should evaluate to \"Yes\" or \"No\"\n // for Audience Path and Action Paths, this property should evaluate to the group name\n // for Experiment Paths, this property should evaluate to the path name\n // for other steps, this property should evaluate to \"null\"\n \"name\": (string) name the name of step,\n \"next_step_id\": (string) IDs for next steps that are full steps or Message steps,\n }\n \"channels\": (array of strings) the channels used in step,\n \"messages\": {\n \"message_variation_id\": (string) { // <=This is the actual id\n \"channel\": (string) the channel type of the message (for example, \"email\"),\n \"has_translatable_content\": (boolean) whether the message has translatable content (only present if `include_has_translatable_content` is true); `true` if locales are configured and the message contains at least one translation tag; `false` if no locales are configured or no translation tags detected; `null` if detection could not be completed,\n // channel-specific fields for this message, see Campaign Details endpoint API Response for example message responses\n }\n }\n },\n ... (more steps)\n ],\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors\n}\n\n\n\n","urlObject":{"protocol":"https","path":["canvas","details"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Required) String
\n\n","type":"text/plain"},"key":"canvas_id","value":"{{canvas_identifier}}"},{"disabled":true,"description":{"content":"(Optional) Boolean
\n","type":"text/plain"},"key":"post_launch_draft_version","value":null},{"disabled":true,"description":{"content":"(Optional) Boolean
\n","type":"text/plain"},"key":"include_has_translatable_content","value":null}],"variable":[]}},"response":[],"_postman_id":"5188873c-13a3-4aaf-a54b-9fa1daeac5f8"},{"name":"Export Canvas list","id":"e6c150d7-fceb-4b10-91e2-a9ca4d5806d1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/canvas/list?page=1&include_archived=false&sort_direction=desc&last_edit.time[gt]=2020-06-28T23:59:59-5:00","description":"\n\nUse this endpoint to export a list of Canvases, including the name, Canvas API identifier and associated tags.
\n
Canvases are returned in groups of 100 sorted by time of creation (oldest to newest by default).
\nArchived 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, you’ll need an API key with the canvas.list permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"canvases\" : [\n {\n \"id\" : (string) Canvas API Identifier,\n \"last_edited\": (ISO 8601 string) the last edited time for the message,\n \"name\" : (string) Canvas name,\n \"tags\" : (array) tag names associated with the Canvas,\n },\n ... (more Canvases)\n ],\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors\n}\n\n\n\n","urlObject":{"protocol":"https","path":["canvas","list"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Optional) Integer
\nThe page of Canvases to return, defaults to 0 (returns the first set of up to 100).
(Optional) Boolean
\nWhether or not to include archived Canvases, defaults to false.
(Optional) String
\ndesc.asc.If sort_direction is not included, the default order is oldest to newest.
(Optional) Datetime (ISO 8601 string)
\nFilters the results and only returns Canvases that were edited greater than the time provided till now. Format is yyyy-MM-DDTHH:mm:ss.
\n\nUse 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.
\n
To use this endpoint, you’ll need an API key with the events.list permission.
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.
Content-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors,\n \"events\" : [\n \"Event A\", (string) the event name,\n \"Event B\", (string) the event name,\n \"Event C\", (string) the event name,\n ...\n ]\n}\n\nFor status codes and associated error messages that will be returned if your request encounters a fatal error, reference Fatal errors & responses.
\n\n\n","urlObject":{"protocol":"https","path":["events","list"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Optional) Integer
\nThe page of event names to return, defaults to 0 (returns the first set of up to 250).
\n","type":"text/plain"},"key":"page","value":"3"}],"variable":[]}},"response":[],"_postman_id":"93ecd8a5-305d-4b72-ae33-2d74983255c1"},{"name":"Export custom events analytics","id":"0bd1ab63-d1a5-4301-8d17-246cf24a178c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/events/data_series?event=event_name&length=24&unit=hour&ending_at=2014-12-10T23:59:59-05:00&app_id={{app_identifier}}&segment_id={{segment_identifier}}","description":"\n\nUse this endpoint to retrieve a series of the number of occurrences of a custom event in your app over a designated time period.
\n
To use this endpoint, you’ll need an API key with the events.data_series permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors,\n \"data\" : [\n {\n \"time\" : (string) point in time - as ISO 8601 extended when unit is \"hour\" and as ISO 8601 date when unit is \"day\",\n \"count\" : (int)\n },\n ...\n ]\n}\n\nFor status codes and associated error messages that will be returned if your request encounters a fatal error, reference Fatal errors & responses.
\n\n\n","urlObject":{"protocol":"https","path":["events","data_series"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Required) String
\nThe name of the custom event for which to return analytics.
\n","type":"text/plain"},"key":"event","value":"event_name"},{"description":{"content":"(Required) Integer
\nMaximum number of units (days or hours) before ending_at to include in the returned series. Must be between 1 and 100 (inclusive).
(Optional) String
\nUnit of time between data points - can be day or hour, defaults to day.
(Optional) Datetime (ISO 8601 string)
\nDate on which the data series should end. Defaults to time of the request.
\n","type":"text/plain"},"key":"ending_at","value":"2014-12-10T23:59:59-05:00"},{"description":{"content":"(Optional) String
\nApp API identifier retrieved from the API Keys page to limit analytics to a specific app.
\nNote: If you are using our older navigation, app_id can be found at Developer Console > API Settings
(Optional) String
\nSee Segment API identifier. Segment ID indicating the analytics-enabled segment for which event analytics should be returned.
\n","type":"text/plain"},"key":"segment_id","value":"{{segment_identifier}}"}],"variable":[]}},"response":[],"_postman_id":"0bd1ab63-d1a5-4301-8d17-246cf24a178c"}],"id":"fef2bce9-b482-4c2c-965e-85bd53caaa42","_postman_id":"fef2bce9-b482-4c2c-965e-85bd53caaa42","description":""},{"name":"KPI","item":[{"name":"Export daily new users by date","id":"07756c39-cfa0-40a0-8101-03f8791cec01","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/kpi/new_users/data_series?length=14&ending_at=2018-06-28T23:59:59-5:00&app_id={{app_identifier}}","description":"\n\nUse this endpoint to retrieve a daily series of the total number of new users on each date.
\n
Note: If you are using our older navigation, app_id can be found at Developer Console > API Settings.
To use this endpoint, you’ll need to generate an API key with the kpi.new_users.data_series permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors,\n \"data\" : [\n {\n \"time\" : (string) the date as ISO 8601 date,\n \"new_users\" : (int) the number of daily new users\n },\n ...\n ]\n}\n\n\n\n","urlObject":{"protocol":"https","path":["kpi","new_users","data_series"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Required) Integer
\nMaximum number of days before ending_at to include in the returned series. Must be between 1 and 100 (inclusive).
(Optional) Datetime (ISO 8601 string)
\nDate on which the data series should end. Defaults to time of the request.
\n","type":"text/plain"},"key":"ending_at","value":"2018-06-28T23:59:59-5:00"},{"description":{"content":"(Optional) String
\nApp API identifier retrieved from the API Keys page. If excluded, results for all apps in the workspace will be returned.
\n","type":"text/plain"},"key":"app_id","value":"{{app_identifier}}"}],"variable":[]}},"response":[],"_postman_id":"07756c39-cfa0-40a0-8101-03f8791cec01"},{"name":"Export daily active users by date","id":"90a64560-65aa-4f71-a8ef-1edf49321986","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/kpi/dau/data_series?length=10&ending_at=2018-06-28T23:59:59-5:00&app_id={{app_identifier}}","description":"\n\nUse this endpoint to retrieve a daily series of the total number of unique active users on each date.
\n
Note: If you are using our older navigation, API Keys can be found at Developer Console > API Settings.
\nTo use this endpoint, you’ll need to generate an API key with the kpi.dau.data_series permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors,\n \"data\" : [\n {\n \"time\" : (string) the date as ISO 8601 date,\n \"dau\" : (int) the number of daily active users\n },\n ...\n ]\n}\n\n\n\n","urlObject":{"protocol":"https","path":["kpi","dau","data_series"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Required) Integer
\nMaximum number of days before ending_at to include in the returned series. Must be between 1 and 100 (inclusive).
(Optional) Datetime (ISO 8601 string)\nDate on which the data series should end. Defaults to time of the request.
\n","type":"text/plain"},"key":"ending_at","value":"2018-06-28T23:59:59-5:00"},{"description":{"content":"(Optional) String
\nApp API identifier retrieved from the API Keys page. If excluded, results for all apps in the workspace will be returned.
\n","type":"text/plain"},"key":"app_id","value":"{{app_identifier}}"}],"variable":[]}},"response":[],"_postman_id":"90a64560-65aa-4f71-a8ef-1edf49321986"},{"name":"Export monthly active users for last 30 days","id":"68f45461-3bf1-425c-b918-f0bbf3f87149","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/kpi/mau/data_series?length=7&ending_at=2018-06-28T23:59:59-05:00&app_id={{app_identifier}}","description":"\n\nUse this endpoint to retrieve a daily series of the total number of unique active users over a 30-day rolling window.
\n
Note: If you are using our older navigation, API Keys can be found at Developer Console > API Settings.
\nTo use this endpoint, you’ll need to generate an API key with the kpi.mau.data_series permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors,\n \"data\" : [\n {\n \"time\" : (string) the date as ISO 8601 date,\n \"mau\" : (int) the number of monthly active users\n },\n ...\n ]\n}\n\n\n\n","urlObject":{"protocol":"https","path":["kpi","mau","data_series"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Required) Integer
\nMaximum number of days before ending_at to include in the returned series. Must be between 1 and 100 (inclusive).
(Optional) Datetime (ISO 8601 string)
\nDate on which the data series should end. Defaults to time of the request.
\n","type":"text/plain"},"key":"ending_at","value":"2018-06-28T23:59:59-05:00"},{"description":{"content":"(Optional) String
\nApp API identifier retrieved from the API Keys page. If excluded, results for all apps in the workspace will be returned.
\n","type":"text/plain"},"key":"app_id","value":"{{app_identifier}}"}],"variable":[]}},"response":[],"_postman_id":"68f45461-3bf1-425c-b918-f0bbf3f87149"},{"name":"Export KPIs for daily app uninstalls by date","id":"59c4d592-3e77-42f8-8ff1-d5d250acbeae","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/kpi/uninstalls/data_series?length=14&ending_at=2018-06-28T23:59:59-5:00&app_id={{app_identifier}}","description":"\n\nUse this endpoint to retrieve a daily series of the total number of uninstalls on each date.
\n
Note: If you are using our older navigation, API Keys can be found at Developer Console > API Settings.
\nTo use this endpoint, you’ll need to generate an API key with the kpi.uninstalls.data_series permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors,\n \"data\" : [\n {\n \"time\" : (string) the date as ISO 8601 date,\n \"uninstalls\" : (int) the number of uninstalls\n },\n ...\n ]\n}\n\n\n\n","urlObject":{"protocol":"https","path":["kpi","uninstalls","data_series"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Required) Integer
\nMaximum number of days before ending_at to include in the returned series. Must be between 1 and 100 (inclusive).
(Optional) Datetime (ISO 8601 string)
\nDate on which the data series should end. Defaults to time of the request.
\n","type":"text/plain"},"key":"ending_at","value":"2018-06-28T23:59:59-5:00"},{"description":{"content":"(Optional) String
\nApp API identifier retrieved from the API Keys page. If excluded, results for all apps in the workspace will be returned.
\n","type":"text/plain"},"key":"app_id","value":"{{app_identifier}}"}],"variable":[]}},"response":[],"_postman_id":"59c4d592-3e77-42f8-8ff1-d5d250acbeae"}],"id":"daae620d-ba97-4bb5-bce1-ede361670f56","_postman_id":"daae620d-ba97-4bb5-bce1-ede361670f56","description":""},{"name":"News Feed","item":[{"name":"Export News Feed Card analytics","id":"9cdc3b1e-641e-4d62-b9e8-42d04ee9d4d8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/feed/data_series?card_id={{card_identifier}}&length=14&unit=day&ending_at=2018-06-28T23:59:59-5:00","description":"\n\nUse this endpoint to retrieve a daily series of engagement stats for a card over time.
\n
Note: If you are using our older navigation, `card_id` can be found at Developer Console > API Settings.
\nTo use this endpoint, you’ll need to generate an API key with the feed.data_series permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors,\n \"data\" : [\n {\n \"time\" : (string) the point in time - as ISO 8601 extended when unit is \"hour\" and as ISO 8601 date when unit is \"day\",\n \"clicks\" : (int) the number of clicks,\n \"impressions\" : (int) the number of impressions,\n \"unique_clicks\" : (int) the number of unique clicks,\n \"unique_impressions\" : (int) the number of unique impressions\n },\n ...\n ]\n}\n\n\n\n","urlObject":{"protocol":"https","path":["feed","data_series"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Required) String
\nSee Card API identifier.
\nThe 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.
(Required) Integer
\nMax number of units (days or hours) before ending_at to include in the returned series. Must be between 1 and 100 (inclusive).
(Optional) String
\nUnit of time between data points. Can be day or hour, defaults to day.
(Optional) Datetime (ISO 8601 string)
\nDate on which the data series should end. Defaults to time of the request.
\n","type":"text/plain"},"key":"ending_at","value":"2018-06-28T23:59:59-5:00"}],"variable":[]}},"response":[],"_postman_id":"9cdc3b1e-641e-4d62-b9e8-42d04ee9d4d8"},{"name":"Export News Feed Cards details","id":"5b1401a6-f12c-4827-82c9-8dc604f1671e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","type":"text","value":"Bearer {{api_key}}"}],"url":"https://{{instance_url}}/feed/details?card_id={{card_identifier}}","description":"\n\nUse this endpoint to retrieve relevant information on a card, which can be identified by the
\ncard_id.
Note: If you are using our older navigation, card_id can be found at Developer Console > API Settings.
To use this endpoint, you’ll need to generate an API key with the feed.details permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"message\": (required, string) The status of the export, returns 'success' when completed without errors,\n \"created_at\" : (string) Date created as ISO 8601 date,\n \"updated_at\" : (string) Date last updated as ISO 8601 date,\n \"name\" : (string) Card name,\n \"publish_at\" : (string) Date card was published as ISO 8601 date,\n \"end_at\" : (string) Date card will stop displaying for users as ISO 8601 date,\n \"tags\" : (array) Tag names associated with the card,\n \"title\" : (string) Title of the card,\n \"image_url\" : (string) Image URL used by this card,\n \"extras\" : (dictionary) Dictionary containing key-value pair data attached to this card,\n \"description\" : (string) Description text used by this card,\n \"archived\": (boolean) whether this Card is archived,\n \"draft\": (boolean) whether this Card is a draft,\n}\n\n\n\n","urlObject":{"protocol":"https","path":["feed","details"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Required) String
\nSee Card API identifier.
\nThe 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.
\n\nUse this endpoint to export a list of News Feed cards, each of which will include its name and card API identifier.
\n
The cards are returned in groups of 100 sorted by time of creation (oldest to newest by default).
\nTo use this endpoint, you’ll need to generate an API key with the feed.list permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors,\n \"cards\" : [\n {\n \"id\" : (string) the card API identifier,\n \"type\" : (string) type of the card - NewsItem (classic cards), CaptionedImage, Banner\n \"title\" : (string) the title of the card,\n \"tags\" : (array) the tag names associated with the card\n },\n ...\n ]\n}\n\n\n\n","urlObject":{"protocol":"https","path":["feed","list"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Optional) Integer
\nThe page of cards to return, defaults to 0 (returns the first set of up to 100).
\n","type":"text/plain"},"key":"page","value":"1"},{"description":{"content":"(Optional) Boolean
\nWhether or not to include archived cards, defaults to false.
\n","type":"text/plain"},"key":"include_archived","value":"true"},{"description":{"content":"(Optional) String
\ndesc.asc.If sort_direction is not included, the default order is oldest to newest.
\n\nUse this endpoint to return a paginated lists of product IDs.
\n
To use this endpoint, you’ll need to generate an API key with the purchases.product_list permission.
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.
Content-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"products\": [\n \"product_name\" (string), the name of the product\n ],\n \"message\": \"success\"\n}\n\n\n\n","urlObject":{"protocol":"https","path":["purchases","product_list"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Optional) Integer
\nThe page of your product list that you would like to view.
\n","type":"text/plain"},"key":"page","value":"1"}],"variable":[]}},"response":[],"_postman_id":"dff4ed40-81f5-451d-9d44-accc0e932285"},{"name":"Export number of purchases","id":"6ac59282-d231-4317-88df-f7f12169b94e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/purchases/quantity_series?ending_at=2018-06-28T23:59:59-5:00&length=100&unit=14&app_id={{app_identifier}}&product=name","description":"\n\nUse this endpoint to return the total number of purchases in your app over a time range.
\n
To use this endpoint, you’ll need to generate an API key with the purchases.quantity_series permission.
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.
curl --location --request GET 'https://rest.iad-01.braze.com/purchases/quantity_series?length=100' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY'\n\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors,\n \"data\" : [\n {\n \"time\" : (string) the date as ISO 8601 date,\n \"purchase_quantity\" : (int) the number of items purchased in the time period\n },\n ...\n ]\n}\n\n\n\n","urlObject":{"protocol":"https","path":["purchases","quantity_series"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Optional) Datetime (ISO 8601 string)\nDate on which the data series should end. Defaults to time of the request.
\n","type":"text/plain"},"key":"ending_at","value":"2018-06-28T23:59:59-5:00"},{"description":{"content":"(Required) Integer\nMaximum number of days before ending_at to include in the returned series. Must be between 1 and 100 (inclusive).
\n","type":"text/plain"},"key":"length","value":"100"},{"description":{"content":"(Optional) String\nUnit of time between data points. Can be day or hour, defaults to day.
(Optional) String\nApp API identifier retrieved from the API Keys page. If excluded, results for all apps in the workspace will be returned.
\n","type":"text/plain"},"key":"app_id","value":"{{app_identifier}}"},{"description":{"content":"(Optional) String\nName of product to filter response by. If excluded, results for all apps will be returned.
\n","type":"text/plain"},"key":"product","value":"name"}],"variable":[]}},"response":[],"_postman_id":"6ac59282-d231-4317-88df-f7f12169b94e"},{"name":"Export revenue data by time","id":"f6e05f9a-13c0-4d66-8caa-4a376d25749f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/purchases/revenue_series?ending_at=2018-06-28T23:59:59-5:00&length=100&unit=14&app_id={{app_identifier}}&product=name","description":"\n\nUse this endpoint to return the total money spent in your app over a time range.
\n
To use this endpoint, you’ll need to generate an API key with the purchases.revenue_series permission.
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.
curl --location --request GET 'https://rest.iad-01.braze.com/purchases/revenue_series?length=100' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY'\n\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors,\n \"data\" : [\n {\n \"time\" : (string) the date as ISO 8601 date,\n \"revenue\" : (int) amount of revenue for the time period\n },\n ...\n ]\n}\n\n\n\n","urlObject":{"protocol":"https","path":["purchases","revenue_series"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Optional) Datetime (ISO 8601 string)\nDate on which the data series should end. Defaults to time of the request.
\n","type":"text/plain"},"key":"ending_at","value":"2018-06-28T23:59:59-5:00"},{"description":{"content":"(Required) Integer\nMaximum number of days before ending_at to include in the returned series. Must be between 1 and 100 (inclusive).
\n","type":"text/plain"},"key":"length","value":"100"},{"description":{"content":"(Optional) String\nUnit of time between data points. Can be day or hour, defaults to day.
(Optional) String\nApp API identifier retrieved from the Settings > Setup and Testing > API Keys to limit analytics to a specific app.
\n","type":"text/plain"},"key":"app_id","value":"{{app_identifier}}"},{"description":{"content":"(Optional) String\nName of product to filter response by. If excluded, results for all apps will be returned.
\n","type":"text/plain"},"key":"product","value":"name"}],"variable":[]}},"response":[],"_postman_id":"f6e05f9a-13c0-4d66-8caa-4a376d25749f"}],"id":"52f3ac64-fe73-4597-a3ff-bbfba2392738","_postman_id":"52f3ac64-fe73-4597-a3ff-bbfba2392738","description":""},{"name":"Segment","item":[{"name":"Export segment list","id":"1349e6f4-3ce7-4e60-b3e9-951c99c0993f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}"}],"url":"https://{{instance_url}}/segments/list?page=1&sort_direction=desc","description":"\n\nUse 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.
\n
The segments are returned in groups of 100 sorted by time of creation (oldest to newest by default). Archived segments are not included.
\nTo use this endpoint, you’ll need an API key with the segments.list permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors,\n \"segments\" : [\n {\n \"id\" : (string) Segment API Identifier,\n \"name\" : (string) segment name,\n \"analytics_tracking_enabled\" : (boolean) whether the segment has analytics tracking enabled,\n \"tags\" : (array) tag names associated with the segment\n },\n ...\n ]\n}\n\n\n\n","urlObject":{"protocol":"https","path":["segments","list"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Optional) Integer
\nThe page of segments to return, defaults to 0 (returns the first set of up to 100).
\n","type":"text/plain"},"key":"page","value":"1"},{"description":{"content":"(Optional) String
\ndesc.asc.If sort_direction is not included, the default order is oldest to newest.
\n\nUse this endpoint to retrieve a daily series of the estimated size of a segment over time.
\n
To use this endpoint, you’ll need an API key with the segments.data_series permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors,\n \"data\" : [\n {\n \"time\" : (string) date as ISO 8601 date,\n \"size\" : (int) size of the segment on that date\n },\n ...\n ]\n}\n\n\n\n","urlObject":{"protocol":"https","path":["segments","data_series"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Required) String
\n\nThe segment_id for a given segment can be found on the API Keys page within your Braze account or you can use the Export segment list endpoint.
(Required) Integer
\nMax number of days before ending_at to include in the returned series - must be between 1 and 100 (inclusive).
(Optional) Datetime (ISO 8601 string)
\nDate on which the data series should end. Defaults to time of the request.
\n","type":"text/plain"},"key":"ending_at","value":"2018-06-27T23:59:59-5:00"}],"variable":[]}},"response":[],"_postman_id":"62d9d142-cdec-4aea-a287-c13efea7415e"},{"name":"Export segment details","id":"aab56ed9-0a28-476a-8b57-b79786dbb9c1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/segments/details?segment_id={{segment_identifier}}","description":"\n\nUse this endpoint to retrieve relevant information on a segment, which can be identified by the
\nsegment_id.
To use this endpoint, you’ll need an API key with the segments.details permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors,\n \"created_at\" : (string) the date created as ISO 8601 date,\n \"updated_at\" : (string) the date last updated as ISO 8601 date,\n \"name\" : (string) the segment name,\n \"description\" : (string) a human-readable description of filters,\n \"text_description\" : (string) the segment description, \n \"tags\" : (array) the tag names associated with the segment formatted as strings,\n \"teams\" : (array) the names of the Teams associated with the campaign\n}\n\n\n\n","urlObject":{"protocol":"https","path":["segments","details"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Required) String
\n\nThe segment_id for a given segment can be found on the API Keys page within your Braze account or you can use the Export segment list endpoint.
\n\nUse this endpoint to retrieve a series of the number of sessions for your app over a designated time period.
\n
Note: If you are using our older navigation, segment_id can be found at Developer Console > API Settings.
To use this endpoint, you’ll need to generate an API key with the sessions.data_series permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors,\n \"data\" : [\n {\n \"time\" : (string) point in time - as ISO 8601 extended when unit is \"hour\" and as ISO 8601 date when unit is \"day\",\n \"sessions\" : (int)\n },\n ...\n ]\n}\n\n\n\n","urlObject":{"protocol":"https","path":["sessions","data_series"],"host":["{{instance_url}}"],"query":[{"description":{"content":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
(Required) Integer
\nMax number of days before ending_at to include in the returned series - must be between 1 and 100 (inclusive).
(Optional) String
\nUnit of time between data points. Can be day or hour, defaults to day.
(Optional) Datetime (ISO 8601 string)
\nDate on which the data series should end. Defaults to time of the request.
\n","type":"text/plain"},"key":"ending_at","value":"2018-06-28T23:59:59-5:00"},{"description":{"content":"(Optional) String
\nApp API identifier retrieved from the API Keys page to limit analytics to a specific app.
\n","type":"text/plain"},"key":"app_id","value":"{{app_identifier}}"},{"description":{"content":"(Required) String
\nSee Segment API identifier. Segment ID indicating the analytics-enabled segment for which sessions should be returned.
\n","type":"text/plain"},"key":"segment_id","value":"{{segment_identifier}}"}],"variable":[]}},"response":[],"_postman_id":"79efb6a9-62ec-4b8a-bf4a-e96313aa4be1"}],"id":"3e300d1e-2e15-4609-84bf-91f6651fb19a","_postman_id":"3e300d1e-2e15-4609-84bf-91f6651fb19a","description":""},{"name":"User Data","item":[{"name":"Export user profile by identifier","id":"b9750447-9d94-4263-967f-f816f0c76577","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"external_ids\": [\"user_identifier1\", \"user_identifier2\"],\n \"user_aliases\": [\n {\n \"alias_name\": \"example_alias\",\n \"alias_label\": \"example_label\"\n }\n ],\n \"device_id\": \"1234567\",\n \"braze_id\": \"braze_identifier\",\n \"email_address\": \"example@braze.com\",\n \"phone\": \"+11112223333\",\n \"fields_to_export\": [\"first_name\", \"email\", \"purchases\"]\n}"},"url":"https://{{instance_url}}/users/export/ids","description":"\n\nUse this endpoint to export data from any user profile by specifying a user identifier.
\n
Up to 50 external_ids or user_aliases can be included in a single request. Should you want to specify device_id, email_address , or phone, only one of any identifier can be included per request.
To use this endpoint, you’ll need an API key with the users.export.ids permission.
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.
\nThe 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:
Be aware that the /users/export/ids endpoint will pull together the entire user profile for this user, including data such as all campaigns and Canvases received, all custom events performed, all purchases made, and all custom attributes. As a result, this endpoint is slower than other REST API endpoints.
Depending on the data requested, this API endpoint may not be sufficient to meet your needs due to the 2,500 requests per minute rate limit. If you anticipate using this endpoint regularly to export users, instead consider exporting users by segment, which is asynchronous and more optimized for larger data pulls.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors,\n \"users\" : (array of object) the data for each of the exported users, may be empty if no users are found,\n \"invalid_user_ids\" : (optional, array of string) each of the identifiers provided in the request that did not correspond to a known user\n}\n\nFor an example of the data that is accessible via this endpoint see the following example.
\nUser 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):
\n{\n \"created_at\": (string),\n \"external_id\" : (string),\n \"user_aliases\" : [\n {\n \"alias_name\" : (string),\n \"alias_label\" : (string)\n }\n ],\n \"braze_id\": (string),\n \"first_name\" : (string),\n \"last_name\" : (string),\n \"email\" : (string),\n \"dob\" : (string) date for the user's date of birth,\n \"home_city\" : (string),\n \"country\" : (string) ISO-3166-1 alpha-2 standard,\n \"phone\" : (string),\n \"language\" : (string) ISO-639-1 standard,\n \"time_zone\" : (string),\n \"last_coordinates\" : (array of float) [lon, lat],\n \"gender\" : (string) \"M\" | \"F\",\n \"total_revenue\" : (float),\n \"attributed_campaign\" : (string),\n \"attributed_source\" : (string),\n \"attributed_adgroup\" : (string),\n \"attributed_ad\" : (string),\n \"push_subscribe\" : (string) \"opted_in\" | \"subscribed\" | \"unsubscribed\",\n \"email_subscribe\" : (string) \"opted_in\" | \"subscribed\" | \"unsubscribed\",\n \"custom_attributes\" : (object) custom attribute key-value pairs,\n \"custom_events\" : [\n {\n \"name\" : (string),\n \"first\" : (string) date,\n \"last\" : (string) date,\n \"count\" : (int)\n },\n ...\n ],\n \"purchases\" : [\n {\n \"name\" : (string),\n \"first\" : (string) date,\n \"last\" : (string) date,\n \"count\" : (int)\n },\n ...\n ],\n \"devices\" : [\n {\n \"model\" : (string),\n \"os\" : (string),\n \"carrier\" : (string),\n \"idfv\" : (string) only included for iOS devices when IDFV collection is enabled,\n \"idfa\" : (string) only included for iOS devices when IDFA collection is enabled,\n \"google_ad_id\" : (string) only included for Android devices when Google Play Advertising Identifier collection is enabled,\n \"roku_ad_id\" : (string) only included for Roku devices,\n \"ad_tracking_enabled\" : (bool)\n },\n ...\n ],\n \"push_tokens\" : [\n {\n \"app\" : (string) app name,\n \"platform\" : (string),\n \"token\" : (string)\n },\n ...\n ],\n \"apps\" : [\n {\n \"name\" : (string),\n \"platform\" : (string),\n \"version\" : (string),\n \"sessions\" : (integer),\n \"first_used\" : (string) date,\n \"last_used\" : (string) date\n },\n ...\n ],\n \"campaigns_received\" : [\n {\n \"name\" : (string),\n \"last_received\" : (string) date,\n \"engaged\" : \n {\n \"opened_email\" : (bool),\n \"opened_push\" : (bool),\n \"clicked_email\" : (bool),\n \"clicked_triggered_in_app_message\" : (bool)\n },\n \"converted\" : (bool),\n \"api_campaign_id\" : (string),\n \"variation_name\" : (optional, string) exists only if it is a multivariate campaign,\n \"variation_api_id\" : (optional, string) exists only if it is a multivariate campaign,\n \"in_control\" : (optional, bool) exists only if it is a multivariate campaign\n },\n ...\n ],\n \"canvases_received\": [\n {\n \"name\": (string),\n \"api_canvas_id\": (string),\n \"last_received_message\": (string) date,\n \"last_entered\": (string) date,\n \"variation_name\": (string),\n \"in_control\": (bool),\n \"last_exited\": (string) date,\n \"steps_received\": [\n {\n \"name\": (string),\n \"api_canvas_step_id\": (string),\n \"last_received\": (string) date\n },\n {\n \"name\": (string),\n \"api_canvas_step_id\": (string),\n \"last_received\": (string) date\n },\n {\n \"name\": (string),\n \"api_canvas_step_id\": (string),\n \"last_received\": (string) date\n }\n ]\n },\n ...\n ],\n \"cards_clicked\" : [\n {\n \"name\" : (string)\n },\n ...\n ]\n}\n\n{\n \"created_at\" : \"2020-07-10 15:00:00.000 UTC\",\n \"external_id\" : \"A8i3mkd99\",\n \"user_aliases\" : [\n {\n \"alias_name\" : \"user_123\",\n \"alias_label\" : \"amplitude_id\"\n }\n ],\n \"braze_id\": \"5fbd99bac125ca40511f2cb1\",\n \"random_bucket\" : 2365,\n \"first_name\" : \"Jane\",\n \"last_name\" : \"Doe\",\n \"email\" : \"example@braze.com\",\n \"dob\" : \"1980-12-21\",\n \"home_city\" : \"Chicago\",\n \"country\" : \"US\",\n \"phone\" : \"+442071838750\",\n \"language\" : \"en\",\n \"time_zone\" : \"Eastern Time (US & Canada)\",\n \"last_coordinates\" : [41.84157636433568, -87.83520818508256],\n \"gender\" : \"F\",\n \"total_revenue\" : 65,\n \"attributed_campaign\" : \"braze_test_campaign_072219\",\n \"attributed_source\" : \"braze_test_source_072219\",\n \"attributed_adgroup\" : \"braze_test_adgroup_072219\",\n \"attributed_ad\" : \"braze_test_ad_072219\",\n \"push_subscribe\" : \"opted_in\", \n \"push_opted_in_at\": \"2020-01-26T22:45:53.953Z\",\n \"email_subscribe\" : \"subscribed\",\n \"custom_attributes\": \n {\n \"loyaltyId\": \"37c98b9d-9a7f-4b2f-a125-d873c5152856\",\n \"loyaltyPoints\": \"321\",\n \"loyaltyPointsNumber\": 107\n },\n \"custom_events\": [\n {\n \"name\": \"Loyalty Acknowledgement\",\n \"first\": \"2021-06-28T17:02:43.032Z\",\n \"last\": \"2021-06-28T17:02:43.032Z\",\n \"count\": 1\n },\n ...\n ],\n \"purchases\": [\n {\n \"name\": \"item_40834\",\n \"first\": \"2021-09-05T03:45:50.540Z\",\n \"last\": \"2022-06-03T17:30:41.201Z\",\n \"count\": 10\n },\n ...\n ],\n \"devices\": [\n {\n \"model\": \"Pixel XL\",\n \"os\": \"Android (Q)\",\n \"carrier\": null,\n \"device_id\": \"312ef2c1-83db-4789-967-554545a1bf7a\",\n \"ad_tracking_enabled\": true\n },\n ...\n ],\n \"push_tokens\": [\n {\n \"app\": \"MovieCanon\",\n \"platform\": \"Android\",\n \"token\": \"12345abcd\",\n \"device_id\": \"312ef2c1-83db-4789-967-554545a1bf7a\",\n \"notifications_enabled\": true\n },\n ...\n ],\n \"apps\": [\n {\n \"name\": \"MovieCannon\",\n \"platform\": \"Android\",\n \"version\": \"3.29.0\",\n \"sessions\": 1129,\n \"first_used\": \"2020-02-02T19:56:19.142Z\",\n \"last_used\": \"2021-11-11T00:25:19.201Z\"\n },\n ...\n ],\n \"campaigns_received\": [\n {\n \"name\": \"Email Unsubscribe\",\n \"api_campaign_id\": \"d72fdc84-ddda-44f1-a0d5-0e79f47ef942\",\n \"last_received\": \"2022-06-02T03:07:38.105Z\",\n \"engaged\": \n {\n \"opened_email\": true\n },\n \"converted\": true,\n \"multiple_converted\": \n {\n \"Primary Conversion Event - A\": true\n },\n \"in_control\": false,\n \"variation_name\": \"Variant 1\",\n \"variation_api_id\": \"1bddc73a-a134-4784-9134-5b5574a9e0b8\"\n },\n ...\n ],\n \"canvases_received\": [\n {\n \"name\": \"Non Global Holdout Group 4/21/21\",\n \"api_canvas_id\": \"46972a9d-dc81-473f-aa03-e3473b4ed781\",\n \"last_received_message\": \"2021-07-07T20:46:24.136Z\",\n \"last_entered\": \"2021-07-07T20:45:24.000+00:00\",\n \"variation_name\": \"Variant 1\",\n \"in_control\": false,\n \"last_entered_control_at\": null,\n \"last_exited\": \"2021-07-07T20:46:24.136Z\",\n \"steps_received\": [\n {\n \"name\": \"Step\",\n \"api_canvas_step_id\": \"43d1a349-c3c8-4be1-9fbe-ce708e4d1c39\",\n \"last_received\": \"2021-07-07T20:46:24.136Z\"\n },\n ...\n ]\n }\n ...\n ], \n \"cards_clicked\" : [\n {\n \"name\" : \"Loyalty Promo\"\n },\n ...\n ]\n}\n\n\n\n","urlObject":{"protocol":"https","path":["users","export","ids"],"host":["{{instance_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"b9750447-9d94-4263-967f-f816f0c76577"},{"name":"Export user profile by segment","id":"cfa6fa98-632c-4f25-8789-6c3f220b9457","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","type":"text","value":"Bearer {{api_key}}"}],"body":{"mode":"raw","raw":"{\n \"segment_id\" : \"segment_identifier\",\n \"callback_endpoint\" : \"example_endpoint\",\n \"fields_to_export\" : [\"first_name\", \"email\", \"purchases\"],\n \"output_format\" : \"zip\"\n}"},"url":"https://{{instance_url}}/users/export/segment","description":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
\n\nUse this endpoint to export all the users within a segment.
\n
User data is exported as multiple files of user JSON objects separated by new lines (such as 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.
\nA company may run at most one export per segment using this endpoint at a given time. Wait for your export to complete before retrying.
\nNote: If you are using our older navigation, segment_id can be found at Developer Console > API Settings.
To use this endpoint, you’ll need an API key with the users.export.segment permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nIf you have added your S3, Azure, or Google Cloud Storage credentials to Braze, then each file will be uploaded in your bucket as a ZIP file with the key format that looks like segment-export/SEGMENT_ID/YYYY-MM-dd/RANDOM_UUID-TIMESTAMP_WHEN_EXPORT_STARTED/filename.zip. If using Azure, make sure that you have the Make this the default data export destination box checked in the Azure partner overview page in Braze. Generally, we will create 1 file per 5,000 users to optimize processing. Exporting smaller segments within a large workspace may result in multiple files. You can then extract the files and concatenate all of the json files to a single file if needed. If you specify an output_format of gzip, then the file extension will be .gz instead of .zip.
We strongly suggest setting up your own S3 or Azure credentials when using this endpoint to enforce your own bucket policies on the export. If you do not have your cloud storage credentials, the response to the request provides the URL where a ZIP file containing all the user files can be downloaded. The URL will only become a valid location after the export is ready.
\nZIP format: bucket-name/segment-export/SEGMENT_ID/YYYY-MM-dd/RANDOM_UUID-TIMESTAMP_WHEN_EXPORT_STARTED/filename.zip
Example ZIP: braze.docs.bucket/segment-export/abc56c0c-rd4a-pb0a-870pdf4db07q/2019-04-25/d9696570-dfb7-45ae-baa2-25e302r2da27-1556044807/114f0226319130e1a4770f2602b5639a.zip
Be aware that if you do not provide your cloud storage credentials, there is a limitation on the amount of data you can export from this endpoint. Depending on the fields you’re exporting and the number of users, the file transfer may fail if it is too large. A best practice is to specify which fields you want to export using fields_to_export and specify only the fields you need to keep the size of the transfer lower. If you are getting errors generating the file, consider breaking your user base into more segments based on a random bucket number (for example, create a segment where a random bucket number is less than 1,000 or between 1,000 and 2,000).
In either scenario, you may optionally provide a callback_endpoint to be notified when the export is ready. If the callback_endpoint is provided, we will make a post request to the provided address when the download is ready. The body of the post will be “success”:true. If you have not added S3 credentials to Braze, then the body of the post will additionally have the attribute url with the download URL as the value.
Larger user bases will result in longer export times. For example, an app with 20 million users could take an hour or more.
\nIf custom_attributes is included in the fields_to_export parameter, all custom attributes are exported regardless of what is in custom_attributes_to_export. If your goal is to export specific attributes, custom_attributes should not be included in the fields_to_export parameter. Instead, use the custom_attributes_to_export parameter.
The following is a list of valid fields_to_export. Using fields_to_export to minimize the data returned can improve the response time of this API endpoint:
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.
\nAttempting to export a segment a second time while the first export job is still running will result in a 429 error.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors,\n \"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',\n \"url\" : (optional, string) the URL where the segment export data can be downloaded if you do not have your own S3 credentials\n}\n\nOnce 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.
\nUser 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):
\n{\n \"external_id\" : (string),\n \"user_aliases\" : [\n {\n \"alias_name\" : (string),\n \"alias_label\" : (string)\n }\n ],\n \"braze_id\": (string),\n \"first_name\" : (string),\n \"last_name\" : (string),\n \"email\" : (string),\n \"dob\" : (string) date for the user's date of birth,\n \"home_city\" : (string),\n \"country\" : (string),\n \"phone\" : (string),\n \"language\" : (string) ISO-639 two letter code,\n \"time_zone\" : (string),\n \"last_coordinates\" : (array of float) [lon, lat],\n \"gender\" : (string) \"M\" | \"F\",\n \"total_revenue\" : (float),\n \"attributed_campaign\" : (string),\n \"attributed_source\" : (string),\n \"attributed_adgroup\" : (string),\n \"attributed_ad\" : (string),\n \"push_subscribe\" : (string) \"opted_in\" | \"subscribed\" | \"unsubscribed\",\n \"email_subscribe\" : (string) \"opted_in\" | \"subscribed\" | \"unsubscribed\",\n \"custom_attributes\" : (object) custom attribute key value pairs,\n \"custom_events\" : [\n {\n \"name\" : (string),\n \"first\" : (string) date,\n \"last\" : (string) date,\n \"count\" : (int)\n },\n ...\n ],\n \"purchases\" : [\n {\n \"name\" : (string),\n \"first\" : (string) date,\n \"last\" : (string) date,\n \"count\" : (int)\n },\n ...\n ],\n \"devices\" : [\n {\n \"model\" : (string),\n \"os\" : (string),\n \"carrier\" : (string),\n \"idfv\" : (string) only included for iOS devices,\n \"idfa\" : (string) only included for iOS devices when IDFA collection is enabled,\n \"google_ad_id\" : (string) only included for Android devices when Google Play Advertising Identifier collection is enabled,\n \"roku_ad_id\" : (string) only included for Roku devices,\n \"windows_ad_id\" : (string) only included for Windows devices,\n \"ad_tracking_enabled\" : (bool)\n },\n ...\n ],\n \"push_tokens\" : [\n {\n \"app\" : (string) app name,\n \"platform\" : (string),\n \"token\" : (string)\n },\n ...\n ],\n \"apps\" : [\n {\n \"name\" : (string),\n \"platform\" : (string),\n \"version\" : (string),\n \"sessions\" : (string),\n \"first_used\" : (string) date,\n \"last_used\" : (string) date\n },\n ...\n ],\n \"campaigns_received\" : [\n {\n \"name\" : (string),\n \"last_received\" : (string) date,\n \"engaged\" : {\n \"opened_email\" : (bool),\n \"opened_push\" : (bool),\n \"clicked_email\" : (bool),\n \"clicked_in_app_message\" : (bool)\n },\n \"converted\" : (bool),\n \"api_campaign_id\" : (string),\n \"variation_name\" : (optional, string) exists only if it is a multivariate campaign,\n \"variation_api_id\" : (optional, string) exists only if it is a multivariate campaign,\n \"in_control\" : (optional, bool) exists only if it is a multivariate campaign\n },\n ...\n ],\n \"canvases_received\": [\n {\n \"name\": (string),\n \"api_canvas_id\": (string),\n \"last_received_message\": (string) date,\n \"last_entered\": (string) date,\n \"variation_name\": (string),\n \"in_control\": (bool),\n \"last_exited\": (string) date,\n \"steps_received\": [\n {\n \"name\": (string),\n \"api_canvas_step_id\": (string),\n \"last_received\": (string) date\n },\n {\n \"name\": (string),\n \"api_canvas_step_id\": (string),\n \"last_received\": (string) date\n },\n {\n \"name\": (string),\n \"api_canvas_step_id\": (string),\n \"last_received\": (string) date\n }\n ]\n },\n ...\n ],\n \"cards_clicked\" : [\n {\n \"name\" : (string)\n },\n ...\n ]\n}\n\n{\n \"created_at\" : \"2020-07-10 15:00:00.000 UTC\",\n \"external_id\" : \"A8i3mkd99\",\n \"user_aliases\" : [\n {\n \"alias_name\" : \"user_123\",\n \"alias_label\" : \"amplitude_id\"\n }\n ],\n \"braze_id\": \"5fbd99bac125ca40511f2cb1\",\n \"random_bucket\" : 2365,\n \"first_name\" : \"Jane\",\n \"last_name\" : \"Doe\",\n \"email\" : \"example@braze.com\",\n \"dob\" : \"1980-12-21\",\n \"home_city\" : \"Chicago\",\n \"country\" : \"US\",\n \"phone\" : \"+442071838750\",\n \"language\" : \"en\",\n \"time_zone\" : \"Eastern Time (US & Canada)\",\n \"last_coordinates\" : [41.84157636433568, -87.83520818508256],\n \"gender\" : \"F\",\n \"total_revenue\" : 65,\n \"attributed_campaign\" : \"braze_test_campaign_072219\",\n \"attributed_source\" : \"braze_test_source_072219\",\n \"attributed_adgroup\" : \"braze_test_adgroup_072219\",\n \"attributed_ad\" : \"braze_test_ad_072219\",\n \"push_subscribe\" : \"opted_in\",\n \"push_opted_in_at\": \"2020-01-26T22:45:53.953Z\",\n \"email_subscribe\" : \"subscribed\",\n \"custom_attributes\":\n {\n \"loyaltyId\": \"37c98b9d-9a7f-4b2f-a125-d873c5152856\",\n \"loyaltyPoints\": \"321\",\n \"loyaltyPointsNumber\": 107\n },\n \"custom_events\": [\n {\n \"name\": \"Loyalty Acknowledgement\",\n \"first\": \"2021-06-28T17:02:43.032Z\",\n \"last\": \"2021-06-28T17:02:43.032Z\",\n \"count\": 1\n },\n ...\n ],\n \"purchases\": [\n {\n \"name\": \"item_40834\",\n \"first\": \"2021-09-05T03:45:50.540Z\",\n \"last\": \"2022-06-03T17:30:41.201Z\",\n \"count\": 10\n },\n ...\n ],\n \"devices\": [\n {\n \"model\": \"Pixel XL\",\n \"os\": \"Android (Q)\",\n \"carrier\": null,\n \"device_id\": \"312ef2c1-83db-4789-967-554545a1bf7a\",\n \"ad_tracking_enabled\": true\n },\n ...\n ],\n \"push_tokens\": [\n {\n \"app\": \"MovieCanon\",\n \"platform\": \"Android\",\n \"token\": \"12345abcd\",\n \"device_id\": \"312ef2c1-83db-4789-967-554545a1bf7a\",\n \"notifications_enabled\": true\n },\n ...\n ],\n \"apps\": [\n {\n \"name\": \"MovieCannon\",\n \"platform\": \"Android\",\n \"version\": \"3.29.0\",\n \"sessions\": 1129,\n \"first_used\": \"2020-02-02T19:56:19.142Z\",\n \"last_used\": \"2021-11-11T00:25:19.201Z\"\n },\n ...\n ],\n \"campaigns_received\": [\n {\n \"name\": \"Email Unsubscribe\",\n \"api_campaign_id\": \"d72fdc84-ddda-44f1-a0d5-0e79f47ef942\",\n \"last_received\": \"2022-06-02T03:07:38.105Z\",\n \"engaged\":\n {\n \"opened_email\": true\n },\n \"converted\": true,\n \"multiple_converted\":\n {\n \"Primary Conversion Event - A\": true\n },\n \"in_control\": false,\n \"variation_name\": \"Variant 1\",\n \"variation_api_id\": \"1bddc73a-a134-4784-9134-5b5574a9e0b8\"\n },\n ...\n ],\n \"canvases_received\": [\n {\n \"name\": \"Non Global Holdout Group 4/21/21\",\n \"api_canvas_id\": \"46972a9d-dc81-473f-aa03-e3473b4ed781\",\n \"last_received_message\": \"2021-07-07T20:46:24.136Z\",\n \"last_entered\": \"2021-07-07T20:45:24.000+00:00\",\n \"variation_name\": \"Variant 1\",\n \"in_control\": false,\n \"last_entered_control_at\": null,\n \"last_exited\": \"2021-07-07T20:46:24.136Z\",\n \"steps_received\": [\n {\n \"name\": \"Step\",\n \"api_canvas_step_id\": \"43d1a349-c3c8-4be1-9fbe-ce708e4d1c39\",\n \"last_received\": \"2021-07-07T20:46:24.136Z\"\n },\n ...\n ]\n }\n ...\n ],\n \"cards_clicked\" : [\n {\n \"name\" : \"Loyalty Promo\"\n },\n ...\n ]\n}\n\n\n\n","urlObject":{"protocol":"https","path":["users","export","segment"],"host":["{{instance_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"cfa6fa98-632c-4f25-8789-6c3f220b9457"},{"name":"Export user profile by Global Control Group","id":"aa3d8b90-d984-48f0-9287-57aa30469de2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"callback_endpoint\" : \"\",\n \"fields_to_export\" : [\"email\", \"braze_id\"],\n \"output_format\" : \"zip\"\n}"},"url":"https://{{instance_url}}/users/export/global_control_group","description":"Tip: For help with CSV and API exports, visit Export troubleshooting.
\n
\n\nUse this endpoint to export all users within a Global Control Group.
\n
User data is exported as multiple files of user JSON objects separated by new lines (such as one JSON object per line).
\nTo use this endpoint, you’ll need to generate an API key with the users.export.global_control_group permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nFor information regarding credentials-based response details, visit this section in the Braze API docs.
\nThe 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:
Content-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"message\": (required, string) the status of the export, returns 'success' when completed without errors,\n \"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',\n \"url\" : (optional, string) the URL where the segment export data can be downloaded if you do not have your own S3 credentials\n}\n\nOnce 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.
\nUser 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):
\n{\n \"created_at\" : (string),\n \"external_id\" : (string),\n \"user_aliases\" : [\n {\n \"alias_name\" : (string),\n \"alias_label\" : (string)\n }\n ],\n \"braze_id\": (string),\n \"first_name\" : (string),\n \"last_name\" : (string),\n \"email\" : (string),\n \"dob\" : (string) date for the user's date of birth,\n \"home_city\" : (string),\n \"country\" : (string) ISO-3166-1 alpha-2 standard,\n \"phone\" : (string),\n \"language\" : (string) ISO-639-1 standard,\n \"time_zone\" : (string),\n \"last_coordinates\" : (array of float) [lon, lat],\n \"gender\" : (string) \"M\" | \"F\",\n \"total_revenue\" : (float),\n \"attributed_campaign\" : (string),\n \"attributed_source\" : (string),\n \"attributed_adgroup\" : (string),\n \"attributed_ad\" : (string),\n \"custom_attributes\" : (object) custom attribute key-value pairs,\n \"custom_events\" : [\n {\n \"name\" : (string),\n \"first\" : (string) date,\n \"last\" : (string) date,\n \"count\" : (int)\n },\n ...\n ],\n \"purchases\" : [\n {\n \"name\" : (string),\n \"first\" : (string) date,\n \"last\" : (string) date,\n \"count\" : (int)\n },\n ...\n ],\n \"devices\" : [\n {\n \"model\" : (string),\n \"os\" : (string),\n \"carrier\" : (string),\n \"idfv\" : (string) only included for iOS devices when IDFV collection is enabled,\n \"idfa\" : (string) only included for iOS devices when IDFA collection is enabled,\n \"google_ad_id\" : (string) only included for Android devices when Google Play Advertising Identifier collection is enabled,\n \"roku_ad_id\" : (string) only included for Roku devices,\n \"ad_tracking_enabled\" : (bool)\n },\n ...\n ],\n \"apps\" : [\n {\n \"name\" : (string),\n \"platform\" : (string),\n \"version\" : (string),\n \"sessions\" : (string),\n \"first_used\" : (string) date,\n \"last_used\" : (string) date\n },\n ...\n ],\n}\n\n{\n{\n \"created_at\" : \"2020-07-10 15:00:00.000 UTC\",\n \"external_id\" : \"A8i3mkd99\",\n \"user_aliases\" : [\n {\n \"alias_name\" : \"user_123\",\n \"alias_label\" : \"amplitude_id\"\n }\n ],\n \"braze_id\": \"5fbd99bac125ca40511f2cb1\",\n \"random_bucket\" : 2365,\n \"first_name\" : \"Jane\",\n \"last_name\" : \"Doe\",\n \"email\" : \"example@braze.com\",\n \"dob\" : \"1980-12-21\",\n \"home_city\" : \"Chicago\",\n \"country\" : \"US\",\n \"phone\" : \"+442071838750\",\n \"language\" : \"en\",\n \"time_zone\" : \"Eastern Time (US & Canada)\",\n \"last_coordinates\" : [41.84157636433568, -87.83520818508256],\n \"gender\" : \"F\",\n \"total_revenue\" : 65,\n \"attributed_campaign\" : \"braze_test_campaign_072219\",\n \"attributed_source\" : \"braze_test_source_072219\",\n \"attributed_adgroup\" : \"braze_test_adgroup_072219\",\n \"attributed_ad\" : \"braze_test_ad_072219\",\n \"custom_attributes\": \n {\n \"loyaltyId\": \"37c98b9d-9a7f-4b2f-a125-d873c5152856\",\n \"loyaltyPoints\": \"321\",\n \"loyaltyPointsNumber\": 107\n },\n \"custom_events\": [\n {\n \"name\": \"Loyalty Acknowledgement\",\n \"first\": \"2021-06-28T17:02:43.032Z\",\n \"last\": \"2021-06-28T17:02:43.032Z\",\n \"count\": 1\n },\n ...\n ],\n \"purchases\": [\n {\n \"name\": \"item_40834\",\n \"first\": \"2021-09-05T03:45:50.540Z\",\n \"last\": \"2022-06-03T17:30:41.201Z\",\n \"count\": 10\n },\n ...\n ],\n \"devices\": [\n {\n \"model\": \"Pixel XL\",\n \"os\": \"Android (Q)\",\n \"carrier\": null,\n \"device_id\": \"312ef2c1-83db-4789-967-554545a1bf7a\",\n \"ad_tracking_enabled\": true\n },\n ...\n ],\n \"apps\": [\n {\n \"name\": \"MovieCannon\",\n \"platform\": \"Android\",\n \"version\": \"3.29.0\",\n \"sessions\": 1129,\n \"first_used\": \"2020-02-02T19:56:19.142Z\",\n \"last_used\": \"2021-11-11T00:25:19.201Z\"\n },\n ...\n ],\n}\n\nWith this collection of endpoints, you can access and export various levels of details on your KPIs, News Feed cards, app sessions, users, segments, campaigns, and Canvases.
\nMake sure you know your Braze instance, API key, and API identifier when building out your parameters and request bodies.
\n","event":[{"listen":"prerequest","script":{"id":"83eafd8c-742a-49ca-98e5-9ec576024e11","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"79beea13-2613-4cfc-ba5f-4f679fc60508","type":"text/javascript","exec":[""]}}],"_postman_id":"ab13bde6-e353-4682-889f-48da9af2a136"},{"name":"Messages","item":[{"name":"Live Activities","item":[{"name":"Update Live Activity","id":"2300226e-f26a-4154-9bcc-5883f1f294cd","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"app_id\": \"{YOUR-APP-API-IDENTIFIER}\",\n \"activity_id\": \"live-activity-1\",\n \"content_state\": {\n \"teamOneScore\": 2,\n \"teamTwoScore\": 4\n },\n \"end_activity\": false,\n \"dismissal_date\": \"2023-02-28T00:00:00+0000\",\n \"stale_date\": \"2023-02-27T16:55:49+0000\",\n \"notification\": {\n \"alert\": {\n \"body\": \"It's halftime! Let's look at the scores\",\n \"title\": \"Halftime\"\n }\n }\n}"},"url":"https://{{instance_url}}/messages/live_activity/update","description":"\n\nUse this endpoint to update and end Live Activities displayed by your iOS app. This endpoint requires additional setup.
\n
After you register a Live Activity, you can pass a JSON payload to update your Apple Push Notification service (APNs). See Apple’s documentation on updating your Live Activity with push notification payloads for more information.
\nTo use this endpoint, you’ll need to complete the following:
\nGenerate an API key with the messages.live_activity.update permission.
Register a Live Activity remotely or locally using the Braze Swift SDK.
\nWe apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nThere are two status code responses for this endpoint: 201 and 4XX.
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.
{\n \"message\": \"success\"\n}\n\nThe 4XX class of status code indicates a client error. Refer to the API errors and responses article for more information about errors you may encounter.
The status code 400 could return the following response body.
{\n \"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' \"\n}\n\n\n\nUse this endpoint to return a JSON list of information about scheduled campaigns and entry Canvases between now and a designated
\nend_timespecified in the request.
Daily, recurring messages will only appear once with their next occurrence. Results returned in this endpoint include campaigns and Canvases created and scheduled in the Braze dashboard.
\nTo use this endpoint, you’ll need an API key with the messages.schedule_broadcasts permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"scheduled_broadcasts\": [\n {\n \"name\" (string) the name of the scheduled broadcast,\n \"id\" (stings) the Canvas or campaign identifier,\n \"type\" (string) the broadcast type either Canvas or Campaign,\n \"tags\" (array) an array of tag names formatted as strings,\n \"next_send_time\" (string) The next send time formatted in ISO 8601, may also include time zone if not local/intelligent delivery,\n \"schedule_type\" (string) The schedule type, either local_time_zones, intelligent_delivery or the name of your company's time zone,\n },\n ]\n}\n\n(Required) String in ISO 8601 format
\nEnd date of the range to retrieve upcoming scheduled Campaigns and Canvases. This is treated as midnight in UTC time by the API.
\n","type":"text/plain"},"key":"end_time","value":"2018-09-01T00:00:00-04:00"}],"variable":[]}},"response":[],"_postman_id":"6f623cc3-383b-4bf7-b14d-7c56fc5562f5"},{"name":"Delete scheduled messages","id":"5e89355c-0a5d-4d8b-8d89-2fd99bac36b0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"},{"key":"Authorization","type":"text","value":"Bearer {{api_key}}"}],"body":{"mode":"raw","raw":"{\n \"schedule_id\": \"schedule_identifier\"\n}"},"url":"https://{{instance_url}}/messages/schedule/delete","description":"\n\nUse this endpoint to cancel a message that you previously scheduled before it has been sent.
\n
To use this endpoint, you’ll need an API key with the messages.schedule.delete permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\n\n\nUse this endpoint to cancel a Canvas message that you previously scheduled via API-triggered before it has been sent.
\n
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.
\nTo use this endpoint, you’ll need an API key with the canvas.trigger.schedule.delete permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\n","urlObject":{"protocol":"https","path":["canvas","trigger","schedule","delete"],"host":["{{instance_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"5f655193-ecd4-495a-93cf-40ab1700efd0"},{"name":"Delete scheduled API-triggered campaigns","id":"7d34037f-4bf2-4fab-bc9c-c972988051a7","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"},{"key":"Authorization","type":"text","value":"Bearer {{api_key}}"}],"body":{"mode":"raw","raw":"{\n \"campaign_id\": \"campaign_identifier\",\n \"schedule_id\": \"schedule_identifier\"\n}"},"url":"https://{{instance_url}}/campaigns/trigger/schedule/delete","description":"\n\nThe delete schedule endpoint allows you to cancel a message that you previously scheduled API-triggered Canvases before it has been sent.
\n
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.
\nTo use this endpoint, you’ll need to generate an API key with the campaigns.trigger.schedule.delete permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\n\n\nUse this endpoint to schedule a campaign, Canvas, or other message to be sent at a designated time and provides you with an identifier to reference that message for updates.
\n
If you are targeting a segment, a record of your request will be stored in the Developer Console after all scheduled messages have been sent.
\nTo use this endpoint, you’ll need an API key with the messages.schedule.create permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nBraze endpoints support batching API requests. A single request to the messaging endpoints can reach any of the following:
\nsegment_id{\n \"dispatch_id\": (string) the dispatch identifier,\n \"schedule_id\": (string) the schedule identifier,\n \"message\": \"success\"\n}\n\n\n\nUse this endpoint to send dashboard created campaign messages via API-triggered delivery, allowing you to decide what action should trigger the message to be sent.
\n
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.
\nTo use this endpoint, you’ll need an API key with the campaigns.trigger.schedule.create permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nBraze endpoints support batching API requests. A single request to the messaging endpoints can reach any of the following:
\nsegment_idContent-Type: application/json\nAuthorization: Bearer YOUR-API-KEY-HERE\n{\n{\n \"dispatch_id\": \"dispatch_identifier\",\n \"schedule_id\": \"schedule_identifier\",\n \"message\": \"success\"\n}\n\n\n\nUse this endpoint to schedule Canvas messages via API-triggered delivery, allowing you to decide what action should trigger the message to be sent.
\n
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 created when you build a Canvas.
\nTo use this endpoint, you’ll need an API key with the canvas.trigger.schedule.create permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nBraze endpoints support batching API requests. A single request to the messaging endpoints can reach any of the following:
\nsegment_id\n\nUse this endpoint to update scheduled messages.
\n
This endpoint accepts updates to either the schedule or messages parameter or both. Your request must contain at least one of those two keys.
To use this endpoint, you’ll need an API key with the messages.schedule.update permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\ncurl --location --request POST 'https://rest.iad-01.braze.com/messages/schedule/update' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY' \\\n--data-raw '{\n \"schedule_id\": \"schedule_identifier\",\n \"schedule\": {\n \"time\": \"2017-05-24T20:30:36Z\"\n },\n \"messages\": {\n \"apple_push\": {\n \"alert\": \"Updated Message!\",\n \"badge\": 1\n },\n \"android_push\": {\n \"title\": \"Updated title!\",\n \"alert\": \"Updated message!\"\n },\n \"sms\": { \n \"subscription_group_id\": \"subscription_group_identifier\",\n \"message_variation_id\": \"message_variation_identifier\",\n \"body\": \"This is my SMS body.\",\n \"app_id\": \"app_identifier\"\n }\n }\n}'\n\n\nUse 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.
\n
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.
\nAny 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.
To use this endpoint, you’ll need an API key with the campaigns.trigger.schedule.update permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\ncurl --location --request POST 'https://rest.iad-01.braze.com/campaigns/trigger/schedule/update' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY' \\\n--data-raw '{\n \"campaign_id\": \"campaign_identifier\",\n \"schedule_id\": \"schedule_identifier\",\n \"schedule\": {\n \"time\": \"2017-05-24T21:30:00Z\",\n \"in_local_time\": true\n }\n}'\n\n\nUse this endpoint to update scheduled API-triggered Canvases that were created in the dashboard.
\n
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.
\nAny 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.
To use this endpoint, you’ll need an API key with the canvas.trigger.schedule.update permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"canvas_id\": (required, string) see Canvas identifier,\n \"schedule_id\": (required, string) the `schedule_id` to update (obtained from the response to create schedule),\n \"schedule\": {\n // required, see create schedule documentation\n }\n}\n\n\nUse this endpoint to create send IDs that can be used to send messages and track message performance programatically, without campaign creation for each send.
\n
Using the send identifier to track and send messages is useful if you are planning to programmatically generate and send content.
\nTo use this endpoint, you'll need to generate an API key with the sends.id.create permission.
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 for details.
Content-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"message\": \"success\",\n \"send_id\" : (string) the send identifier\n}\n\n\n\nUse this endpoint to send immediate messages to designated users via the Braze API.
\n
Be sure to include Messaging Objects in your body to complete your requests.
\nIf you are targeting a segment, a record of your request will be stored in the Developer Console.
\nTo use this endpoint, you'll need to generate an API key with the messages.send permission.
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.
Braze endpoints support batching API requests. A single request to the messaging endpoints can reach any of the following:
\nUp 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 object
\nMessage sending endpoint responses will include the message’s dispatch_id for reference back to the dispatch of the message. The dispatch_id is the ID of the message dispatch, meaning the unique ID for each “transmission” sent from Braze. For more information, refer to Dispatch ID behavior.
\n\nUse this endpoint to send immediate, one-off transactional messages to a designated user.
\n
This endpoint is used alongside the creation of a Braze Transactional Email campaign and corresponding campaign ID.
\n\n\nImportant: Transactional Email is currently available as part of select Braze packages. Reach out to your Braze customer success manager for more details.
\n
Similar to the Send triggered campaign endpoint, 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.
To use this endpoint, you'll need to generate an API key with the transactional.send permission.
Braze 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.
\nThe send transactional email endpoint will respond with the message’s 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.
{\n \"dispatch_id\": Out-of-the-box generated Unique ID of the instance of this send\n \"status\": Current status of the message\n \"metadata\": Object containing additional information about the send instance\n}\n\nThe 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.
\nMost 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.
\nAll 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.
\nIn 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, 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 > Email Preferences in your Braze dashboard and locate the section Transactional Event Status Postback. Input your desired URL to receive postbacks.
\n\n\nNote: If you are using our older navigation, Email Preferences can be found at Manage Settings > Email Settings.
\n
// Sent Event\n{\n \"dispatch_id\": \"acf471119f7449d579e8089032003ded\",\n \"status\": \"sent\",\n \"metadata\": {\n \"received_at\": \"2020-08-31T18:58:41.000+00:00\",\n \"enqueued_at\": \"2020-08-31T18:58:41.000+00:00\",\n \"executed_at\": \"2020-08-31T18:58:41.000+00:00\",\n \"sent_at\": \"2020-08-31T18:58:42.000+00:00\",\n \"campaign_api_id\": \"417220e4-5a2a-b634-7f7d-9ec891532368\",\n \"external_send_id\" : \"34a2ceb3cf6184132f3d816e9984269a\"\n }\n}\n// Processed Event\n{\n \"dispatch_id\": \"acf471119f7449d579e8089032003ded\",\n \"status\": \"processed\",\n \"metadata\": {\n \"processed_at\": \"2020-08-31T18:58:42.000+00:00\",\n \"campaign_api_id\": \"417220e4-5a2a-b634-7f7d-9ec891532368\",\n \"external_send_id\" : \"34a2ceb3cf6184132f3d816e9984269a\"\n }\n}\n// Aborted\n{\n \"dispatch_id\": \"acf471119f7449d579e8089032003ded\",\n \"status\": \"aborted\",\n \"metadata\": {\n \"reason\": \"User not emailable\",\n \"aborted_at\": \"2020-08-31T19:04:51.000+00:00\",\n \"campaign_api_id\": \"417220e4-5a2a-b634-7f7d-9ec891532368\",\n \"external_send_id\" : \"34a2ceb3cf6184132f3d816e9984269a\"\n }\n}\n// Delivered Event\n{\n \"dispatch_id\": \"acf471119f7449d579e8089032003ded\",\n \"status\": \"delivered\",\n \"metadata\": {\n \"delivered_at\": \"2020-08-31T18:27:32.000+00:00\",\n \"campaign_api_id\": \"417220e4-5a2a-b634-7f7d-9ec891532368\",\n \"external_send_id\" : \"34a2ceb3cf6184132f3d816e9984269a\"\n }\n}\n// Bounced Event\n{\n \"dispatch_id\": \"acf471119f7449d579e8089032003ded\",\n \"status\": \"bounced\",\n \"metadata\": {\n \"bounced_at\": \"2020-08-31T18:58:43.000+00:00\",\n \"reason\": \"550 5.1.1 The email account that you tried to reach does not exist\",\n \"campaign_api_id\": \"417220e4-5a2a-b634-7f7d-9ec891532368\",\n \"external_send_id\" : \"34a2ceb3cf6184132f3d816e9984269a\"\n }\n}\n\n// Sent Event\n{\n \"dispatch_id\": \"acf471119f7449d579e8089032003ded\",\n \"status\": \"sent\",\n \"metadata\": {\n \"received_at\": \"2020-08-31T18:58:41.000+00:00\",\n \"enqueued_at\": \"2020-08-31T18:58:41.000+00:00\",\n \"executed_at\": \"2020-08-31T18:58:41.000+00:00\",\n \"sent_at\": \"2020-08-31T18:58:42.000+00:00\",\n \"campaign_api_id\": \"417220e4-5a2a-b634-7f7d-9ec891532368\",\n \"external_send_id\" : \"34a2ceb3cf6184132f3d816e9984269a\"\n }\n}\n// Processed Event\n{\n \"dispatch_id\": \"acf471119f7449d579e8089032003ded\",\n \"status\": \"processed\",\n \"metadata\": {\n \"processed_at\": \"2020-08-31T18:58:42.000+00:00\",\n \"campaign_api_id\": \"417220e4-5a2a-b634-7f7d-9ec891532368\",\n \"external_send_id\" : \"34a2ceb3cf6184132f3d816e9984269a\"\n }\n}\n// Aborted\n{\n \"dispatch_id\": \"acf471119f7449d579e8089032003ded\",\n \"status\": \"aborted\",\n \"metadata\": {\n \"reason\": \"User not emailable\",\n \"aborted_at\": \"2020-08-31T19:04:51.000+00:00\",\n \"campaign_api_id\": \"417220e4-5a2a-b634-7f7d-9ec891532368\",\n \"external_send_id\" : \"34a2ceb3cf6184132f3d816e9984269a\"\n }\n}\n// Delivered Event\n{\n \"dispatch_id\": \"acf471119f7449d579e8089032003ded\",\n \"status\": \"delivered\",\n \"metadata\": {\n \"delivered_at\": \"2020-08-31T18:27:32.000+00:00\",\n \"campaign_api_id\": \"417220e4-5a2a-b634-7f7d-9ec891532368\",\n \"external_send_id\" : \"34a2ceb3cf6184132f3d816e9984269a\"\n }\n}\n// Bounced Event\n{\n \"dispatch_id\": \"acf471119f7449d579e8089032003ded\",\n \"status\": \"bounced\",\n \"metadata\": {\n \"bounced_at\": \"2020-08-31T18:58:43.000+00:00\",\n \"reason\": \"550 5.1.1 The email account that you tried to reach does not exist\",\n \"campaign_api_id\": \"417220e4-5a2a-b634-7f7d-9ec891532368\",\n \"external_send_id\" : \"34a2ceb3cf6184132f3d816e9984269a\"\n }\n}\n\n\n\nUse this endpoint to send immediate, ad-hoc messages to designated users via API-triggered delivery.
\n
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.
\nIf you are targeting a segment, a record of your request will be stored in the Developer Console. Note that to send messages with this endpoint, you must have a campaign ID created when you build an API-triggered campaign.
\nTo use this endpoint, you'll need to generate an API key with the campaigns.trigger.send permission.
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.
Braze endpoints support batching API requests. A single request to the messaging endpoints can reach any of the following:
\nexternal_ids, each with individual message parameterssegment_idThe 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.
\n\nImportant: A user’s 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 you’re interested in participating in the early access. More details can be found in the User attributes object.
\n
Message sending endpoint responses will include the message’s 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.
Using the attributes object in campaigns
\nBraze 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.
\n\n","urlObject":{"protocol":"https","path":["campaigns","trigger","send"],"host":["{{instance_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"aef185ae-f591-452a-93a9-61d4bc023b05"},{"name":"Send Canvases using API-triggered delivery","id":"c9a8a5fe-a101-4755-99f2-73aa8fc146fe","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","type":"text","value":"Bearer {{api_key}}"}],"body":{"mode":"raw","raw":"{\n \"canvas_id\": \"canvas_identifier\",\n \"canvas_entry_properties\": {\"product_name\" : \"shoes\", \"product_price\" : 79.99},\n \"broadcast\": false,\n \"audience\": {\n \"AND\": [\n {\n \"custom_attribute\": {\n \"custom_attribute_name\": \"eye_color\",\n \"comparison\": \"equals\",\n \"value\": \"blue\"\n }\n },\n {\n \"custom_attribute\": {\n \"custom_attribute_name\": \"favorite_foods\",\n \"comparison\": \"includes_value\",\n \"value\": \"pizza\"\n }\n },\n {\n \"OR\": [\n {\n \"custom_attribute\": {\n \"custom_attribute_name\": \"last_purchase_time\",\n \"comparison\": \"less_than_x_days_ago\",\n \"value\": 2\n }\n },\n {\n \"push_subscription_status\": {\n \"comparison\": \"is\",\n \"value\": \"opted_in\"\n }\n }\n ]\n },\n {\n \"email_subscription_status\": {\n \"comparison\": \"is_not\",\n \"value\": \"subscribed\"\n }\n },\n {\n \"last_used_app\": {\n \"comparison\": \"after\",\n \"value\": \"2019-07-22T13:17:55+0000\"\n }\n }\n ]\n },\n \"recipients\": [\n {\n \"user_alias\": {\n \"alias_name\" : \"example_name\",\n \"alias_label\" : \"example_label\"\n },\n \"external_user_id\": \"user_identifier\",\n \"trigger_properties\": \"\",\n \"canvas_entry_properties\": \"\",\n \"send_to_existing_only\": true,\n \"attributes\": {\n \"first_name\" : \"Alex\"\n }\n }\n ]\n}"},"url":"https://{{instance_url}}/canvas/trigger/send","description":"Important: Looking for the Canvas version of this endpoint? Check out Sending Canvas messages via API-triggered delivery.
\n
\n\nUse this endpoint to send Canvas messages via API-triggered delivery.
\n
To use this endpoint, you’ll 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.
\nNote that to send messages with this endpoint, you must have a Canvas ID created when you build a Canvas.
\nWhen 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.
Braze endpoints support batching API requests. A single request to the messaging endpoints can reach any of the following:
\nexternal_ids, each with individual message parameterssegment_idCustomers using the API for server-to-server calls may need to whitelist the appropriate API URL if they’re behind a firewall.
\n\n\nNote: 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.
\n
Message sending endpoint responses will include the message’s 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 for more information.
Using the Attributes Object in Canvas
\nBraze 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.
\n\n","urlObject":{"protocol":"https","path":["canvas","trigger","send"],"host":["{{instance_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"c9a8a5fe-a101-4755-99f2-73aa8fc146fe"}],"id":"7babde92-7ddb-4053-87a5-ab0f6c264d2c","_postman_id":"7babde92-7ddb-4053-87a5-ab0f6c264d2c","description":""}],"id":"2caba516-ea27-47ed-b8d5-a64b211db7d0","description":"Important: Looking for the camaigns version of this endpoint? Check out Sending campaign messages via API-triggered delivery.
\n
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 campaign in the Braze 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.
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 who haven’t become re-eligible for the campaign regardless of how many API requests are sent.
\nThe Send Message endpoints allow you to send immediate messages to designated users. If you are targeting a segment, a record of your request will be stored in the Message Activity Log. Use the Schedule Message endpoints to send messages at a designated time, and modify or cancel messages that you have already scheduled.
\n","_postman_id":"2caba516-ea27-47ed-b8d5-a64b211db7d0"},{"name":"Preference Center","item":[{"name":"Generate preference center URL","id":"0bc750ff-068e-4391-897e-6eddca2561cd","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/preference_center/v1/{PreferenceCenterExternalID}/url/{UserID}?preference_center_api_id={{preference_center_api_id}}&external_id={{external_id}}","description":"\n\nUse this endpoint to generate a URL for a preference center.
\n
Each preference center URL is unique to each user.
\nTo use this endpoint, you’ll need an API key with the preference_center.user.get permission.
This endpoint has a rate limit of 1,000 requests per minute, per workspace.
\ncurl --location --request GET 'https://rest.iad-01.braze.com/preference_center/v1/$preference_center_external_id/url/$user_external_id' \\\n--header 'Authorization: Bearer YOUR-API-KEY-HERE'\n\n{\n \"preference_center_url\": \"https://www.example.com/preferences\"\n}\n\n(Required) String
\n","type":"text/plain"},"key":"external_id","value":"{{external_id}}"}],"variable":[]}},"response":[],"_postman_id":"0bc750ff-068e-4391-897e-6eddca2561cd"},{"name":"List preference centers","id":"dd8f6667-5eba-4e19-a29e-ba74644c0b8e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/preference_center/v1/list","description":"\n\nUse this endpoint to list your available preference centers.
\n
To use this endpoint, you’ll need an API key with the preference_center.list permission.
This endpoint has a rate limit of 1,000 requests per minute, per workspace.
\nThere are no path or request parameters for this endpoint.
\ncurl --location -g --request GET https://rest.iad-01.braze.com/preference_center/v1/list \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY'\n\n{\n \"preference_centers\": [\n {\n \"name\": \"My Preference Center 1\",\n \"preference_center_api_id\": \"preference_center_api_id\",\n \"created_at\": \"2022-08-17T15:46:10Z\",\n \"updated_at\": \"2022-08-17T15:46:10Z\"\n },\n {\n \"name\": \"My Preference Center 2\",\n \"preference_center_api_id\": \"preference_center_api_id\",\n \"created_at\": \"2022-08-19T11:13:06Z\",\n \"updated_at\": \"2022-08-19T11:13:06Z\"\n },\n {\n \"name\": \"My Preference Center 3\",\n \"preference_center_api_id\": \"preference_center_api_id\",\n \"created_at\": \"2022-08-19T11:30:50Z\",\n \"updated_at\": \"2022-08-19T11:30:50Z\"\n },\n {\n \"name\": \"My Preference Center 4\",\n \"preference_center_api_id\": \"preference_center_api_id\",\n \"created_at\": \"2022-09-13T20:41:34Z\",\n \"updated_at\": \"2022-09-13T20:41:34Z\"\n }\n ]\n}\n\n\n\nUse this endpoint to view the details for your preference centers, including when it was created and updated.
\n
To use this endpoint, you'll need an API key with the preference_center.get permission.
This endpoint has a rate limit of 1,000 requests per minute, per workspace.
\nThere are no request parameters for this endpoint.
\ncurl --location -g --request GET https://rest.iad-01.braze.com/preference_center/v1/preference_center_external_id \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY'\n\n{\n \"name\": \"My Preference Center\",\n \"preference_center_api_id\": \"preference_center_api_id\",\n \"created_at\": \"example_time_created\",\n \"updated_at\": \"example_time_updated\",\n \"preference_center_title\": \"Example preference center title\",\n \"preference_center_page_html\": \"HTML for preference center here\",\n \"confirmation_page_html\": \"HTML for confirmation page here\",\n \"redirect_page_html\": null,\n \"preference_center_options\": {\n \"meta-viewport-content\": \"width=device-width, initial-scale=2\"\n },\n \"state\": \"active\"\n}\n\n\n\nUse this endpoint to create a preference center to allow users to manage their notification preferences for your email campaigns.
\n
Refer to Create a preference center with API for steps on how to build an API-generated preference center.
\nTo use this endpoint, you’ll need an API key with the preference_center.update permission.
This endpoint has a rate limit of 10 requests per minute, per workspace.
\n\n\nNote: The preference center name can't be edited after it's created.
\n
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.
\n{\n \"preference_center_api_id\": \"preference_center_api_id_example\",\n \"liquid_tag\": \"{{preference_center.${MyPreferenceCenter2022-09-22}}}\",\n \"created_at\": \"2022-09-22T18:28:07+00:00\",\n \"message\": \"success\"\n}\n\n%3C!doctype%20html%3E\n<html lang=\"en\">\n <head>\n <meta name=\"robots\" content=\"noindex\" />\n <title>Email Preferences</title>\n <script type=\"text/javascript\">\n%20%20%20%20%20%20window.onload%20%3D%20()%20%3D%3E%20%7B\n%20%20%20%20%20%20%20%20const%20globalUnsubscribed%20%3D%20%26%23x27%3B%7B%7Bsubscribed_state.%24%7Bemail_global%7D%7D%7D%26%23x27%3B%20%3D%3D%20%22unsubscribed%22%3B\n%20%20%20%20%20%20%20%20const%20globalSubscribedValue%20%3D%20%26%23x27%3B%7B%7Bsubscribed_state.%24%7Bemail_global%7D%7D%7D%26%23x27%3B%20%3D%3D%20%22opted_in%22%20%3F%20%22opted_in%22%20%3A%20%22subscribed%22%3B\n%20%20%20%20%20%20%20%20const%20idStates%20%3D%20%5B\n%20%20%20%20%20%20%20%20%20%20%2F%2F%20input%20format%3A%20%5BAPI_ID%2C%20%26%23x27%3B%7B%7Bsubscribed_state.%24%7BAPI_ID%7D%7D%7D%26%23x27%3B%20%3D%3D%20%22subscribed%22%5D%5B%5D\n%20%20%20%20%20%20%20%20%20%20%5B%26%23x27%3B3d2ae07a-f2ff-4318-bdff-e394f2d3a4ec%26%23x27%3B%2C%20%26%23x27%3B%7B%7Bsubscribed_state.%24%7B3d2ae07a-f2ff-4318-bdff-e394f2d3a4ec%7D%7D%7D%26%23x27%3B%20%3D%3D%20%26%23x27%3Bsubscribed%26%23x27%3B%5D%2C%5B%26%23x27%3B7d89bdc3-4aa1-4592-8b8a-4c8b7161c875%26%23x27%3B%2C%20%26%23x27%3B%7B%7Bsubscribed_state.%24%7B7d89bdc3-4aa1-4592-8b8a-4c8b7161c875%7D%7D%7D%26%23x27%3B%20%3D%3D%20%26%23x27%3Bsubscribed%26%23x27%3B%5D%2C%5B%26%23x27%3B5444d32e-2815-4258-964c-b9690d4ccb94%26%23x27%3B%2C%20%26%23x27%3B%7B%7Bsubscribed_state.%24%7B5444d32e-2815-4258-964c-b9690d4ccb94%7D%7D%7D%26%23x27%3B%20%3D%3D%20%26%23x27%3Bsubscribed%26%23x27%3B%5D\n%20%20%20%20%20%20%20%20%5D%3B\n%20%20%20%20%20%20%20%20const%20setState%20%3D%20(id%2C%20subscribed)%20%3D%3E%20%7B\n%20%20%20%20%20%20%20%20%20%20document.querySelector(%60%23checkbox-%24%7Bid%7D%60).checked%20%3D%20subscribed%3B\n%20%20%20%20%20%20%20%20%20%20document.querySelector(%60%23value-%24%7Bid%7D%60).value%20%3D%20subscribed%20%3F%20%22subscribed%22%20%3A%20%22unsubscribed%22%3B\n%20%20%20%20%20%20%20%20%7D%3B\n%20%20%20%20%20%20%20%20const%20setGlobal%20%3D%20(unsubscribed)%20%3D%3E%20%7B\n%20%20%20%20%20%20%20%20%20%20document.querySelector(%60%23checkbox-global%60).checked%20%3D%20unsubscribed%3B\n%20%20%20%20%20%20%20%20%20%20document.querySelector(%60%23value-global%60).value%20%3D%20unsubscribed%20%3F%20%22unsubscribed%22%20%3A%20globalSubscribedValue%3B\n%20%20%20%20%20%20%20%20%20%20idStates.forEach((%5Bid%5D)%20%3D%3E%20%7B\n%20%20%20%20%20%20%20%20%20%20%20%20document.querySelector(%60%23checkbox-%24%7Bid%7D%60).disabled%20%3D%20unsubscribed%3B\n%20%20%20%20%20%20%20%20%20%20%7D)%3B\n%20%20%20%20%20%20%20%20%7D%3B\n%20%20%20%20%20%20%20%20idStates.forEach((%5Bid%2C%20state%5D)%20%3D%3E%20%7B\n%20%20%20%20%20%20%20%20%20%20setState(id%2C%20state)%3B\n%20%20%20%20%20%20%20%20%20%20document.querySelector(%60%23checkbox-%24%7Bid%7D%60).onchange%20%3D%20((e)%20%3D%3E%20%7B\n%20%20%20%20%20%20%20%20%20%20%20%20setState(id%2C%20e.target.checked)%3B\n%20%20%20%20%20%20%20%20%20%20%7D)%3B\n%20%20%20%20%20%20%20%20%7D)%3B\n%20%20%20%20%20%20%20%20setGlobal(globalUnsubscribed)%3B\n%20%20%20%20%20%20%20%20document.querySelector(%60%23checkbox-global%60).onchange%20%3D%20((e)%20%3D%3E%20%7B\n%20%20%20%20%20%20%20%20%20%20setGlobal(e.target.checked)%3B\n%20%20%20%20%20%20%20%20%7D)%3B\n%20%20%20%20%20%20%7D%3B\n </script>\n <style>\n%20%20%20%20%20%20body%20%7B\n%20%20%20%20%20%20%20%20background%3A%20%23fff%3B\n%20%20%20%20%20%20%20%20margin%3A%200%3B\n%20%20%20%20%20%20%7D\n%20%20%20%20%20%20%40media%20(max-width%3A%20600px)%20%7B\n%20%20%20%20%20%20%20%20.main-container%20%7B\n%20%20%20%20%20%20%20%20%20%20margin-top%3A%200%3B\n%20%20%20%20%20%20%20%20%20%20width%3A%20100%25%3B\n%20%20%20%20%20%20%20%20%7D\n%20%20%20%20%20%20%20%20.main-container%20.content%20.email-input%20%7B\n%20%20%20%20%20%20%20%20%20%20width%3A%20100%25%3B\n%20%20%20%20%20%20%20%20%7D\n%20%20%20%20%20%20%7D\n </style>\n </head>\n <body class=\"vsc-initialized\" style=\"margin: 0\" bgcolor=\"#fff\">\n%20%20%20%20%3Cdiv\n%20%20%20%20%20%20class%3D%22main-container%22\n%20%20%20%20%20%20style%3D%22\n%20%20%20%20%20%20%20%20background-color%3A%20%23fff%3B\n%20%20%20%20%20%20%20%20color%3A%20%23333335%3B\n%20%20%20%20%20%20%20%20font-family%3A\n%20%20%20%20%20%20%20%20%20%20Sailec%20W00%20Medium%2C\n%20%20%20%20%20%20%20%20%20%20helvetica%2C\n%20%20%20%20%20%20%20%20%20%20arial%2C\n%20%20%20%20%20%20%20%20%20%20sans-serif%3B\n%20%20%20%20%20%20%20%20margin-left%3A%20auto%3B\n%20%20%20%20%20%20%20%20margin-right%3A%20auto%3B\n%20%20%20%20%20%20%20%20margin-top%3A%2030px%3B\n%20%20%20%20%20%20%20%20width%3A%20600px%3B\n%20%20%20%20%20%20%20%20padding%3A%2015px%200%205px%3B\n%20%20%20%20%20%20%22\n%20%20%20%20%3E\n <div class='preserveHtml' class='preserveHtml' class=\"content\" style=\"margin-left: 20px; margin-right: 20px\">\n <div class='preserveHtml' class='preserveHtml' class='preserveHtml'>\n%20%20%20%20%20%20%20%20%20%20%3Ch1\n%20%20%20%20%20%20%20%20%20%20%20%20style%3D%22color%3A%20%233accdd%3B%20font-size%3A%2027px%3B%20font-weight%3A%20400%3B%20margin-bottom%3A%2040px%3B%20margin-top%3A%200%22\n%20%20%20%20%20%20%20%20%20%20%20%20align%3D%22center%22\n%20%20%20%20%20%20%20%20%20%20%3E\n%20%20%20%20%20%20%20%20%20%20%20%20Manage%20Email%20Preferences\n </h1>\n <p class='preserveHtml' class='preserveHtml' class=\"intro-text\" style=\"font-size: 14px; margin-bottom: 20px\" align=\"center\">\n%20%20%20%20%20%20%20%20%20%20%20%20Select%20the%20emails%20that%20you%20want%20to%20receive.\n </p>\n </div>\n <form action=\"{{ preference_center_submit_url }}\" method=\"post\" accept-charset=\"UTF-8\">\n <div class='preserveHtml' class='preserveHtml' class='preserveHtml'>\n <h3 class='preserveHtml' class='preserveHtml' style=\"font-size: 15px; margin-bottom: 15px; margin-left: 5px; margin-top: 40px\">\n Email Address: <span class=\"displayed-email\" style=\"font-weight: 400\">{{${email_address}}}</span>\n </h3>\n </div>\n <div class='preserveHtml' class='preserveHtml' class=\"subscription-groups-holder\" style=\"margin-bottom: 20px\"><div class='preserveHtml' class='preserveHtml' class=\"row\" style=\"border-top-width: 1px; border-top-color: #dddde2; border-top-style: solid; background-color: #fff; padding: 15px 10px 14px;border-bottom: 1px solid rgb(221, 221, 226);\">\n <label style=\"color: #27368f; cursor: pointer; font-size: 15px; font-weight: 700;\">\n <input type=\"checkbox\" id=\"checkbox-3d2ae07a-f2ff-4318-bdff-e394f2d3a4ec\" class=\"sub_group\" style=\"margin-right: 4px;\">\n <input type=\"hidden\" name=\"{% form_field_name :subscription_group 3d2ae07a-f2ff-4318-bdff-e394f2d3a4ec %}\" id=\"value-3d2ae07a-f2ff-4318-bdff-e394f2d3a4ec\" />\n%20%20%20%20Sub%20Group%201\n </label>\n <p class='preserveHtml' class='preserveHtml' class=\"subscription-group\" style=\"font-size: 13px; line-height: 1.4em; min-height: 20px; padding-right: 20px; margin: 0 0 3px 23px;\">\n </p>\n</div>\n<div class='preserveHtml' class='preserveHtml' class=\"row\" style=\"border-top-width: 1px; border-top-color: #dddde2; border-top-style: solid; background-color: #fff; padding: 15px 10px 14px;border-bottom: 1px solid rgb(221, 221, 226);\">\n <label style=\"color: #27368f; cursor: pointer; font-size: 15px; font-weight: 700;\">\n <input type=\"checkbox\" id=\"checkbox-7d89bdc3-4aa1-4592-8b8a-4c8b7161c875\" class=\"sub_group\" style=\"margin-right: 4px;\">\n <input type=\"hidden\" name=\"{% form_field_name :subscription_group 7d89bdc3-4aa1-4592-8b8a-4c8b7161c875 %}\" id=\"value-7d89bdc3-4aa1-4592-8b8a-4c8b7161c875\" />\n%20%20%20%20Sub%20Group%202\n </label>\n <p class='preserveHtml' class='preserveHtml' class=\"subscription-group\" style=\"font-size: 13px; line-height: 1.4em; min-height: 20px; padding-right: 20px; margin: 0 0 3px 23px;\">\n </p>\n</div>\n<div class='preserveHtml' class='preserveHtml' class=\"row\" style=\"border-top-width: 1px; border-top-color: #dddde2; border-top-style: solid; background-color: #fff; padding: 15px 10px 14px;border-bottom: 1px solid rgb(221, 221, 226);\">\n <label style=\"color: #27368f; cursor: pointer; font-size: 15px; font-weight: 700;\">\n <input type=\"checkbox\" id=\"checkbox-5444d32e-2815-4258-964c-b9690d4ccb94\" class=\"sub_group\" style=\"margin-right: 4px;\">\n <input type=\"hidden\" name=\"{% form_field_name :subscription_group 5444d32e-2815-4258-964c-b9690d4ccb94 %}\" id=\"value-5444d32e-2815-4258-964c-b9690d4ccb94\" />\n%20%20%20%20Sub%20Group%203\n </label>\n <p class='preserveHtml' class='preserveHtml' class=\"subscription-group\" style=\"font-size: 13px; line-height: 1.4em; min-height: 20px; padding-right: 20px; margin: 0 0 3px 23px;\">\n </p>\n</div>\n</div>\n <div class='preserveHtml' class='preserveHtml' class=\"unsub-all\" style=\"cursor: pointer; font-size: 13px; margin-bottom: 20px\" align=\"center\">\n <label>\n <input type=\"checkbox\" id=\"checkbox-global\" />\n%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3Cinput\n%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20type%3D%22hidden%22\n%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20id%3D%22value-global%22\n%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20name%3D%22%7B%25%20form_field_name%20%3Aemail_global_state%20%25%7D%22\n%20%20%20%20%20%20%20%20%20%20%20%20%20%20%2F%3E\n <i class='preserveHtml' class='preserveHtml' class='preserveHtml'> Unsubscribe from all of the above types of emails </i>\n </label>\n </div>\n <div class='preserveHtml' class='preserveHtml' class='preserveHtml'>\n%20%20%20%20%20%20%20%20%20%20%20%20%3Cinput\n%20%20%20%20%20%20%20%20%20%20%20%20%20%20class%3D%22save%22\n%20%20%20%20%20%20%20%20%20%20%20%20%20%20type%3D%22submit%22\n%20%20%20%20%20%20%20%20%20%20%20%20%20%20value%3D%22Save%22\n%20%20%20%20%20%20%20%20%20%20%20%20%20%20style%3D%22\n%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20background-color%3A%20rgb(71%2C%20204%2C%20163)%3B\n%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20color%3A%20%23fff%3B\n%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20cursor%3A%20pointer%3B\n%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20display%3A%20block%3B\n%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20font-size%3A%2016px%3B\n%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20text-align%3A%20center%3B\n%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20text-decoration%3A%20none%3B\n%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20width%3A%20200px%3B\n%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20margin%3A%200%20auto%2020px%3B\n%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20padding%3A%2012px%3B\n%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20border-style%3A%20none%3B\n%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22\n%20%20%20%20%20%20%20%20%20%20%20%20%2F%3E\n </div>\n </form>\n </div>\n </div>\n </body>\n</html>\n\n\n\nUse this endpoint to update a preference center.
\n
To use this endpoint, you’ll need an API key with the preference_center.update permission.
This endpoint has a rate limit of 10 requests per minute, per workspace.
\ncurl --location --request POST 'https://rest.iad-01.braze.com/preference_center/v1/{preferenceCenterExternalId}' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-API-KEY-HERE' \\\n--data-raw '{\n \"name\": \"Example\",\n \"preference_center_title\": \"Example Preference Center Title\",\n \"preference_center_page_html\": \"HTML for preference center here\",\n \"confirmation_page_html\": \"HTML here with a message to users here\",\n \"state\": \"active\"\n}\n'\n\n{\n \"preference_center_api_id\": \"8efc52aa-935e-42b7-bd6b-98f43bb9b0f1\",\n \"created_at\": \"2022-09-22T18:28:07Z\",\n \"updated_at\": \"2022-09-22T18:32:07Z\",\n \"message\": \"success\"\n}\n\nUse the endpoints in this section to build a preference center, which is a Braze-hosted website that can display your user’s subscription state and subscription group statuses. Using HTML and CSS, your developer team can build your preference center so that the styling of the page matches your brand guidelines.
\nCheck out Preference center overview for more details on how to create and customize your preference center.
\n","_postman_id":"6d20ac1a-6788-4a60-afb9-0264ec928879"},{"name":"SCIM","item":[{"name":"Remove dashboard user account","id":"9c7c71ea-afd6-414a-99d1-4eb1fe274f16","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"X-Request-Origin","value":"YOUR-REQUEST-ORIGIN-HERE","type":"text"},{"key":"Authorization","value":"Bearer YOUR-SCIM-TOKEN-HERE","type":"text"}],"url":"https://{{instance_url}}/scim/v2/Users/{id}","description":"\n\nUse this endpoint to permanently delete an existing dashboard user by specifying the resource
\nidreturned by the SCIM <code>POST</code> method.
This is similar to deleting a user in the Manage Users section of the Braze dashboard.
\nTo use this endpoint, you'll need a SCIM token. For more information, refer to Automated user provisioning.
\nThis 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.
There is no request body for this endpoint.
\ncurl --location --request DELETE 'https://rest.iad-01.braze.com/scim/v2/Users/dfa245b7-24195aec-887bb3ad-602b3340' \\\n--header 'Content-Type: application/json' \\\n--header 'X-Request-Origin: YOUR-REQUEST-ORIGIN-HERE' \\\n--header 'Authorization: Bearer YOUR-SCIM-TOKEN-HERE' \\\n\nHTTP/1.1 204 Not Found\nContent-Type: text/html; charset=UTF-8\n\nIf a developer with this ID doesn’t exist in Braze, the endpoint will respond with:
\nHTTP/1.1 404 Not Found Content-Type: text/html; charset=UTF-8\n{ \"schemas\": [\"urn:ietf:params:scim:api:messages:2.0:Error\"], \"detail\": \"User not found\", \"status\": 404 }\n\n\n\nUse this endpoint to look up an existing dashboard user account by specifying their email in the filter query parameter.
\n
Note that when the query parameter is URL encoded it will read like this: /scim/v2/Users?filter=userName eq \"user@test.com\"
To use this endpoint, you'll need a SCIM token. For more information, refer to Automated user provisioning.
\nThis 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.
There is no request body for this endpoint.
\nContent-Type: application/json\nX-Request-Origin: YOUR-REQUEST-ORIGIN-HERE\nAuthorization: Bearer YOUR-SCIM-TOKEN-HERE\n{\n \"schemas\": [\"urn:ietf:params:scim:api:messages:2.0:ListResponse\"],\n \"totalResults\": 1,\n \"Resources\": [\n {\n \"userName\": \"user@test.com\",\n \"id\": \"dfa245b7-24195aec-887bb3ad-602b3340\",\n \"name\": {\n \"givenName\": \"Test\",\n \"familyName\": \"User\"\n },\n \"department\": \"finance\",\n \"lastSignInAt\": \"Thursday, January 1, 1970 12:00:00 AM\",\n \"permissions\": {\n \"companyPermissions\": [\"manage_company_settings\"],\n \"appGroup\": [\n {\n \"appGroupId\": \"241adcd25789fabcded\",\n \"appGroupName\": \"Test Workspace\",\n \"appGroupPermissions\": [\"basic_access\",\"send_campaigns_canvases\"],\n \"team\": [\n {\n \"teamId\": \"241adcd25789fabcded\",\n \"teamName\": \"Test Team\", \n \"teamPermissions\": [\"admin\"]\n }\n ]\n } \n ]\n }\n }\n ]\n}\n\n\n\nUse this endpoint to look up an existing dashboard user account by specifying the resource
\nidreturned by the SCIM <code>POST</code> method.
To use this endpoint, you'll need a SCIM token. For more information, refer to Automated user provisioning.
\nThis 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.
There is no request body for this endpoint.
\ncurl --location --request GET 'https://rest.iad-01.braze.com/scim/v2/Users/dfa245b7-24195aec-887bb3ad-602b3340' \\\n--header 'Content-Type: application/json' \\\n--header 'X-Request-Origin: YOUR-REQUEST-ORIGIN-HERE' \\\n--header 'Authorization: Bearer YOUR-API-KEY-HERE' \\\n\n{\n \"schemas\": [\"urn:ietf:params:scim:schemas:core:2.0:User\"],\n \"id\": \"dfa245b7-24195aec-887bb3ad-602b3340\",\n \"userName\": \"user@test.com\",\n \"name\": {\n \"givenName\": \"Test\",\n \"familyName\": \"User\"\n },\n \"department\": \"finance\",\n \"lastSignInAt\": \"Thursday, January 1, 1970 12:00:00 AM\",\n \"createdAt\": \"Thursday, January 1, 1970 12:00:00 AM\",\n \"permissions\": {\n \"companyPermissions\": [\"manage_company_settings\"],\n \"roles\": [\n {\n \"roleName\": \"Another Test Role\",\n \"roleId\": \"23125dad23dfaae7,\n \"appGroup\": [\n {\n \"appGroupId\": \"241adcd25adfabcded\",\n \"appGroupName\": \"Production Workspace\",\n \"appGroupPermissionSets\": [\n {\n \"appGroupPermissionSetName\": \"A Permission Set\",\n \"appGroupPermissionSetId\": \"dfa385109bc38\",\n \"permissions\": [\"basic_access\",\"publish_cards\"]\n }\n ]\n } \n ]\n }\n ],\n \"appGroup\": [\n {\n \"appGroupId\": \"241adcd25789fabcded\",\n \"appGroupName\": \"Test Workspace\",\n \"appGroupPermissions\": [\"basic_access\",\"send_campaigns_canvases\"],\n \"team\": [\n {\n \"teamId\": \"241adcd25789fabcded\",\n \"teamName\": \"Test Team\", \n \"teamPermissions\": [\"admin\"]\n }\n ]\n } \n ]\n }\n}\n\n\n\nUse this endpoint 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).
\n
To use this endpoint, you'll need a SCIM token. For more information, refer to Automated user provisioning.
\nThis 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.
{\n \"schemas\": [\"urn:ietf:params:scim:schemas:core:2.0:User\"],\n \"id\": \"dfa245b7-24195aec-887bb3ad-602b3340\",\n \"userName\": \"user@test.com\",\n \"name\": {\n \"givenName\": \"Test\",\n \"familyName\": \"User\"\n },\n \"department\": \"finance\",\n \"lastSignInAt\": \"Thursday, January 1, 1970 12:00:00 AM\",\n \"permissions\": {\n \"companyPermissions\": [\"manage_company_settings\"],\n \"appGroup\": [\n {\n \"appGroupId\": \"241adcd25789fabcded\",\n \"appGroupName\": \"Test App Group\",\n \"appGroupPermissions\": [\"basic_access\",\"send_campaigns_canvases\"],\n \"team\": [\n {\n \"teamId\": \"2519dafcdba238ae7\",\n \"teamName\": \"Test Team\", \n \"teamPermissions\": [\"basic_access\",\"export_user_data\"]\n }\n ]\n } \n ]\n }\n}\n\nIf a user with this email address already exists in Braze, the endpoint will respond with:
\nHTTP/1.1 409 Conflict\nDate: Tue, 10 Sep 2019 02:22:30 GMT\nContent-Type: text/json;charset=UTF-8\n{\n \"schemas\": [\"urn:ietf:params:scim:api:messages:2.0:Error\"],\n \"detail\": \"User already exists in the database.\",\n \"status\": 409\n}\n\n\n\nUse this endpoint to update an existing dashboard user account by specifying the resource
\nidreturned by the SCIM <code>POST</code> 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.
\nFor 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.
To use this endpoint, you'll need a SCIM token. For more information, refer to Automated user provisioning.
\nThis 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.
{\n \"schemas\": [\"urn:ietf:params:scim:schemas:core:2.0:User\"],\n \"id\": \"dfa245b7-24195aec-887bb3ad-602b3340\",\n \"userName\": \"user@test.com\",\n \"name\": {\n \"givenName\": \"Test\",\n \"familyName\": \"User\"\n },\n \"department\": \"finance\",\n \"lastSignInAt\": \"Thursday, January 1, 1970 12:00:00 AM\",\n \"permissions\": {\n \"companyPermissions\": [\"manage_company_settings\"],\n \"appGroup\": [\n {\n \"appGroupId\": \"241adcd25789fabcded\",\n \"appGroupName\": \"Test App Group\",\n \"appGroupPermissions\": [\"basic_access\",\"send_campaigns_canvases\"],\n \"team\": [\n {\n \"teamId\": \"2519dafcdba238ae7\",\n \"teamName\": \"Test Team\", \n \"teamPermissions\": [\"admin\"]\n }\n ]\n } \n ]\n }\n}\n\nIf a user with this ID doesn’t exist in Braze, the endpoint will respond with:
\nHTTP/1.1 404 Not Found\nContent-Type: text/html; charset=UTF-8\n{\n \"schemas\": [\"urn:ietf:params:scim:api:messages:2.0:Error\"],\n \"detail\": \"User not found\",\n \"status\": 404\n}\n\nThe System for Cross-domain Identity Management (SCIM) specification is designed to make managing user identities in cloud-based applications and services easier by providing a defined schema for representing users and groups. Use the Braze SCIM endpoints to manage automated user provisioning.
\n","_postman_id":"d66cf93b-b3ac-473b-b878-cc1ab9c4956a"},{"name":"SMS","item":[{"name":"Query invalid phone numbers","id":"81ceae19-15d1-4ac1-ad22-a6b86a92456d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/sms/invalid_phone_numbers?start_date=2018-09-01&end_date=2018-09-01&limit=100&offset=1&phone_numbers=12345678901&reason=provider_error","description":"\n\nUse this endpoint to pull a list of phone numbers that have been deemed “invalid” within a certain time frame.
\n
To use this endpoint, you’ll need an API key with the sms.invalid_phone_numbers permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nYou must provide either a start_date and an end_date OR phone_numbers. If you provide all three, start_date, 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.
curl --location --request GET 'https://rest.iad-01.braze.com/sms/invalid_phone_numbers?start_date=2019-01-01&end_date=2019-02-01&limit=100&offset=1&phone_numbers[]=12345678901' \\\n--header 'Authorization: Bearer YOUR-API-KEY-HERE'\n\nEntries are listed in descending order.
\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"sms\": [\n {\n \"phone\": (string) phone number in e.164 format,\n \"invalid_detected_at\": (string) the time the invalid number was detected in ISO 8601\n \"reason\" : \"provider_error\"\n },\n {\n \"phone\": (string) phone number in e.164 format,\n \"invalid_detected_at\": (string) the time the invalid number was detected in ISO 8601\n \"reason\" : \"deactivated\"\n },\n {\n \"phone\": (string) phone number in e.164 format,\n \"invalid_detected_at\": (string) the time the invalid number was detected in ISO 8601\n \"reason\" : \"provider_error\"\n }\n ],\n \"message\": \"success\"\n}\n\n(Optional*) String in YYYY-MM-DD format
\nStart 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.
(Optional*) String in YYYY-MM-DD format
\nEnd date of the range to retrieve invalid phone numbers. This is treated as midnight in UTC time by the API.
\n","type":"text/plain"},"key":"end_date","value":"2018-09-01"},{"description":{"content":"(Optional) Integer
\nOptional field to limit the number of results returned. Defaults to 100, maximum is 500.
\n","type":"text/plain"},"key":"limit","value":"100"},{"description":{"content":"(Optional) Integer
\nOptional beginning point in the list to retrieve from.
\n","type":"text/plain"},"key":"offset","value":"1"},{"description":{"content":"(Optional*) Array of Strings in e.164 format
\nIf provided, we will return the phone number if it has been found to be invalid.
\n","type":"text/plain"},"key":"phone_numbers","value":"12345678901"},{"description":{"content":"(Optional) String
\nAvailable values are “provider_error” (provider error indicates phone cannot receive SMS) or “deactivated” (phone number has been deactivated). If omitted, all reasons are returned.
\n","type":"text/plain"},"key":"reason","value":"provider_error"}],"variable":[]}},"response":[],"_postman_id":"81ceae19-15d1-4ac1-ad22-a6b86a92456d"},{"name":"Remove invalid phone numbers","id":"76495aac-8c2d-4e1a-8cac-12e3856ab1d3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"phone_numbers\": (required, array of string in e.164 format)\n}"},"url":"https://{{instance_url}}/sms/invalid_phone_numbers/remove","description":"\n\nUse this endpoint to remove “invalid” phone numbers from Braze’s invalid list.
\n
This can be used to re-validate phone numbers after they have been marked as invalid.
\nTo use this endpoint, you’ll need an API key with the sms.invalid_phone_numbers.remove permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\ncurl --location --request POST 'https://rest.iad-01.braze.com/sms/invalid_phone_numbers/remove' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY' \\\n--data-raw '{\n \"phone_numbers\" : [\"12183095514\",\"14255551212\"]\n}'\n\nUse the Braze SMS Endpoints to manage your users’ phone numbers in your subscription groups.
\n","_postman_id":"61a7002c-d047-4913-ac81-9217d8843fd8"},{"name":"Subscription Groups","item":[{"name":"Email","item":[{"name":"List user's subscription group status","id":"488c8923-fa44-4124-9245-036d13c615f2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/subscription/status/get?subscription_group_id={{subscription_group_id}}&external_id={{external_identifier}}&email=example@braze.com","description":"\n\nUse this endpoint to get the subscription state of a user in a subscription group.
\n
To use this endpoint, you’ll 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.
\nTo use this endpoint, you’ll need an API key with the subscription.status.get permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nOne of external_id or email or phone is required for each user.
external_id or email is required. When both are submitted, only the external_id is used for the query and the email address is applied to that user.1\nhttps://rest.iad-03.braze.com/subscription/status/get?subscription_group_id={{subscription_group_id}}&external_id[]=1&external_id[]=2\n\ncurl --location -g --request GET 'https://rest.iad-01.braze.com/subscription/status/get?subscription_group_id={{subscription_group_id}}&email=example@braze.com' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY'\n\nAll successful responses will return Subscribed, Unsubscribed, or Unknown depending on status and user history with the subscription group.
Content-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n \"status\": {\n \"1\": \"Unsubscribed\",\n \"2\": \"Subscribed\"\n },\n \"message\": \"success\"\n}\n\n(Required) String
\nThe id of your subscription group.
(Required*) String
\nThe external_id of the user (must include at least one and at most 50 external_ids).
When both an external_id and email/phone are submitted, only the external_id(s) provided will be applied to the result query.
(Required* ) String
\nThe email address of the user. It can be passed as an array of strings with a maximum of 50.
\nSubmitting both an email address and phone number (with no external_id) will result in an error.
\n\nUse this endpoint to list and get the subscription groups of a certain user.
\n
To use this endpoint, you’ll need an API key with the subscription.groups.get permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nhttps://rest.iad-03.braze.com/subscription/user/status?external_id[]=1&external_id[]=2
curl --location -g --request GET 'https://rest.iad-01.braze.com/subscription/user/status?external_id={{external_id}}&email=example@braze.com&limit=100&offset=0' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY'\n\n(Required) String
\nThe external_id of the user. Must include at least one and at most 50 external_ids.
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).
(Required) String
\nThe email address of the user, can be passed as an array of strings. Must include at least one email address (with a maximum of 50).
\n","type":"text/plain"},"key":"email","value":"example@braze.com"},{"description":{"content":"(Optional) Integer
\nThe limit on the maximum number of results returned. Default (and maximum) limit is 100.
\n","type":"text/plain"},"key":"limit","value":"100"},{"description":{"content":"(Optional) Integer
\nNumber of templates to skip before returning the rest of the templates that fit the search criteria.
\n","type":"text/plain"},"key":"offset","value":"0"}],"variable":[]}},"response":[],"_postman_id":"d1c3b617-22f1-47bf-9ee8-499526824470"},{"name":"Update user's subscription group status (V2)","id":"b1b9a0e0-6329-4df2-a465-53347f410662","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"\"subscription_groups\":[\n {\n \"subscription_group_id\": (required, string),\n \"subscription_state\": (required, string)\n \"external_ids\": (required*, array of strings),\n \"emails\": (required*, array of strings),\n \"phones\": (required*, array of strings in E.164 format),\n }\n ]","options":{"raw":{"language":"json"}}},"url":"https://{{instance_url}} /v2/subscription/status/set","description":"\n\nUse this endpoint to batch update the subscription state of up to 50 users on the Braze dashboard.
\n
You can access a subscription group’s subscription_group_id by navigating to the Subscriptions Group page.
To use this endpoint, you’ll need an API key with the subscription.status.get permission.
This endpoint has 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.
Note that you cannot include both emails and phones parameters. Also, emails, phones, and external_ids can all be sent individually.
\n\nWhen creating new users via the <code>/users/track</code> 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.
\n
The following example uses external_id to make one API call for email and SMS.
curl --location --request POST 'https://rest.iad-01.braze.com/v2/subscription/status/set' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY' \\\n--data-raw '{\n \"subscription_groups\":[\n {\n \"subscription_group_id\":\"subscription_group_identifier\",\n \"subscription_state\":\"subscribed\",\n \"external_ids\":[\"example-user\",\"example1@email.com\"]\n },\n {\n \"subscription_group_id\":\"subscription_group_identifier\",\n \"subscription_state\":\"subscribed\",\n \"external_ids\":[\"example-user\",\"example1@email.com\"]\n }\n ]\n}\n\ncurl --location --request POST 'https://rest.iad-01.braze.com/v2/subscription/status/set' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY' \\\n--data-raw '{\n \"subscription_groups\":[\n {\n \"subscription_group_id\":\"subscription_group_identifier\",\n \"subscription_state\":\"subscribed\",\n \"emails\":[\"example1@email.com\",\"example2@email.com\"]\n }\n ]\n}\n'\n\ncurl --location --request POST 'https://rest.iad-01.braze.com/v2/subscription/status/set' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY' \\\n--data-raw '{\n \"subscription_groups\":[\n {\n \"subscription_group_id\":\"subscription_group_identifier\",\n \"subscription_state\":\"subscribed\",\n \"phones\":[\"+12223334444\",\"+15556667777\"]\n }\n ]\n}\n'\n\n\n\nUse this endpoint to batch update the subscription state of up to 50 users on the Braze dashboard.
\n
You can access a subscription group’s subscription_group_id by navigating to the Subscription Group page.
To use this endpoint, you’ll need an API key with the subscription.status.set permission.
This endpoint has 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.
This property should not be used for updating a user’s profile information. Use the /users/track property instead.
\n\n\nWhen creating new users via the /users/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.
\n
curl --location --request POST 'https://rest.iad-01.braze.com/subscription/status/set' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY' \\\n--data-raw '{\n \"subscription_group_id\": \"subscription_group_identifier\",\n \"subscription_state\": \"unsubscribed\",\n \"external_id\": \"external_identifier\",\n \"email\": [\"example1@email.com\", \"example2@email.com\"]\n}\n'\n\nThe status code 201 could return the following response body.
{\n \"message\": \"success\"\n}\n\n\n\n","urlObject":{"protocol":"https","path":["subscription","status","set"],"host":["{{instance_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"8895e87e-6324-47a3-a833-adf29a258bb9"}],"id":"729cb3ab-ef56-4bf4-a455-5b52d8a7703b","_postman_id":"729cb3ab-ef56-4bf4-a455-5b52d8a7703b","description":""},{"name":"SMS and WhatsApp","item":[{"name":"List user's subscription group status","id":"4b8515b8-067f-41fd-b213-8bb2d18b1557","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/subscription/status/get?subscription_group_id={{subscription_group_id}}&external_id={{external_identifier}}&phone=+11112223333","description":"The endpoint only accepts the
\nphonevalue, 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.\"}
\n\nUse this endpoint to get the subscription state of a user in a subscription group.
\n
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.
\nTo use this endpoint, you’ll need an API key with the subscription.status.get permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nOne of external_id or email or phone is required for each user.
external_id or phone is required. When both are submitted, only the external_id is used for querying and the phone number is applied to that user.1\nhttps://rest.iad-03.braze.com/subscription/status/get?subscription_group_id={{subscription_group_id}}&external_id[]=1&external_id[]=2\n\ncurl --location -g --request GET 'https://rest.iad-01.braze.com/subscription/status/get?subscription_group_id={{subscription_group_id}}&phone=+11112223333' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY'\n\n(Required) String
\nThe id of your subscription group.
(Required*) String
\nThe external_id of the user (must include at least one and at most 50 external_ids).
When both an external_id and email/phone are submitted, only the external_id(s) provided will be applied to the result query.
(Required*) String in E.164 format
\nThe phone number of the user. If email is not included, you must include at least one phone number (with a maximum of 50).
\nSubmitting both an email address and phone number (with no external_id) will result in an error.
\n\nUse this endpoint to list and get the subscription groups of a certain user.
\n
To use this endpoint, you’ll need an API key with the subscription.groups.get permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\n\n\nIf there are multiple users (multiple
\nexternal_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).
https://rest.iad-03.braze.com/subscription/user/status?external_id[]=1&external_id[]=2
curl --location -g --request GET 'https://rest.iad-01.braze.com/subscription/user/status?external_id={{external_id}}&limit=100&offset=1&phone=+11112223333' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY'\n\n(Required*) String
\nThe external_id of the user (must include at least one and at most 50 external_ids).
\n","type":"text/plain"},"key":"external_id","value":"{{external_id}}"},{"description":{"content":"(Optional) Integer
\nThe limit on the maximum number of results returned. Default (and maximum) limit is 100.
\n","type":"text/plain"},"key":"limit","value":"100"},{"description":{"content":"(Optional) Integer
\nNumber of templates to skip before returning the rest of the templates that fit the search criteria.
\n","type":"text/plain"},"key":"offset","value":"1"},{"description":{"content":"(Required*) String in E.164 format
\nThe phone number of the user. Must include at least one phone number (with a maximum of 50).
\n","type":"text/plain"},"key":"phone","value":"+11112223333"}],"variable":[]}},"response":[],"_postman_id":"54bd7ca8-60d9-4654-aff5-406479f3c666"},{"name":"Update user's subscription group status (V2)","id":"81a5fe65-588b-4b61-82d8-5ce68b681409","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"\"subscription_groups\":[\n {\n \"subscription_group_id\": (required, string),\n \"subscription_state\": (required, string)\n \"external_ids\": (required*, array of strings),\n \"emails\": (required*, array of strings),\n \"phones\": (required*, array of strings in E.164 format),\n }\n ]"},"url":"https://{{instance_url}}/v2/subscription/status/set","description":"\n\nUse this endpoint to batch update the subscription state of up to 50 users on the Braze dashboard.
\n
To use this endpoint, you’ll need to generate an API key with the subscription.status.set permission.
You can access a subscription group’s subscription_group_id by navigating to the Subscriptions Group page.
This endpoint has 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.
curl --location --request POST 'https://rest.iad-01.braze.com/subscription/status/set' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY' \\\n--data-raw '{\n \"subscription_groups\": [\n {\n \"subscription_group_id\": \"504e09e6-ffa4-4b31-96c3-c05d50d903cf\",\n \"subscription_state\": \"unsubscribed\",\n \"external_ids\": [\n \"user1\",\n \"user2\"\n ],\n \"emails\": [\n \"test1@braze.com\",\n \"test2@braze.com\"\n ],\n \"phones\": [\n \"+445555555555\",\n \"+445555555556\"\n ]\n }\n ]\n}\n'\n\nResponse: (status 201)
\n{\n \"message\": \"success\"\n}\n\n\n\nUse this endpoint to batch update the subscription state of up to 50 users on the Braze dashboard.
\n
To use this endpoint, you’ll need an API key with the subscription.status.set permission.
This endpoint has 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.
This property should not be used for updating a user’s profile information. Use the /users/track property instead.
\n\n\nWhen creating new users via the /users/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.
\n
curl --location --request POST 'https://rest.iad-01.braze.com/subscription/status/set' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY' \\\n--data-raw '{\n \"subscription_group_id\": \"504e09e6-ffa4-4b31-96c3-c05d50d903cf\",\n \"subscription_state\": \"unsubscribed\",\n \"external_id\": [\n \"user1\",\n \"user2\"\n ],\n \"emails\": [\n \"test1@braze.com\",\n \"test2@braze.com\"\n ],\n \"phones\": [\n \"+445555555555\",\n \"+445555555556\"\n ]\n}\n'\n\nThe status code 201 could return the following response body.
{\n \"message\": \"success\"\n}\n\n\n\n","urlObject":{"protocol":"https","path":["subscription","status","set"],"host":["{{instance_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"72558b32-7dbe-4cba-bd22-a7ce513076dd"}],"id":"53ea7760-5280-4be6-84de-f05f5343c498","_postman_id":"53ea7760-5280-4be6-84de-f05f5343c498","description":""}],"id":"41314f9c-bef6-42b0-ac57-e0808165679b","description":"The endpoint only accepts the
\nphonevalue, 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.\"}
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. This applies to both SMS and email subscription groups.
\nLooking for guidance on creating subscription groups? Check out our articles for SMS subscription groups and email subscription groups.
\n","_postman_id":"41314f9c-bef6-42b0-ac57-e0808165679b"},{"name":"Templates","item":[{"name":"Content Blocks","item":[{"name":"List available Content Blocks","id":"6d87048f-68fd-46c9-aa15-3a970e99540e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/content_blocks/list?modified_after=2020-01-01T01:01:01.000000&modified_before=2020-02-01T01:01:01.000000&limit=100&offset=1","description":"\n\nUse this endpoint to list your existing Content Blocks information.
\n
To use this endpoint, you’ll need an API key with the content_blocks.list permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\ncurl --location --request GET 'https://rest.iad-01.braze.com/content_blocks/list?modified_after=2020-01-01T01:01:01.000000&modified_before=2020-02-01T01:01:01.000000&limit=100&offset=1' \\\n--header 'Authorization: Bearer YOUR-API-KEY-HERE'\n\nContent-Type: application/json\nAuthorization: Bearer YOUR_REST_API_KEY\n{\n \"count\": \"integer\",\n \"content_blocks\": [\n {\n \"content_block_id\": (string) the Content Block identifier,\n \"name\": (string) the name of the Content Block,\n \"content_type\": (string) the content type, html or text,\n \"liquid_tag\": (string) the Liquid tags,\n \"inclusion_count\" : (integer) the inclusion count,\n \"created_at\": (string) The time the Content Block was created in ISO 8601,\n \"last_edited\": (string) The time the Content Block was last edited in ISO 8601,\n \"tags\": (array) An array of tags formatted as strings,\n }\n ]\n}\n\nThe following table lists possible returned errors and their associated troubleshooting steps.
\n","urlObject":{"protocol":"https","path":["content_blocks","list"],"host":["{{instance_url}}"],"query":[{"description":{"content":"(Optional) String in ISO 8601
\nRetrieve only content blocks updated at or after the given time.
\n","type":"text/plain"},"key":"modified_after","value":"2020-01-01T01:01:01.000000"},{"description":{"content":"(Optional) String in ISO 8601
\nRetrieve only content blocks updated at or before the given time.
\n","type":"text/plain"},"key":"modified_before","value":"2020-02-01T01:01:01.000000"},{"description":{"content":"(Optional) Positive Number
\nMaximum number of content blocks to retrieve. Default to 100 if not provided, with a maximum acceptable value of 1000.
\n","type":"text/plain"},"key":"limit","value":"100"},{"description":{"content":"(Optional) Positive Number
\nNumber of content blocks to skip before returning rest of the templates that fit the search criteria.
\n","type":"text/plain"},"key":"offset","value":"1"}],"variable":[]}},"response":[],"_postman_id":"6d87048f-68fd-46c9-aa15-3a970e99540e"},{"name":"See Content Block information","id":"589adda3-0def-4369-9ddc-eae71923c0ee","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/content_blocks/info?content_block_id={{content_block_id}}&include_inclusion_data=false","description":"\n\nUse this endpoint to call information for your existing Content Blocks.
\n
To use this endpoint, you’ll need an API key with the content_blocks.info permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\ncurl --location -g --request GET 'https://rest.iad-01.braze.com/content_blocks/info?content_block_id={{content_block_id}}&include_inclusion_data=false' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY'\n\nContent-Type: application/json\nAuthorization: Bearer YOUR_REST_API_KEY\n{\n \"content_block_id\": (string) the Content Block identifier,\n \"name\": (string) the name of the Content Block,\n \"content\": (string) the content in the Content Block,\n \"description\": (string) the Content Block description,\n \"content_type\": (string) the content type, html or text,\n \"tags\": (array) An array of tags formatted as strings,\n \"created_at\": (string) The time the Content Block was created in ISO 8601,\n \"last_edited\": (string) The time the Content Block was last edited in ISO 8601,\n \"inclusion_count\" : (integer) the inclusion count,\n \"inclusion_data\": (array) the inclusion data,\n \"message\": \"success\",\n}\n\nThe following table lists possible returned errors and their associated troubleshooting steps.
\n","urlObject":{"protocol":"https","path":["content_blocks","info"],"host":["{{instance_url}}"],"query":[{"description":{"content":"(Required) String
\nThe Content Block identifier.
\nYou can find this by either listing Content Block information through an API call or going to the API Keys page, then scrolling to the bottom and searching for your Content Block API identifier.
\n","type":"text/plain"},"key":"content_block_id","value":"{{content_block_id}}"},{"description":{"content":"(Optional) Boolean
\nWhen 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.
\n\nUse this endpoint to create a Content Block.
\n
To use this endpoint, you’ll need an API key with the content_blocks.create permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nCopiedcurl --location --request POST 'https://rest.iad-01.braze.com/content_blocks/create' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR_REST_API_KEY' \\\n--data-raw '{\n \"name\": \"content_block\",\n \"description\": \"This is my Content Block\",\n \"content\": \"HTML content within block\",\n \"state\": \"draft\",\n \"tags\": [\"marketing\"]\n}'\n\nContent-Type: application/json\nAuthorization: Bearer YOUR_REST_API_KEY\n{\n \"content_block_id\": (string) Your newly generated block id,\n \"liquid_tag\": (string) The generated block tag from the Content Block name,\n \"created_at\": (string) The time the Content Block was created in ISO 8601,\n \"message\": \"success\"\n}\n\nThe following table lists possible returned errors and their associated troubleshooting steps.
\n","urlObject":{"protocol":"https","path":["content_blocks","create"],"host":["{{instance_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"f1cefa8b-7a28-4e64-b579-198a4610d0a5"},{"name":"Update Content Block","event":[{"listen":"prerequest","script":{"id":"9ee80f80-86b0-4d60-8cd8-d327056859f0","exec":[""],"type":"text/javascript","packages":{}}}],"id":"4782239a-cb60-4217-9de0-51411434d57d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"content_block_id\" : (required, string) Content Block's API identifier.\n \"name\": (optional, string) Must be less than 100 characters,\n \"description\": (optional, string) The description of the Content Block. Must be less than 250 character,\n \"content\": (optional, string) HTML or text content within Content Block,\n \"state\": (optional, string) Choose `active` or `draft`. Defaults to `active` if not specified,\n \"tags\": (optional, array of strings) Tags must already exist\n}"},"url":"https://{{instance_url}}/content_blocks/update","description":"\n\nUse this endpoint to update a Content Block.
\n
To use this endpoint, you’ll need an API key with the content_blocks.update permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\ncurl --location --request POST 'https://rest.iad-01.braze.com/content_blocks/update' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR_REST_API_KEY' \\\n--data-raw '{\n \"content_block_id\" :\"content_block_id\",\n \"name\": \"content_block\",\n \"description\": \"This is my Content Block\",\n \"content\": \"HTML or text content within block\",\n \"state\": \"draft\",\n \"tags\": [\"marketing\"]\n}'\n\nContent-Type: application/json\nAuthorization: Bearer YOUR_REST_API_KEY\n{\n \"content_block_id\": (string) Your newly generated block id,\n \"liquid_tag\": (string) The generated block tag from the Content Block name,\n \"created_at\": (string) The time the Content Block was created in ISO 8601,\n \"message\": \"success\"\n}\n\nThe following table lists possible returned errors and their associated troubleshooting steps.
\n","urlObject":{"protocol":"https","path":["content_blocks","update"],"host":["{{instance_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"4782239a-cb60-4217-9de0-51411434d57d"}],"id":"b39ca484-6876-4b70-8fe3-19bee69bfb74","description":"Content Blocks are an Email Templating feature that allow you to:
\nYou can edit Content Blocks in the Templates & Media section of the Braze UI, or here, via API.
\n","_postman_id":"b39ca484-6876-4b70-8fe3-19bee69bfb74"},{"name":"Email Templates","item":[{"name":"List available email templates","id":"eec24bf4-a3f4-47cb-b4d8-bb8f03964cca","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/templates/email/list?modified_after=2020-01-01T01:01:01.000000&modified_before=2020-02-01T01:01:01.000000&limit=1&offset=0","description":"\n\nUse this endpoint to get a list of available templates in your Braze account.
\n
To use this endpoint, you'll need an API key with the templates.email.list permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\ncurl --location --request GET 'https://rest.iad-01.braze.com/templates/email/list?modified_after=2020-01-01T01:01:01.000000&modified_before=2020-02-01T01:01:01.000000&limit=1&offset=0' \\\n--header 'Authorization: Bearer YOUR_REST_API_KEY'\n\nImportant: Templates built using the drag-and-drop editor for email are not provided in this response.
\nContent-Type: application/json\nAuthorization: Bearer YOUR_REST_API_KEY\n{\n \"count\": the number of templates returned\n \"templates\": [template with the following properties]:\n \"email_template_id\": (string) your email template's API Identifier,\n \"template_name\": (string) the name of your email template,\n \"created_at\": (string) the time the email was created at in ISO 8601,\n \"updated_at\": (string) the time the email was updated in ISO 8601,\n \"tags\": (array of strings) tags appended to the template\n}\n\n(Optional) String in ISO 8601
\nRetrieve only templates updated at or after the given time.
\n","type":"text/plain"},"key":"modified_after","value":"2020-01-01T01:01:01.000000"},{"description":{"content":"(Optional) String in ISO 8601
\nRetrieve only templates updated at or before the given time.
\n","type":"text/plain"},"key":"modified_before","value":"2020-02-01T01:01:01.000000"},{"description":{"content":"(Optional) Positive Number
\nMaximum number of templates to retrieve. Default to 100 if not provided, with a maximum acceptable value of 1000.
\n","type":"text/plain"},"key":"limit","value":"1"},{"description":{"content":"(Optional) Positive Number
\nNumber of templates to skip before returning rest of the templates that fit the search criteria.
\n","type":"text/plain"},"key":"offset","value":"0"}],"variable":[]}},"response":[],"_postman_id":"eec24bf4-a3f4-47cb-b4d8-bb8f03964cca"},{"name":"See email template information","id":"e98d2d5b-62fe-4358-b391-9fe9e460d0ac","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"https://{{instance_url}}/templates/email/info?email_template_id={{email_template_id}}","description":"\n\nUse this endpoint to get information on your email templates.
\n
Important: Templates built using the drag-and-drop editor are not accepted.
\nTo use this endpoint, you’ll need an API key with the templates.email.info permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\ncurl --location -g --request GET 'https://rest.iad-01.braze.com/templates/email/info?email_template_id={{email_template_id}}' \\\n--header 'Authorization: Bearer YOUR_REST_API_KEY'\n\nContent-Type: application/json\nAuthorization: Bearer YOUR_REST_API_KEY\n{\n \"email_template_id\": (string) Your email template's API Identifier,\n \"template_name\": (string) The name of your email template,\n \"description\": (string) The email template description,\n \"subject\": (string) The email template subject line,\n \"preheader\": (optional, string) The email preheader used to generate previews in some clients),\n \"body\": (optional, string) The email template body that may include HTML,\n \"plaintext_body\": (optional, string) A plaintext version of the email template body,\n \"should_inline_css\": (optional, boolean) Whether there is inline CSS in the body of the template - defaults to the css inlining value for the workspace,\n \"tags\": (string) Tag names,\n \"created_at\": (string) The time the email was created at in ISO 8601,\n \"updated_at\": (string) The time the email was updated in ISO 8601\n}\n\nImages in this response will show in the body variable as HTML.
(Required) String
\nSee email template's API identifier.
\n","type":"text/plain"},"key":"email_template_id","value":"{{email_template_id}}"}],"variable":[]}},"response":[],"_postman_id":"e98d2d5b-62fe-4358-b391-9fe9e460d0ac"},{"name":"Create email template","id":"5eb1fe0d-2795-474d-aaf2-c4e2977dc94b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"template_name\": (required, string) The name of your email template,\n \"subject\": (required, string) The email template subject line,\n \"body\": (required, string) The email template body that may include HTML,\n \"plaintext_body\": (optional, string) A plaintext version of the email template body,\n \"preheader\": (optional, string) The email preheader used to generate previews in some clients,\n \"tags\": (optional, Array of Strings) Tags must already exist,\n \"should_inline_css\": (optional, Boolean) If `true`, the `inline_css` feature is used on this template.\n }"},"url":"https://{{instance_url}}/templates/email/create?template_name&subject&body&plaintext_body&preheader&tags&should_inline_css","description":"\n\nUse this endpoint to create email templates on the Braze dashboard.
\n
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 with 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.
\nTo use this endpoint, you’ll need an API key with the templates.email.create permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nCopiedcurl --location --request POST 'https://rest.iad-01.braze.com/templates/email/create' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR_REST_API_KEY' \\\n--data-raw '{\n \"template_name\": \"email_template_name\",\n \"subject\": \"Welcome to my email template!\",\n \"body\": \"This is the text within my email body and https://www.braze.com/ here is a link to Braze.com.\",\n \"plaintext_body\": \"This is the text within my email body and here is a link to https://www.braze.com/.\",\n \"preheader\": \"My preheader is pretty cool.\",\n \"tags\": [\"Tag1\", \"Tag2\"]\n}'\n\nThe following table lists possible returned errors and their associated troubleshooting steps, if applicable.
\n","urlObject":{"protocol":"https","path":["templates","email","create"],"host":["{{instance_url}}"],"query":[{"description":{"content":"(Required) String
\n","type":"text/plain"},"key":"template_name","value":null},{"description":{"content":"(Required) String
\n","type":"text/plain"},"key":"subject","value":null},{"description":{"content":"(Required) String
\n","type":"text/plain"},"key":"body","value":null},{"description":{"content":"(Optional) String
\n","type":"text/plain"},"key":"plaintext_body","value":null},{"description":{"content":"(Optional) String
\n","type":"text/plain"},"key":"preheader","value":null},{"description":{"content":"(Optional) String
\n","type":"text/plain"},"key":"tags","value":null},{"description":{"content":"(Optional) Boolean
\n","type":"text/plain"},"key":"should_inline_css","value":null}],"variable":[]}},"response":[],"_postman_id":"5eb1fe0d-2795-474d-aaf2-c4e2977dc94b"},{"name":"Update email template","id":"afb25494-3350-458d-932d-5bf4220049fa","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"email_template_id\": (required, string) Your email template's API Identifier,\n \"template_name\": (optional, string) The name of your email template,\n \"subject\": (optional, string) The email template subject line,\n \"body\": (optional, string) The email template body that may include HTML,\n \"plaintext_body\": (optional, string) A plaintext version of the email template body,\n \"preheader\": (optional, string) The email preheader used to generate previews in some clients,\n \"tags\": (optional, array of Strings) Tags must already exist,\n \"should_inline_css\": (optional, Boolean) If `true`, the `inline_css` feature will be applied to the template.\n}","options":{"raw":{"language":"json"}}},"url":"https://{{instance_url}}/templates/email/update?email_template_id={{email_template_id}}&template_name&subject&body&plaintext_body&preheader&tags&should_inline_css","description":"\n\nUse this endpoint to update email templates on the Braze dashboard.
\n
You can access an email template’s email_template_id by navigating to it on the Templates & Media page. The Create email template endpoint 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.
To use this endpoint, you’ll need an API key with the templates.email.update permission.
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
\nThe following table lists possible returned errors and their associated troubleshooting steps, if applicable.
\ncurl --location --request POST 'https://rest.iad-01.braze.com/templates/email/update' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR_REST_API_KEY' \\\n--data-raw '{\n \"email_template_id\": \"email_template_id\",\n \"template_name\": \"Weekly Newsletter\",\n \"subject\": \"This Week'\\''s Styles\",\n \"body\": \"Check out this week'\\''s digital lookbook to inspire your outfits. Take a look at https://www.braze.com/\",\n \"plaintext_body\": \"This is the updated text within my email body and here is a link to https://www.braze.com/.\",\n \"preheader\": \"We want you to have the best looks this summer\",\n \"tags\": [\"Tag1\", \"Tag2\"]\n}'\n\nThe following table lists possible returned errors and their associated troubleshooting steps, if applicable.
\n","urlObject":{"protocol":"https","path":["templates","email","update"],"host":["{{instance_url}}"],"query":[{"description":{"content":"(Required) String
\n","type":"text/plain"},"key":"email_template_id","value":"{{email_template_id}}"},{"description":{"content":"(Optional) String
\n","type":"text/plain"},"key":"template_name","value":null},{"description":{"content":"(Optional) String
\n","type":"text/plain"},"key":"subject","value":null},{"description":{"content":"(Optional) String
\n","type":"text/plain"},"key":"body","value":null},{"description":{"content":"(Optional) String
\n","type":"text/plain"},"key":"plaintext_body","value":null},{"description":{"content":"(Optional) String
\n","type":"text/plain"},"key":"preheader","value":null},{"description":{"content":"(Optional) String
\n","type":"text/plain"},"key":"tags","value":null},{"description":{"content":"(Optional) Boolean
\n","type":"text/plain"},"key":"should_inline_css","value":null}],"variable":[]}},"response":[],"_postman_id":"afb25494-3350-458d-932d-5bf4220049fa"}],"id":"7fd91278-ca24-48b2-99d8-e156c5423eb9","_postman_id":"7fd91278-ca24-48b2-99d8-e156c5423eb9","description":""}],"id":"5bf8d4ab-74e2-4b6c-9e53-a0b9b8aa7947","description":"Using the Template endpoints, you can create and manage your templates for email and Content Blocks.
\nLooking for more guidance on creating templates for email and Content Blocks? Check out our dedicated for Email Templates section and Content Blocks article.
\n","_postman_id":"5bf8d4ab-74e2-4b6c-9e53-a0b9b8aa7947"},{"name":"User Data","item":[{"name":"External ID Migration","item":[{"name":"Rename external ID","id":"17682d2b-1546-4a3c-9703-aa5a12861d7c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","type":"text","value":"application/json"},{"key":"Authorization","type":"text","value":"Bearer {{api_key}}"}],"body":{"mode":"raw","raw":"{\n \"external_id_renames\" :[\n {\n \"current_external_id\": \"existing_external_id\",\n \"new_external_id\" : \"new_external_id\"\n }\n ]\n}"},"url":"https://{{instance_url}}/users/external_ids/rename","description":"\n\nUse this endpoint to rename your users’ external IDs.
\n
You can send up to 50 rename objects per request.
\nThis 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.
\n\nWarning: Make sure to remove deprecated external IDs with the
\n/users/external_ids/removeendpoint instead of/users/delete. Sending a request to/users/deletewith the deprecated external ID deletes the user profile entirely and cannot be undone.
To use this endpoint, you’ll need an API key with the users.external_ids.rename permission.
We apply a rate limit of 1,000 requests per minute to this endpoint, as documented in API rate limits.
\nNote the following:
\nThe current_external_id must be the user’s 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.
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.
{\n \"message\" : (string) status message,\n \"external_ids\" : (array of strings) successful rename operations,\n \"rename_errors\": (array of arrays) <minor error message>\n}\n\nThe 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
\nEmpty external_id_renames array
external_id_renames array with more than 50 objects
Rate limit hit (more than 1,000 requests per minute)
\nNo, since the number of users will stay the same, they’ll just have a new external_id.
No, since the user is still the same user, and all their historical behavior is still connected to them.
\nYes. 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.
\nThis feature does not cost data points.
\nWe 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.
\n","urlObject":{"protocol":"https","path":["users","external_ids","rename"],"host":["{{instance_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"17682d2b-1546-4a3c-9703-aa5a12861d7c"},{"name":"Remove external ID","id":"e16b5340-5f44-42b6-9033-2398faf8908e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"external_ids\" :[\n \"existing_deprecated_external_id_string\",\n ...\n ]\n}"},"url":"https://{{instance_url}}/users/external_ids/remove","description":"\n\nUse this endpoint to remove your users' old deprecated external IDs.
\n
You can send up to 50 external IDs per request. To use this endpoint, you’ll need to generate an API key with the users.external_ids.remove permission.
\n\nWarning: 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.
\n
We apply a rate limit of 1,000 requests per minute to this endpoint, as documented in API rate limits.
\n\n\nImportant: Only deprecated IDs can be removed; attempting to remove a primary external ID will result in an error.
\n
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.
{\n \"message\" : (string) status message,\n \"removed_ids\" : (array of strings) successful remove operations,\n \"removal_errors\": (array of arrays) <minor error message>\n}\n\nThe 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
\nEmpty external_ids array
external_ids array with more than 50 items
Rate limit hit (more than 1,000 requests per minute)
\nThe 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 don’t break. We highly recommend removing deprecated External IDs once your old naming schema is no longer in use.
\n\nUse this endpoint to add new user aliases for existing identified users, or to create new unidentified users.
\n
Up to 50 user aliases may be specified per request.
\nAdding 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. After 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.
To use this endpoint, you'll need an API key with the users.alias.new permission.
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.
\nContent-Type: application/json\nAuthorization: Bearer YOUR_REST_API_KEY\n{\n \"aliases_processed\": 1,\n \"message\": \"success\"\n}\n\n\nUse this endpoint to update existing user aliases.
\n
Up to 50 user aliases may be specified per request.
\nUpdating 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.
Note: This endpoint does not guarantee the sequence of alias_updates objects being updated.
To use this endpoint, you'll need an API key with the users.alias.update permission.
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.
{\n \"alias_label\" : (required, string),\n \"old_alias_name\" : (required, string),\n \"new_alias_name\" : (required, string)\n}\n\n\n\nUse this endpoint to identify an unidentified (alias-only or email-only) user using the provided external ID.
\n
Calling /users/identify combines a user profile that is identified by an alias (alias-only profile) or email address (email-only profile) with a user profile that has an external_id (identified profile), then removes the alias-only profile.
Identifying a user requires an external_id to be included in the aliases_to_identify or emails_to_identify object. If there isn’t a user with that external_id, the external_id will be added to the aliased user’s record, and the user will be considered identified.
Note the following:
\nWhen 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, 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 found on the anonymous user to the identified user.
\n\nTip: To prevent unexpected loss of data when identifying users, we highly recommend that you first refer to data collection best practices to learn about capturing user data when alias-only user info is already present.
\n
To use this endpoint, you'll need an API key with the users.identify permission.
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.
Setting the merge_behavior field to merge sets the endpoint to merge the following list of fields found exclusively on the anonymous user to the identified user. Setting the field to none will not merge any user data to the identified user profile.
First name
\nLast name
\nGender
\nDate of birth
\nPhone number
\nTime zone
\nHome city
\nCountry
\nLanguage
\nSession count (the sum of sessions from both profiles)
\nDate of first session (Braze will pick the earlier date of the two dates)
\nDate of last session (Braze will pick the later date of the two dates)
\nCustom attributes
\nCustom event and purchase event data (excluding event properties)
\nCustom event and purchase event properties for \"X times in Y days\" segmentation (where X<=50 and Y<=30)
\nSegmentable custom events summary
\nEvent count (the sum from both profiles)
\nEvent first occurred (Braze will pick the earlier date of the two dates)
\nEvent last occurred (Braze will pick the later date of the two dates)
\nIn-app purchase total in cents (the sum from both profiles)
\nTotal number of purchases (the sum from both profiles)
\nDate of first purchase (Braze will pick the earlier date of the two dates)
\nDate of last purchase (Braze will pick the later date of the two dates)
\nApp summaries
\nLast_X_at fields (Braze will update the fields if the orphaned profile fields are more recent)
\nCampaign summaries (Braze will pick the most recent date fields)
\nWorkflow summaries (Braze will pick the most recent date fields)
\nMessage and message engagement history
\nCustom event and purchase event count and first date and last date timestamps
\nSession data if the app exists on both user profiles
\nIf an email is specified as an identifier, an additional prioritization value is required in the identifier. The prioritization should be an array specifying which user to merge if there are multiple users found. prioritization is an ordered array, meaning if more than one user matches from a prioritization, then merging will not occur.
The allowed values for the array are: identified, unidentified, most_recently_updated. most_recently_updated refers to prioritizing the most recently updated user.
Only one of the following options may exist in the prioritization array at a time:
\nidentified refers to prioritizing a user with an external_id
unidentified refers to prioritizing a user without an external_id
curl --location --request POST 'https://rest.iad-01.braze.com/users/identify' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR_REST_API_KEY' \\\n--data-raw '{\n \"aliases_to_identify\": [\n {\n \"external_id\": \"external_identifier\",\n \"user_alias\": {\n \"alias_name\": \"example_alias\",\n \"alias_label\": \"example_label\"\n }\n }\n ],\n \"emails_to_identify\": [\n {\n \"external_id\": \"external_identifier_2\",\n \"email\": \"john.smith@braze.com\",\n \"prioritization\": [\"unidentified\", \"most_recently_updated\"]\n }\n ]\n \"merge_behavior\": \"merge\"\n}'\n\nContent-Type: application/json\nAuthorization: Bearer YOUR_REST_API_KEY\n{\n \"aliases_processed\": 1,\n \"message\": \"success\"\n}\n\n\n\nUse this endpoint to record custom events, purchases, and update user profile attributes.
\n
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.
\nTo use this endpoint, you'll need an API key with the users.track permission.
Customers using the API for server-to-server calls may need to allowlist rest.iad-01.braze.com if they’re behind a firewall.
Starting on October 28th, 2024, we apply a base speed limit of 3,000 requests per three seconds to this endpoint for all customers. Each /users/track request can contain up to 75 event objects, 75 attribute objects, and 75 purchase objects. Each object (event, attribute, and purchase arrays) can update one user each. In total, this means a maximum of 225 users can be updated in a single call. In addition, a single user profile can be updated by multiple objects.
Different limits apply to customers who have purchased Monthly Active Users - CY 24-25. For details on these limits, see Monthly Active Users - CY 24-25 limits.
\nSee our page on API rate limits for details, and reach out to your customer success manager if you need your limit increased.
\n\n\nImportant: For each request component listed in the following table, one of
\nexternal_id,user_alias,braze_id,phoneis required.
You can update a user profile by email address using the /users/track endpoint.
curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR_REST_API_KEY' \\\n--data-raw '{\n \"attributes\": [\n {\n \"email\": \"test@braze.com\",\n \"string_attribute\": \"fruit\",\n \"boolean_attribute_1\": true,\n \"integer_attribute\": 26,\n \"array_attribute\": [\n \"banana\",\n \"apple\"\n ]\n }\n ],\n \"events\": [\n {\n \"email\": \"test@braze.com\",\n \"app_id\": \"your_app_identifier\",\n \"name\": \"rented_movie\",\n \"time\": \"2022-12-06T19:20:45+01:00\",\n \"properties\": {\n \"release\": {\n \"studio\": \"FilmStudio\",\n \"year\": \"2022\"\n },\n \"cast\": [\n {\n \"name\": \"Actor1\"\n },\n {\n \"name\": \"Actor2\"\n }\n ]\n }\n },\n {\n \"user_alias\": {\n \"alias_name\": \"device123\",\n \"alias_label\": \"my_device_identifier\"\n },\n \"app_id\": \"your_app_identifier\",\n \"name\": \"rented_movie\",\n \"time\": \"2013-07-16T19:20:50+01:00\"\n }\n ],\n \"purchases\": [\n {\n \"email\": \"test@braze.com\",\n \"app_id\": \"your_app_identifier\",\n \"product_id\": \"product_name\",\n \"currency\": \"USD\",\n \"price\": 12.12,\n \"quantity\": 6,\n \"time\": \"2017-05-12T18:47:12Z\",\n \"properties\": {\n \"color\": \"red\",\n \"monogram\": \"ABC\",\n \"checkout_duration\": 180,\n \"size\": \"Large\",\n \"brand\": \"Backpack Locker\"\n }\n }\n ]\n}'\n\nYou can update a user profile by phone number using the /users/track endpoint. This endpoint only works if you include a valid phone number.
\n\nImportant:
\n
If you include a request with bothphone, Braze will use the email as the identifier.
curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR_REST_API_KEY' \\\n--data-raw '{\n \"attributes\": [\n {\n \"phone\": \"+15043277269\",\n \"string_attribute\": \"fruit\",\n \"boolean_attribute_1\": true,\n \"integer_attribute\": 25,\n \"array_attribute\": [\n \"banana\",\n \"apple\"\n ]\n }\n ],\n}'\n\nThis example shows how to create a user and set their subscription group within the user attributes object.
\nUpdating the subscription status with this endpoint will update the user specified by their external_id (such as User1) and update the subscription status of any users with the same email as that user (User1).
curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR_REST_API_KEY' \\\n--data-raw '{\n \"attributes\": [\n {\n \"external_id\": \"user_identifier\",\n \"email\": \"example@email.com\",\n \"email_subscribe\": \"subscribed\",\n \"subscription_groups\": [{\n \"subscription_group_id\": \"subscription_group_identifier_1\",\n \"subscription_state\": \"unsubscribed\"\n },\n {\n \"subscription_group_id\": \"subscription_group_identifier_2\",\n \"subscription_state\": \"subscribed\"\n },\n {\n \"subscription_group_id\": \"subscription_group_identifier_3\",\n \"subscription_state\": \"subscribed\"\n }\n ]\n }\n ]\n}'\n\nYou 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.
curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR_REST_API_KEY' \\\n--data-raw '{\n{\n \"attributes\": [\n {\n \"_update_existing_only\": false,\n \"user_alias\": {\n \"alias_name\": \"example_name\",\n \"alias_label\": \"example_label\"\n },\n \"email\": \"email@example.com\"\n }\n ],\n}'\n\nWhen using any of the aforementioned API requests, you should receive one of the following three general responses: a successful message, a successful message with non-fatal errors, or a message with fatal errors.
\nSuccessful messages will be met with the following response:
\n{\n \"message\" : \"success\",\n \"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,\n \"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,\n \"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,\n}\n\nIf 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:
\n{\n \"message\" : \"success\",\n \"errors\" : [\n {\n <minor error message>\n }\n ]\n}\n\nFor success messages, any data 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:
\n{\n \"message\" : <fatal error message>,\n \"errors\" : [\n {\n <fatal error message>\n }\n ]\n}\n\nFor status codes and associated error messages that will be returned if your request encounters a fatal error, reference Fatal errors & responses.
\nIf 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.
\n\n\nImportant:
\n
\n\nDo not send legally required transactional emails to SMS gateways as there’s a strong likelihood that those emails will not be delivered.
\n
Although emails you send using a phone number and the provider’s gateway domain (known as an MM3) can result in the email being received as an SMS (text) message, some of our email providers do not support this behavior. For example, if you send an email to a T-Mobile phone number (such as “9999999999@tmomail.net”), your SMS message would be sent to whoever owns that phone number on the T-Mobile network.
\nKeep in mind that even though these emails may not be delivered to the SMS gateway, they will still count towards your email billing. To avoid sending emails to unsupported gateways, review the list of unsupported gateway domain names.
\nIf the external_id exists, the most recently updated profile with an external ID will be prioritized for updates. If the external_id doesn’t exist, the most recently updated profile will be prioritized for updates.
A new profile will be created, and an email-only user will be created. An alias will not be created. The email field will be set to test@braze.com, as noted in the example request for updating a user profile by email address.
\n/users/track to import legacy user data?You may submit data through the Braze API for a user who has not yet used your mobile app to generate a user profile. If the user subsequently uses the application all information following their identification using the SDK will be merged with the existing user profile you created using the API call. Any user behavior recorded anonymously by the SDK before identification will be lost upon merging with the existing API-generated user profile.
\nThe segmentation tool will include these users regardless of whether they have engaged with the app. If you want to exclude users uploaded using the User API who have not yet engaged with the app, add the Session Count > 0 filter.
/users/track handle duplicate events?Each event object in the events array represents a single occurrence of a custom event by a user at a designated time. This means each event ingested into Braze has its own event ID, so “duplicate” events are treated as separate, unique events.
\nFor customers who have purchased Monthly Active Users - CY 24-25, Braze manages different rate limits on its /users/track endpoint:
Hourly rate limits are set according to the expected data ingestion activity on your account, which may correspond to the number of monthly active users you have purchased, industry, seasonality, or other factors.
\nIn addition to the limit on requests per hour, Braze also imposes a burst limit on the number of requests allowed per second.
\nEach request may batch up to 50 updates combined across attribute, event, or purchase objects.
\nCurrent limits based on expected ingestion can be found in the dashboard under Settings > APIs and Identifiers > API limits. We may modify rate limits to protect system stability or allow for increased data throughput on your account. Please contact Braze Support or your customer success manager for questions or concerns regarding hourly or per-second request limit and the needs of your business.
\n","urlObject":{"protocol":"https","path":["users","track"],"host":["{{instance_url}}"],"query":[{"disabled":true,"key":"","value":""}],"variable":[]}},"response":[],"_postman_id":"4cf57ea9-9b37-4e99-a02e-4373c9a4ee59"},{"name":"Delete users","id":"22e91d00-d178-4b4f-a3df-0073ecfcc992","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","type":"text","value":"Bearer {{api_key}}"}],"body":{"mode":"raw","raw":"{\n \"external_ids\": [\"external_identifier1\", \"external_identifier2\"],\n \"braze_ids\": [\"braze_identifier1\", \"braze_identifier2\"],\n \"user_aliases\": [\n {\n \"alias_name\": \"user_alias1\", \"alias_label\": \"alias_label1\"\n },\n {\n \"alias_name\": \"user_alias2\", \"alias_label\": \"alias_label2\"\n }\n ]\n}"},"url":"https://{{instance_url}}/users/delete","description":"\n\nUse this endpoint to delete any user profile by specifying a known user identifier.
\n
Up to 50 external_ids, user_aliases, braze_ids, or email_addresses can be included in a single request. Only one of external_ids, user_aliases, braze_ids, or email_addresses can be included in a single request.
\n\nWarning: 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 using the API in our Help documentation.
\n
To use this endpoint, you'll need an API key with the users.delete permission.
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.
If an email is specified as an identifier, an additional prioritization value is required in the identifier. The prioritization is an ordered array and should specify which user to delete if multiple users are found. This means deleting users will not occur if more than one user matches a prioritization.
The allowed values for the array are: identified, unidentified, most_recently_updated. most_recently_updated refers to prioritizing the most recently updated user.
Only one of the following options may exist in the prioritization array at a time:
\nidentified refers to prioritizing a user with an external_id
unidentified refers to prioritizing a user without an external_id
Content-Type: application/json\nAuthorization: Bearer YOUR_REST_API_KEY\n{\n \"deleted\" : (required, integer) number of user IDs queued for deletion\n}\n\n\n\nUse this endpoint to merge one user into another user.
\n
Up to 50 merges may be specified per request. This endpoint is asynchronous.
\nTo use this endpoint, you'll need an API key with the users.merge permission.
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.
The behavior documented below is true for all Braze features that are not powered by Snowflake. User merges won’t be reflected for the Messaging History tab, Segment Extensions, Query Builder, and Currents.
\n\n\nImportant: The endpoint does not guarantee the sequence of
\nmerge_updatesobjects being updated.
This endpoint will merge any of the following fields if they're not found on the target user:
\nFirst name
\nLast name
\nGender
\nDate of birth
\nPhone number
\nTime zone
\nHome city
\nCountry
\nLanguage
\nSession count (the sum of sessions from both profiles)
\nDate of first session (Braze will pick the earlier date of the two dates)
\nDate of last session (Braze will pick the later date of the two dates)
\nCustom attributes (existing custom attributes on the target profile are retained and will include custom attributes that didn’t exist on the target profile)
\nCustom event and purchase event data
\nCustom event and purchase event properties for “X times in Y days” segmentation (where X<=50 and Y<=30)
\nSegmentable custom events summary
\nEvent count (the sum from both profiles)
\nEvent first occurred (Braze will pick the earlier date of the two dates)
\nEvent last occurred (Braze will pick the later date of the two dates)
\nIn-app purchase total in cents (the sum from both profiles)
\nTotal number of purchases (the sum from both profiles)
\nDate of first purchase (Braze will pick the earlier date of the two dates)
\nDate of last purchase (Braze will pick the later date of the two dates)
\nApp summaries
\nLast_X_at fields (Braze will update the fields if the orphaned profile fields are more recent)
\nCampaign interaction data (Braze will pick the most recent date fields)
\nWorkflow summaries (Braze will pick the most recent date fields)
\nMessage and message engagement history
\nSession data will only be merged if the app exists on both user profiles
\n\n\nNote: When merging users, using the
\n/users/mergeendpoint works the same way as using the <code>changeUser()</code> method.
Note that 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”.
\nIf an email or phone is specified as an identifier, an additional prioritization value is required in the identifier. The prioritization should be an array specifying which user to merge if there are multiple users found. prioritization is an ordered array, meaning if more than one user matches from a prioritization, then merging will not occur.
The allowed values for the array are: identified, unidentified, most_recently_updated. most_recently_updated refers to prioritizing the most recently updated user.
Only one of the following options may exist in the prioritization array at a time:
\nidentified refers to prioritizing a user with an external_id
unidentified refers to prioritizing a user without an external_id
There are two status code responses for this endpoint: 202 and 400.
The status code 202 could return the following response body.
{\n \"message\": \"success\"\n}\n\nThe status code 400 could return the following response body. Refer to Troubleshooting for more information about errors you may encounter.
{\n \"message\": \"'merge_updates' must be an array of objects\"\n}\n\nThe following table lists possible error messages that may occur.
\n","urlObject":{"protocol":"https","path":["users","merge"],"host":["{{instance_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"d262b86d-cf84-46e2-b9d0-f882bb7078de"}],"id":"903f23b8-dd85-4c82-bff8-9f651d916888","description":"The Braze User Data endpoints allow you to track information about your users by logging data about them that comes from outside your mobile app. You can also use this API to delete users for testing or other purposes.
\nAll API endpoints have a data payload limit of 4 MB. Attempts to post more data than 4 MB will fail with an HTTP 413 Request Entity Too Large.
\nThe examples in this section contain the URL https://rest.iad-01.braze.com, but you may need to use a different endpoint URL (for example, if you're hosted in the Braze EU data center or have a dedicated Braze installation). Your Braze customer success manager will inform you if you should use a different endpoint URL.
\n","_postman_id":"903f23b8-dd85-4c82-bff8-9f651d916888"}],"event":[{"listen":"prerequest","script":{"id":"fe2426d8-1773-4b52-8ae4-5c0891772518","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"5c6ba08d-e78a-4ca3-988b-0266805b9f32","type":"text/javascript","exec":[""]}}]}