openapi: 3.0.0 info: title: Braze Preference Center API description: 'The Braze and Radar integration allows you to access sophisticated location-based campaign triggers and user profile enrichment with rich, first-party location data. When Radar geofence or trip tracking events are generated, custom events and user attributes are sent to Braze in real-time. These events and attributes can then be used to trigger location-based campaigns, power last-mile pickup and delivery operations, monitor fleet and shipping logistics, or build user segments based on location patterns. ' version: 1.0.0 servers: - url: https://rest.iad-01.braze.com description: REST endpoint for instance US-01 - url: https://rest.iad-01.braze.com description: REST endpoint for instance US-01 - url: https://rest.iad-02.braze.com description: REST endpoint for instance US-02 - url: https://rest.iad-03.braze.com description: REST endpoint for instance US-03 - url: https://rest.iad-04.braze.com description: REST endpoint for instance US-04 - url: https://rest.iad-05.braze.com description: REST endpoint for instance US-05 - url: https://rest.iad-06.braze.com description: REST endpoint for instance US-06 - url: https://rest.iad-08.braze.com description: REST endpoint for instance US-08 - url: https://rest.fra-01.braze.eu description: REST endpoint for instance EU-01 - url: https://rest.fra-02.braze.eu description: REST endpoint for instance EU-02 security: - BearerAuth: [] tags: - name: Preference Center paths: /preference_center_v1/{PreferenceCenterExternalID}/url/{UserID}: get: tags: - Preference Center summary: Generate Preference Center URL description: "> Use this endpoint to generate a URL for a preference center. \n \n\nTo use this endpoint, youll need to generate an API key with the `preference_center.user.get` permission.\n\nEach preference center URL is unique to each user.\n\n## Rate limit\n\nThis endpoint has a rate limit of 1,000 requests per minute, per workspace.\n\n## Path parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `preferenceCenterExternalID` | Required | String | The ID for your preference center. |\n| `userID` | Required | String | The user ID. |\n\n## Example request\n\n```\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\n## Response\n\n``` json\n{\n \"preference_center_url\": \"https://www.example.com/preferences\"\n}\n\n```" parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: preference_center_api_id in: query schema: type: string example: '{{preference_center_api_id}}' - name: external_id in: query schema: type: string description: (Required) String example: '{{external_id}}' - name: PreferenceCenterExternalID in: path schema: type: string required: true - name: UserID in: path schema: type: string required: true responses: '200': description: Successful response content: application/json: schema: type: object '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' /preference_center/v1/list: get: tags: - Preference Center summary: List Preference Centers description: "> Use this endpoint to list your available preference centers. \n \n\nTo use this endpoint, youll need to generate an API key with the `preference_center.list` permission.\n\n## Rate limit\n\nThis endpoint has a rate limit of 1,000 requests per minute, per workspace.\n\n## Path and request parameters\n\nThere are no path or request parameters for this endpoint.\n\n## Example request\n\n```\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\n## Response\n\n``` json\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```" parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} responses: '200': description: Successful response content: application/json: schema: type: object '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' /preference_center/v1/{PreferenceCenterExternalID}: get: tags: - Preference Center summary: View Details for Preference Center description: "> Use this endpoint to view the details for your preference centers, including when it was created and updated. \n \n\nTo use this endpoint, youll need to generate an API key with the `preference_center.get` permission.\n\n## Rate limit\n\nThis endpoint has a rate limit of 1,000 requests per minute, per workspace.\n\n## Path parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `preferenceCenterExternalID` | Required | String | The ID for your preference center. |\n\n## Request parameters\n\nThere are no request parameters for this endpoint.\n\n## Example request\n\n```\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\n## Response\n\n``` json\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```" parameters: - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: PreferenceCenterExternalID in: path schema: type: string required: true responses: '200': description: Successful response content: application/json: schema: type: object '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' put: tags: - Preference Center summary: Update Preference Center description: "> Use this endpoint to update a preference center. \n \n\nTo use this endpoint, youll need to generate an API key with the `preference_center.update` permission.\n\n## Rate limit\n\nThis endpoint has a rate limit of 10 requests per minute, per workspace.\n\n## Path parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `preferenceCenterExternalID` | Required | String | The ID for your preference center. |\n\n## Request parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `preference_center_page_html` | Required | String | The HTML for the preference center page. |\n| `preference_center_title` | Optional | String | The title for the preference center and confirmation pages. If a title is not specified, the title of the pages will default to \"Preference Center\". |\n| `confirmation_page_html` | Required | String | The HTML for the confirmation page. |\n| `state` | Optional | String | Choose `active` or `draft`. |\n| `options` | Optional | Object | Attributes: `meta-viewport-content`. When present, a `viewport` meta tag will be added to the page with `content=` . |\n\n## Example request\n\n```\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\n## Example response\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\n```" requestBody: content: application/json: schema: type: object example: external_send_id: YOUR_BASE64_COMPATIBLE_ID trigger_properties: example_string_property: YOUR_EXAMPLE_STRING example_integer_property: YOUR_EXAMPLE_INTEGER recipient: - external_user_id: TARGETED_USER_ID_STRING properties: external_send_id: type: string trigger_properties: type: object properties: example_string_property: type: string example_integer_property: type: string recipient: type: array items: type: object properties: external_user_id: type: string parameters: - name: Content-Type in: header schema: type: string example: application/json - name: Authorization in: header schema: type: string example: Bearer {{api_key}} - name: PreferenceCenterExternalID in: path schema: type: string required: true responses: '200': description: Successful response content: application/json: schema: type: object '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' /preference_center/v1: post: tags: - Preference Center summary: Create Preference Center description: "> Use this endpoint to create a preference center to allow users to manage their notification preferences for email campaigns. \n \n\nTo use this endpoint, youll need to generate an API key with the `preference_center.update` permission.\n\nCheck out [Creating a preference center via API](https://www.braze.com/docs/user_guide/message_building_by_channel/email/preference_center/) for details on how to include this in your email campaigns.\n\n## Rate limit\n\nThis endpoint has a rate limit of 10 requests per minute, per workspace.\n\n## Request parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `name` | Required | String | The name of the preference center that meets the following requirements:
\\- Only contains letters, numbers, hyphens, and underscores
\\- Does not have spaces |\n| `preference_center_title` | Optional | String | The title for the preference center and confirmation pages. If a title is not specified, the title of the pages will default to \"Preference Center\". |\n| `preference_center_page_html` | Required | String | The HTML for the preference center page. |\n| `confirmation_page_html` | Required | String | The HTML for the confirmation page. |\n| `state` | Optional | String | Choose `active` or `draft`. Defaults to `active` if not specified. |\n| `options` | Optional | Object | Attributes: `meta-viewport-content`. When present, a `viewport` meta tag will be added to the page with `content=` . |\n\n> **Note:** The preference center name can't be edited once created. \n \n\n### Liquid tags\n\nRefer 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#### User subscription state\n\n| Liquid | Description |\n| --- | --- |\n| `{{subscribed_state.${email_global}}}` | Get the global email subscribed state for the user (i.e., \"opted_in\", \"subscribed\", or \"unsubscribed\". |\n| `{{subscribed_state.${}}}` | Get the subscribed state of the specified subscription group for the user (i.e., \"subscribed\" or \"unsubscribed\"). |\n\n#### Form inputs and action\n\n| Liquid | Description |\n| --- | --- |\n| `{% form_field_name :email_global_state %}` | Indicates that a specific form input element corresponds to the user's global email subscribed state. The user's selection state should be \"opted_in\", \"subscribed\", or \"unsubscribed\" when the form is submitted with selection data for the global email subscribed state. If it's a checkbox, the user will either be \"opted_in\" or \"unsubscribed\". For a hidden input, the \"subscribed\" state will also be valid. |\n| `{% form_field_name :subscription_group %}` | Indicates that a specific form input element corresponds to a given subscription group. The user's selection state should be either \"subscribed\" or \"unsubscribed\" when the form is submitted with selection data for a specific subscription group. |\n| `{{preference_center_submit_url}}` | Generates URL for form submission. |\n\n## Example response\n\n```\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```" requestBody: content: application/json: schema: type: object example: name: string preference_center_title: string preference_center_page_html: string confirmation_page_html: string state: active options: meta-viewport-content: string properties: name: type: string preference_center_title: type: string preference_center_page_html: type: string confirmation_page_html: type: string state: type: string options: type: object properties: meta-viewport-content: type: string parameters: - name: Content-Type in: header schema: type: string example: application/json - name: Authorization in: header schema: type: string example: Bearer {{api_key}} responses: '200': description: Successful response content: application/json: schema: type: object '201': description: Successful response content: application/json: schema: type: object '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' components: responses: Forbidden: description: 403 Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: 401 Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: 429 Rate Limited content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: 404 Not Found content: application/json: schema: $ref: '#/components/schemas/Error' BadRequest: description: 400 Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: 500 Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' schemas: Error: type: object properties: message: type: string errors: type: array items: type: string securitySchemes: BearerAuth: type: http scheme: bearer