---
openapi: 3.0.3
info:
title: Braze REST API – Schedule API-triggered Canvases
description: 'Use this endpoint to schedule Canvas messages via API-triggered delivery, allowing you to decide what action should trigger the message to be sent.
'
version: 1.0.0
contact:
name: Braze Support
url: https://www.braze.com/docs/braze_support/
license:
name: Braze Documentation
url: https://www.braze.com/docs/api/home/
servers:
- url: https://rest.iad-01.braze.com
description: US-01
- url: https://rest.iad-02.braze.com
description: US-02
- url: https://rest.iad-03.braze.com
description: US-03
- url: https://rest.iad-04.braze.com
description: US-04
- url: https://rest.iad-05.braze.com
description: US-05
- url: https://rest.iad-06.braze.com
description: US-06
- url: https://rest.iad-07.braze.com
description: US-07
- url: https://rest.iad-08.braze.com
description: US-08
- url: https://rest.us-10.braze.com
description: US-10
- url: https://rest.fra-01.braze.eu
description: EU-01
- url: https://rest.fra-02.braze.eu
description: EU-02
- url: https://rest.au-01.braze.com
description: AU-01
- url: https://rest.id-01.braze.com
description: ID-01
- url: https://rest.jp-01.braze.com
description: JP-01
- url: https://rest.kr-01.braze.com
description: KR-01
security:
- BearerAuth: []
paths:
"/canvas/trigger/schedule/create":
post:
summary: Schedule API-triggered Canvases
description: |
## Prerequisites
To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key/) with the `canvas.trigger.schedule.create` permission.
## Rate limit
When you use connected audience filters in your request, this endpoint has a rate limit of 250 requests per minute. Otherwise, if you specify an `external_id`, this endpoint has a default rate limit of 250,000 requests per hour, shared between the endpoints documented in [API rate limits]({{site.baseurl}}/api/api_limits#requests-with-shared-rate-limits).
This endpoint supports [batching API requests]({{site.baseurl}}/api/api_limits#batching-api-requests). One request can include any of the following:
- Up to 50 `recipients` by default
- A [connected audience]({{site.baseurl}}/api/objects_filters/connected_audience) of any size
**Note:**
Canvas entries are recorded at the scheduled message time, not when this API request is made. Users triggered for a future-dated schedule won't appear as entries until that scheduled time arrives.
## Request body
The following headers and request body are required for this endpoint.
```
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY
```
```json
{
"canvas_id": (required, string) see Canvas identifier,
// Including 'recipients' will send only to the provided user ids if they are in the campaign's segment
"recipients": (optional, array of recipients object),
// for any keys that conflict between these trigger properties and those in a Recipients Object, the value from the
// Recipients Object will be used
"audience": (optional, connected audience object) see connected audience,
// Including 'audience' will only send to users in the audience
// If 'recipients' and 'audience' are not provided and broadcast is not set to 'false',
// the message will send to entire segment targeted by the Canvas
"broadcast": (optional, boolean) see broadcast -- defaults to false on 8/31/17, must be set to true if "recipients" object is omitted,
"context": (optional, object) personalization key-value pairs for the first step for all users in this send; see trigger properties,
"schedule": {
"time": (required, datetime as ISO 8601 string) time to send the message,
"in_local_time": (optional, bool),
"at_optimal_time": (optional, bool),
}
}
```
## Request parameters
The following table lists the request parameters for this endpoint.
| Parameter | Required | Data Type | Description |
| --------- | ---------| --------- | ----------- |
|`canvas_id`|Required|String| See [Canvas identifier]({{site.baseurl}}/api/identifier_types/). |
| `recipients` | Optional | Array of recipients objects | See [recipients object]({{site.baseurl}}/api/objects_filters/recipient_object/). |
| `audience` | Optional | Connected audience object | See [connected audience]({{site.baseurl}}/api/objects_filters/connected_audience/). |
|`broadcast`| Optional | Boolean | You must set `broadcast` to true when sending a message to an entire segment that a campaign or Canvas targets. This parameter defaults to false (as of August 31, 2017).
If `broadcast` is set to true, a `recipients` list cannot be included. However, use caution when setting `broadcast: true`, as unintentionally setting this flag may cause you to send your message to a larger than expected audience. |
| `context` | Optional | Object | Personalization key-value pairs for all users in this send. See [Canvas context object]({{site.baseurl}}/user_guide/messaging/canvas/canvas_components/context/).
Every workspace also accepts `canvas_entry_properties` for these key-value pairs, at both the request level and the recipient level. If you're not sure whether your workspace supports `context`, use `canvas_entry_properties`. |
| `schedule` | Required | Schedule object | See [schedule object]({{site.baseurl}}/api/objects_filters/schedule_object/). |
## Example request
The following sample request shows an example of how to schedule an API-triggered Canvas.
```
curl --location --request POST 'https://rest.iad-01.braze.com/canvas/trigger/schedule/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
"canvas_id": "canvas_identifier",
"recipients": [
{
"user_alias": "example_alias",
"external_user_id": "external_user_identifier",
"context": {}
}
],
"audience": {
"AND": [
{
"custom_attribute": {
"custom_attribute_name": "eye_color",
"comparison": "equals",
"value": "blue"
}
},
{
"custom_attribute": {
"custom_attribute_name": "favorite_foods",
"comparison": "includes_value",
"value": "pizza"
}
},
{
"OR": [
{
"custom_attribute": {
"custom_attribute_name": "last_purchase_time",
"comparison": "less_than_x_days_ago",
"value": 2
}
},
{
"push_subscription_status": {
"comparison": "is",
"value": "opted_in"
}
}
]
},
{
"email_subscription_status": {
"comparison": "is_not",
"value": "subscribed"
}
},
{
"last_used_app": {
"comparison": "after",
"value": "2019-07-22T13:17:55+0000"
}
}
]
},
"broadcast": false,
"context": {},
"schedule": {
"time": "",
"in_local_time": false,
"at_optimal_time": false
}
}'
```
## Response
The following sample response shows an example of the response returned when you schedule API-triggered Canvases.
```json
{
"dispatch_id": "dispatch_identifier",
"schedule_id": "schedule_identifier",
"message": "success"
}
```
## Response status codes
The following table lists the responses for this endpoint, the error message you may receive, and how to resolve it.
**Note:**
If your workspace accepts `canvas_entry_properties` instead of `context`, error messages name `canvas_entry_properties` in place of `context`.
| Status code | Meaning | Error message | How to resolve |
| --- | --- | --- | --- |
| `201 Created` | The request was accepted. The response includes a `dispatch_id` and `schedule_id`. | `success` | No action needed. |
| `400 Bad Request` | The `canvas_id` is missing or isn't a string. | `canvas_id must be a string of the Canvas api identifier` | Pass a valid `canvas_id` string. Find it with the [Export Canvas list endpoint]({{site.baseurl}}/api/endpoints/export/canvas/get_canvases/). |
| `400 Bad Request` | The Canvas can't be triggered by the API. | `Canvas must be triggerable by API` | Set the Canvas entry to **API-triggered** delivery, then retry. |
| `400 Bad Request` | The `time` is missing, malformed, or in the past. | `'time' must be an ISO 8601 time in UTC that has not passed` | Pass `schedule.time` as a future ISO 8601 UTC datetime. |
| `400 Bad Request` | For local or optimal delivery, the `time` is in the past. | `'time' must be an ISO 8601 time in UTC that is not in the past` | Pass a future `schedule.time` for local or optimal delivery. |
| `400 Bad Request` | Both `in_local_time` and `at_optimal_time` are `true`. | `only one of 'in_local_time' and 'at_optimal_time' can be true` | Set only one of `in_local_time` or `at_optimal_time`. |
| `400 Bad Request` | The `recipients` value isn't an array of objects that each include a user identifier. | `'recipients' must be an array of objects, each containing a user identifier and optional 'context'` | Pass `recipients` as an array of objects, each with an `external_user_id`, `user_alias`, or `braze_id`. |
| `400 Bad Request` | The `recipients` array is empty. | `when including recipients, there must be at least one recipient specified` | Include at least one recipient, or use `broadcast`. |
| `400 Bad Request` | The `recipients` array exceeds the maximum allowed length. | `Max input length exceeded.` | Send fewer recipients per request (up to the API-triggered recipient limit). |
| `400 Bad Request` | The `broadcast` value isn't a boolean. | `Broadcast must be a boolean` | Pass `broadcast` as `true` or `false`. |
| `400 Bad Request` | `broadcast` is `true` but `recipients` or `external_user_ids` were also provided. | `Cannot send messages to recipients with the broadcast parameter set to true. Broadcast is only available when sending to a Segment or Connected Audience` | Set `broadcast` to `true` only when sending to a segment or connected audience, without explicit recipients. |
| `400 Bad Request` | No recipients were provided and `broadcast` isn't `true`. | `Must provide recipients unless the broadcast parameter is true` | Include `recipients`, or set `broadcast` to `true`. |
| `400 Bad Request` | The `context` value isn't an object. | `'context' must be an object` | Pass `context` as an object. |
| `400 Bad Request` | The `context` payload is too large. | `'context' is too large` | Reduce the size of `context` below your workspace's API trigger properties limit. |
| `400 Bad Request` | `segment_id` isn't supported on this endpoint. | `'segment_id' is not supported on this endpoint` | Remove `segment_id` from the request. |
| `401 Unauthorized` | The REST API key is missing, malformed, or sent to the wrong REST endpoint. | `Invalid API key` | Send the key as `Authorization: Bearer YOUR_REST_API_KEY` to the correct [REST endpoint]({{site.baseurl}}/api/basics/#endpoints). For more causes, see [Errors and responses]({{site.baseurl}}/api/errors/#fatal-errors). |
| `403 Access Denied` | The REST API key doesn't have the required permission. | `Access Denied` | Use a REST API key that has the `canvas.trigger.schedule.create` permission. |
| `429 Rate Limited` | You exceeded the rate limit for this endpoint. | `Over rate limit` | Slow your request rate and retry with exponential backoff. See [API rate limits]({{site.baseurl}}/api/api_limits/). |
| `5XX Internal Server Error` | An unexpected error occurred on the Braze server. | `Internal Server Error` | Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/). |
operationId: post_canvas_trigger_schedule_create_post_schedule_triggered_canvases
tags:
- Messaging
responses:
'201':
description: The request was accepted. The response includes a `dispatch_id` and `schedule_id`.
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleTriggeredCanvasesResponse'
'400':
description: |-
Bad Request. Causes include:
- `canvas_id must be a string of the Canvas api identifier` — The `canvas_id` is missing or isn't a string.
- `Canvas must be triggerable by API` — The Canvas can't be triggered by the API.
- `'time' must be an ISO 8601 time in UTC that has not passed` — The `time` is missing, malformed, or in the past.
- `'time' must be an ISO 8601 time in UTC that is not in the past` — For local or optimal delivery, the `time` is in the past.
- `only one of 'in_local_time' and 'at_optimal_time' can be true` — Both `in_local_time` and `at_optimal_time` are `true`.
- `'recipients' must be an array of objects, each containing a user identifier and optional 'context'` — The `recipients` value isn't an array of objects that each include a user identifier.
- `when including recipients, there must be at least one recipient specified` — The `recipients` array is empty.
- `Max input length exceeded.` — The `recipients` array exceeds the maximum allowed length.
- `Broadcast must be a boolean` — The `broadcast` value isn't a boolean.
- `Cannot send messages to recipients with the broadcast parameter set to true. Broadcast is only available when sending to a Segment or Connected Audience` — `broadcast` is `true` but `recipients` or `external_user_ids` were also provided.
- `Must provide recipients unless the broadcast parameter is true` — No recipients were provided and `broadcast` isn't `true`.
- `'context' must be an object` — The `context` value isn't an object.
- `'context' is too large` — The `context` payload is too large.
- `'segment_id' is not supported on this endpoint` — `segment_id` isn't supported on this endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: The REST API key is missing, malformed, or sent to the wrong REST endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: The REST API key doesn't have the required permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: You exceeded the rate limit for this endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'5XX':
description: An unexpected error occurred on the Braze server.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
canvas_id:
type: string
description: See Canvas identifier.
recipients:
type: array
items:
type: object
description: See recipients object.
audience:
type: object
description: See connected audience.
broadcast:
type: boolean
description: 'You must set `broadcast` to true when sending a message to an entire segment that a campaign or Canvas targets. This parameter defaults to false (as of August 31, 2017). If `broadcast` is set to true, a `recipients` list cannot be included. However, use caution when setting `broadcast: true`, as unintentionally setting this flag may cause you to send your message to a larger than expected audience.'
context:
type: object
description: Personalization key-value pairs for all users in this send. See Canvas context object.
schedule:
type: object
description: See schedule object.
required:
- canvas_id
- schedule
examples:
example_request:
summary: Example request
value:
canvas_id: canvas_identifier
recipients:
- user_alias: example_alias
external_user_id: external_user_identifier
context: {}
audience:
AND:
- custom_attribute:
custom_attribute_name: eye_color
comparison: equals
value: blue
- custom_attribute:
custom_attribute_name: favorite_foods
comparison: includes_value
value: pizza
- OR:
- custom_attribute:
custom_attribute_name: last_purchase_time
comparison: less_than_x_days_ago
value: 2
- push_subscription_status:
comparison: is
value: opted_in
- email_subscription_status:
comparison: is_not
value: subscribed
- last_used_app:
comparison: after
value: '2019-07-22T13:17:55+0000'
broadcast: false
context: {}
schedule:
time: ''
in_local_time: false
at_optimal_time: false
components:
schemas:
ScheduleTriggeredCanvasesResponse:
type: object
properties:
dispatch_id:
type: string
schedule_id:
type: string
message:
type: string
ErrorResponse:
type: object
properties:
message:
type: string
description: The error message describing why the request failed.
errors:
type: array
description: Non-fatal errors encountered while processing the request. Data unaffected by these errors is still processed.
items:
type: object
properties:
type:
type: string
description: The error type.
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: REST API key