ReferenceMessages
Broadcasts
9 operations. Send Authorization: Bearer $PASSBOOK_KEY. Markdown
GET
/api/v1/broadcastsmessages:writeSDK pb.broadcasts.list
Query
cursorstring · max 512
limitinteger · ≥ 1 · ≤ 200
state"draft" | "scheduled" | "sending" | "sent" | "partial" | "failed" | "cancelled"
origin"manual" | "rule"
Returns
200
Errors
| Code | Status | Fix |
|---|---|---|
| BROADCAST_INVALID_INPUT | Fix the values named in issues; GET /api/v1/templates/{id}/input-schema lists the allowed inputs. | |
| BROADCAST_NOT_CANCELLABLE | Check the state with GET /api/v1/broadcasts/{id} and cancel only a draft or scheduled message. | |
| BROADCAST_NOT_DRAFT | Send only drafts, or create a new message with POST /api/v1/broadcasts. | |
| BROADCAST_NOT_EDITABLE | Create a new message with POST /api/v1/broadcasts instead. | |
| BROADCAST_NOT_FOUND | Check the id with GET /api/v1/broadcasts. | |
| BROADCAST_NOT_RETRYABLE | Check the state with GET /api/v1/broadcasts/{id} and retry only a failed or cancelled message. | |
| BROADCAST_ORG | Remove the organization change and update the message in its own organization. | |
| BROADCAST_PAST | Set at to a future time. | |
| BROADCAST_TOO_FAR | Set at to a time within the next year. | |
| BROADCAST_UNKNOWN_INPUT | Use only input names from GET /api/v1/templates/{id}/input-schema. | |
| FORBIDDEN | Use a key with the scope the operation lists, or ask an org admin. | |
| INVALID_API_KEY | Create a new key in the console and update PASSBOOK_KEY. | |
| MESSAGING_UNSUPPORTED | Use a template that defines a message field, or add one to it. | |
| MISSING_SCOPE | Create a key with the scope the operation lists under security. | |
| ORG_NOT_FOUND | Check orgId with GET /api/v1/orgs. | |
| PASS_CONFLICT | Fetch the pass with GET /api/v1/passes/{id} and send the request again. | |
| RATE_LIMITED | Wait for Retry-After seconds, then retry. Back off on repeats. | |
| UNAUTHENTICATED | Send Authorization: Bearer $PASSBOOK_KEY. | |
| VALIDATION | Fix each field in issues and resend. |
POST
/api/v1/broadcastsmessages:writeSDK pb.broadcasts.create
Body
orgIdstring · max 64Required
kind"message" | "change"Required
targetobjectRequired
templateIdsstring · max 64[]Required
onDeviceboolean
holderState"unassigned" | "waiting" | "owned"
qstring · max 200
scanobject | object
matchobject | object | object[]
patchobjectRequired
namestring · max 80
notifyboolean
send"draft" | "now" | "schedule"
atinteger · ≥ 0
clearAfterinteger | null · ≥ 60000 · ≤ 31622400000
Returns
201
Errors
| Code | Status | Fix |
|---|---|---|
| BROADCAST_INVALID_INPUT | Fix the values named in issues; GET /api/v1/templates/{id}/input-schema lists the allowed inputs. | |
| BROADCAST_NOT_CANCELLABLE | Check the state with GET /api/v1/broadcasts/{id} and cancel only a draft or scheduled message. | |
| BROADCAST_NOT_DRAFT | Send only drafts, or create a new message with POST /api/v1/broadcasts. | |
| BROADCAST_NOT_EDITABLE | Create a new message with POST /api/v1/broadcasts instead. | |
| BROADCAST_NOT_FOUND | Check the id with GET /api/v1/broadcasts. | |
| BROADCAST_NOT_RETRYABLE | Check the state with GET /api/v1/broadcasts/{id} and retry only a failed or cancelled message. | |
| BROADCAST_ORG | Remove the organization change and update the message in its own organization. | |
| BROADCAST_PAST | Set at to a future time. | |
| BROADCAST_TOO_FAR | Set at to a time within the next year. | |
| BROADCAST_UNKNOWN_INPUT | Use only input names from GET /api/v1/templates/{id}/input-schema. | |
| FORBIDDEN | Use a key with the scope the operation lists, or ask an org admin. | |
| INVALID_API_KEY | Create a new key in the console and update PASSBOOK_KEY. | |
| MESSAGING_UNSUPPORTED | Use a template that defines a message field, or add one to it. | |
| MISSING_SCOPE | Create a key with the scope the operation lists under security. | |
| ORG_NOT_FOUND | Check orgId with GET /api/v1/orgs. | |
| PASS_CONFLICT | Fetch the pass with GET /api/v1/passes/{id} and send the request again. | |
| RATE_LIMITED | Wait for Retry-After seconds, then retry. Back off on repeats. | |
| UNAUTHENTICATED | Send Authorization: Bearer $PASSBOOK_KEY. | |
| VALIDATION | Fix each field in issues and resend. |
POST
/api/v1/broadcasts/previewmessages:writeSDK pb.broadcasts.countRecipients
Body
orgIdstring · max 64Required
targetobjectRequired
templateIdsstring · max 64[]Required
onDeviceboolean
holderState"unassigned" | "waiting" | "owned"
qstring · max 200
scanobject | object
matchobject | object | object[]
Returns
200
Errors
| Code | Status | Fix |
|---|---|---|
| BROADCAST_INVALID_INPUT | Fix the values named in issues; GET /api/v1/templates/{id}/input-schema lists the allowed inputs. | |
| BROADCAST_NOT_CANCELLABLE | Check the state with GET /api/v1/broadcasts/{id} and cancel only a draft or scheduled message. | |
| BROADCAST_NOT_DRAFT | Send only drafts, or create a new message with POST /api/v1/broadcasts. | |
| BROADCAST_NOT_EDITABLE | Create a new message with POST /api/v1/broadcasts instead. | |
| BROADCAST_NOT_FOUND | Check the id with GET /api/v1/broadcasts. | |
| BROADCAST_NOT_RETRYABLE | Check the state with GET /api/v1/broadcasts/{id} and retry only a failed or cancelled message. | |
| BROADCAST_ORG | Remove the organization change and update the message in its own organization. | |
| BROADCAST_PAST | Set at to a future time. | |
| BROADCAST_TOO_FAR | Set at to a time within the next year. | |
| BROADCAST_UNKNOWN_INPUT | Use only input names from GET /api/v1/templates/{id}/input-schema. | |
| FORBIDDEN | Use a key with the scope the operation lists, or ask an org admin. | |
| INVALID_API_KEY | Create a new key in the console and update PASSBOOK_KEY. | |
| MESSAGING_UNSUPPORTED | Use a template that defines a message field, or add one to it. | |
| MISSING_SCOPE | Create a key with the scope the operation lists under security. | |
| ORG_NOT_FOUND | Check orgId with GET /api/v1/orgs. | |
| PASS_CONFLICT | Fetch the pass with GET /api/v1/passes/{id} and send the request again. | |
| RATE_LIMITED | Wait for Retry-After seconds, then retry. Back off on repeats. | |
| UNAUTHENTICATED | Send Authorization: Bearer $PASSBOOK_KEY. | |
| VALIDATION | Fix each field in issues and resend. |
GET
/api/v1/broadcasts/{id}messages:writeSDK pb.broadcasts.retrieve
Path
idstring · max 64Required
Returns
200
Errors
| Code | Status | Fix |
|---|---|---|
| BROADCAST_INVALID_INPUT | Fix the values named in issues; GET /api/v1/templates/{id}/input-schema lists the allowed inputs. | |
| BROADCAST_NOT_CANCELLABLE | Check the state with GET /api/v1/broadcasts/{id} and cancel only a draft or scheduled message. | |
| BROADCAST_NOT_DRAFT | Send only drafts, or create a new message with POST /api/v1/broadcasts. | |
| BROADCAST_NOT_EDITABLE | Create a new message with POST /api/v1/broadcasts instead. | |
| BROADCAST_NOT_FOUND | Check the id with GET /api/v1/broadcasts. | |
| BROADCAST_NOT_RETRYABLE | Check the state with GET /api/v1/broadcasts/{id} and retry only a failed or cancelled message. | |
| BROADCAST_ORG | Remove the organization change and update the message in its own organization. | |
| BROADCAST_PAST | Set at to a future time. | |
| BROADCAST_TOO_FAR | Set at to a time within the next year. | |
| BROADCAST_UNKNOWN_INPUT | Use only input names from GET /api/v1/templates/{id}/input-schema. | |
| FORBIDDEN | Use a key with the scope the operation lists, or ask an org admin. | |
| INVALID_API_KEY | Create a new key in the console and update PASSBOOK_KEY. | |
| MESSAGING_UNSUPPORTED | Use a template that defines a message field, or add one to it. | |
| MISSING_SCOPE | Create a key with the scope the operation lists under security. | |
| NOT_FOUND | Check the id, and that the key's mode (test or live) matches the object. | |
| ORG_NOT_FOUND | Check orgId with GET /api/v1/orgs. | |
| PASS_CONFLICT | Fetch the pass with GET /api/v1/passes/{id} and send the request again. | |
| RATE_LIMITED | Wait for Retry-After seconds, then retry. Back off on repeats. | |
| UNAUTHENTICATED | Send Authorization: Bearer $PASSBOOK_KEY. | |
| VALIDATION | Fix each field in issues and resend. |
PATCH
/api/v1/broadcasts/{id}messages:writeSDK pb.broadcasts.update
Path
idstring · max 64Required
Body
orgIdstring · max 64Required
kind"message" | "change"Required
targetobjectRequired
templateIdsstring · max 64[]Required
onDeviceboolean
holderState"unassigned" | "waiting" | "owned"
qstring · max 200
scanobject | object
matchobject | object | object[]
patchobjectRequired
namestring · max 80
notifyboolean
send"draft" | "now" | "schedule"
atinteger · ≥ 0
clearAfterinteger | null · ≥ 60000 · ≤ 31622400000
Returns
200
Errors
| Code | Status | Fix |
|---|---|---|
| BROADCAST_INVALID_INPUT | Fix the values named in issues; GET /api/v1/templates/{id}/input-schema lists the allowed inputs. | |
| BROADCAST_NOT_CANCELLABLE | Check the state with GET /api/v1/broadcasts/{id} and cancel only a draft or scheduled message. | |
| BROADCAST_NOT_DRAFT | Send only drafts, or create a new message with POST /api/v1/broadcasts. | |
| BROADCAST_NOT_EDITABLE | Create a new message with POST /api/v1/broadcasts instead. | |
| BROADCAST_NOT_FOUND | Check the id with GET /api/v1/broadcasts. | |
| BROADCAST_NOT_RETRYABLE | Check the state with GET /api/v1/broadcasts/{id} and retry only a failed or cancelled message. | |
| BROADCAST_ORG | Remove the organization change and update the message in its own organization. | |
| BROADCAST_PAST | Set at to a future time. | |
| BROADCAST_TOO_FAR | Set at to a time within the next year. | |
| BROADCAST_UNKNOWN_INPUT | Use only input names from GET /api/v1/templates/{id}/input-schema. | |
| FORBIDDEN | Use a key with the scope the operation lists, or ask an org admin. | |
| INVALID_API_KEY | Create a new key in the console and update PASSBOOK_KEY. | |
| MESSAGING_UNSUPPORTED | Use a template that defines a message field, or add one to it. | |
| MISSING_SCOPE | Create a key with the scope the operation lists under security. | |
| NOT_FOUND | Check the id, and that the key's mode (test or live) matches the object. | |
| ORG_NOT_FOUND | Check orgId with GET /api/v1/orgs. | |
| PASS_CONFLICT | Fetch the pass with GET /api/v1/passes/{id} and send the request again. | |
| RATE_LIMITED | Wait for Retry-After seconds, then retry. Back off on repeats. | |
| UNAUTHENTICATED | Send Authorization: Bearer $PASSBOOK_KEY. | |
| VALIDATION | Fix each field in issues and resend. |
POST
/api/v1/broadcasts/{id}/sendmessages:writeSDK pb.broadcasts.send
Path
idstring · max 64Required
Body
atinteger · ≥ 0
Returns
200
Errors
| Code | Status | Fix |
|---|---|---|
| BROADCAST_INVALID_INPUT | Fix the values named in issues; GET /api/v1/templates/{id}/input-schema lists the allowed inputs. | |
| BROADCAST_NOT_CANCELLABLE | Check the state with GET /api/v1/broadcasts/{id} and cancel only a draft or scheduled message. | |
| BROADCAST_NOT_DRAFT | Send only drafts, or create a new message with POST /api/v1/broadcasts. | |
| BROADCAST_NOT_EDITABLE | Create a new message with POST /api/v1/broadcasts instead. | |
| BROADCAST_NOT_FOUND | Check the id with GET /api/v1/broadcasts. | |
| BROADCAST_NOT_RETRYABLE | Check the state with GET /api/v1/broadcasts/{id} and retry only a failed or cancelled message. | |
| BROADCAST_ORG | Remove the organization change and update the message in its own organization. | |
| BROADCAST_PAST | Set at to a future time. | |
| BROADCAST_TOO_FAR | Set at to a time within the next year. | |
| BROADCAST_UNKNOWN_INPUT | Use only input names from GET /api/v1/templates/{id}/input-schema. | |
| FORBIDDEN | Use a key with the scope the operation lists, or ask an org admin. | |
| INVALID_API_KEY | Create a new key in the console and update PASSBOOK_KEY. | |
| MESSAGING_UNSUPPORTED | Use a template that defines a message field, or add one to it. | |
| MISSING_SCOPE | Create a key with the scope the operation lists under security. | |
| NOT_FOUND | Check the id, and that the key's mode (test or live) matches the object. | |
| ORG_NOT_FOUND | Check orgId with GET /api/v1/orgs. | |
| PASS_CONFLICT | Fetch the pass with GET /api/v1/passes/{id} and send the request again. | |
| RATE_LIMITED | Wait for Retry-After seconds, then retry. Back off on repeats. | |
| UNAUTHENTICATED | Send Authorization: Bearer $PASSBOOK_KEY. | |
| VALIDATION | Fix each field in issues and resend. |
POST
/api/v1/broadcasts/{id}/cancelmessages:writeSDK pb.broadcasts.cancel
Path
idstring · max 64Required
Returns
200
Errors
| Code | Status | Fix |
|---|---|---|
| BROADCAST_INVALID_INPUT | Fix the values named in issues; GET /api/v1/templates/{id}/input-schema lists the allowed inputs. | |
| BROADCAST_NOT_CANCELLABLE | Check the state with GET /api/v1/broadcasts/{id} and cancel only a draft or scheduled message. | |
| BROADCAST_NOT_DRAFT | Send only drafts, or create a new message with POST /api/v1/broadcasts. | |
| BROADCAST_NOT_EDITABLE | Create a new message with POST /api/v1/broadcasts instead. | |
| BROADCAST_NOT_FOUND | Check the id with GET /api/v1/broadcasts. | |
| BROADCAST_NOT_RETRYABLE | Check the state with GET /api/v1/broadcasts/{id} and retry only a failed or cancelled message. | |
| BROADCAST_ORG | Remove the organization change and update the message in its own organization. | |
| BROADCAST_PAST | Set at to a future time. | |
| BROADCAST_TOO_FAR | Set at to a time within the next year. | |
| BROADCAST_UNKNOWN_INPUT | Use only input names from GET /api/v1/templates/{id}/input-schema. | |
| FORBIDDEN | Use a key with the scope the operation lists, or ask an org admin. | |
| INVALID_API_KEY | Create a new key in the console and update PASSBOOK_KEY. | |
| MESSAGING_UNSUPPORTED | Use a template that defines a message field, or add one to it. | |
| MISSING_SCOPE | Create a key with the scope the operation lists under security. | |
| NOT_FOUND | Check the id, and that the key's mode (test or live) matches the object. | |
| ORG_NOT_FOUND | Check orgId with GET /api/v1/orgs. | |
| PASS_CONFLICT | Fetch the pass with GET /api/v1/passes/{id} and send the request again. | |
| RATE_LIMITED | Wait for Retry-After seconds, then retry. Back off on repeats. | |
| UNAUTHENTICATED | Send Authorization: Bearer $PASSBOOK_KEY. | |
| VALIDATION | Fix each field in issues and resend. |
POST
/api/v1/broadcasts/{id}/retrymessages:writeSDK pb.broadcasts.retry
Path
idstring · max 64Required
Returns
201
Errors
| Code | Status | Fix |
|---|---|---|
| BROADCAST_INVALID_INPUT | Fix the values named in issues; GET /api/v1/templates/{id}/input-schema lists the allowed inputs. | |
| BROADCAST_NOT_CANCELLABLE | Check the state with GET /api/v1/broadcasts/{id} and cancel only a draft or scheduled message. | |
| BROADCAST_NOT_DRAFT | Send only drafts, or create a new message with POST /api/v1/broadcasts. | |
| BROADCAST_NOT_EDITABLE | Create a new message with POST /api/v1/broadcasts instead. | |
| BROADCAST_NOT_FOUND | Check the id with GET /api/v1/broadcasts. | |
| BROADCAST_NOT_RETRYABLE | Check the state with GET /api/v1/broadcasts/{id} and retry only a failed or cancelled message. | |
| BROADCAST_ORG | Remove the organization change and update the message in its own organization. | |
| BROADCAST_PAST | Set at to a future time. | |
| BROADCAST_TOO_FAR | Set at to a time within the next year. | |
| BROADCAST_UNKNOWN_INPUT | Use only input names from GET /api/v1/templates/{id}/input-schema. | |
| FORBIDDEN | Use a key with the scope the operation lists, or ask an org admin. | |
| INVALID_API_KEY | Create a new key in the console and update PASSBOOK_KEY. | |
| MESSAGING_UNSUPPORTED | Use a template that defines a message field, or add one to it. | |
| MISSING_SCOPE | Create a key with the scope the operation lists under security. | |
| NOT_FOUND | Check the id, and that the key's mode (test or live) matches the object. | |
| ORG_NOT_FOUND | Check orgId with GET /api/v1/orgs. | |
| PASS_CONFLICT | Fetch the pass with GET /api/v1/passes/{id} and send the request again. | |
| RATE_LIMITED | Wait for Retry-After seconds, then retry. Back off on repeats. | |
| UNAUTHENTICATED | Send Authorization: Bearer $PASSBOOK_KEY. | |
| VALIDATION | Fix each field in issues and resend. |
Recipients
GET
/api/v1/broadcasts/{id}/itemsmessages:writeSDK pb.broadcasts.recipients.list
Path
idstring · max 64Required
Query
cursorstring · max 512
limitinteger · ≥ 1 · ≤ 200
outcome"updated" | "unchanged" | "failed"
Returns
200
Errors
| Code | Status | Fix |
|---|---|---|
| BROADCAST_INVALID_INPUT | Fix the values named in issues; GET /api/v1/templates/{id}/input-schema lists the allowed inputs. | |
| BROADCAST_NOT_CANCELLABLE | Check the state with GET /api/v1/broadcasts/{id} and cancel only a draft or scheduled message. | |
| BROADCAST_NOT_DRAFT | Send only drafts, or create a new message with POST /api/v1/broadcasts. | |
| BROADCAST_NOT_EDITABLE | Create a new message with POST /api/v1/broadcasts instead. | |
| BROADCAST_NOT_FOUND | Check the id with GET /api/v1/broadcasts. | |
| BROADCAST_NOT_RETRYABLE | Check the state with GET /api/v1/broadcasts/{id} and retry only a failed or cancelled message. | |
| BROADCAST_ORG | Remove the organization change and update the message in its own organization. | |
| BROADCAST_PAST | Set at to a future time. | |
| BROADCAST_TOO_FAR | Set at to a time within the next year. | |
| BROADCAST_UNKNOWN_INPUT | Use only input names from GET /api/v1/templates/{id}/input-schema. | |
| FORBIDDEN | Use a key with the scope the operation lists, or ask an org admin. | |
| INVALID_API_KEY | Create a new key in the console and update PASSBOOK_KEY. | |
| MESSAGING_UNSUPPORTED | Use a template that defines a message field, or add one to it. | |
| MISSING_SCOPE | Create a key with the scope the operation lists under security. | |
| NOT_FOUND | Check the id, and that the key's mode (test or live) matches the object. | |
| ORG_NOT_FOUND | Check orgId with GET /api/v1/orgs. | |
| PASS_CONFLICT | Fetch the pass with GET /api/v1/passes/{id} and send the request again. | |
| RATE_LIMITED | Wait for Retry-After seconds, then retry. Back off on repeats. | |
| UNAUTHENTICATED | Send Authorization: Bearer $PASSBOOK_KEY. | |
| VALIDATION | Fix each field in issues and resend. |