Braze Preference Center API
The Preference Center API from Braze — 4 operation(s) for preference center.
OpenAPI Specification
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: <br>\\- Only contains letters, numbers, hyphens, and underscores <br>\\- 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