Set Notification Preferences

Changes how the signed-in person is notified: per channel (in-app, email, Slack), optionally per workspace and event kind, instant, daily digest or off.

Updated

PUT
/v1/notification-preferences
curl -X PUT "https://api.orshot.com/v1/notification-preferences" \
  -H "Authorization: Bearer <ORSHOT_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": [],
    "timezone": "<TIMEZONE>"
  }'

Changes how the signed-in person is notified: per channel (in-app, email, Slack), optionally per workspace and event kind, instant, daily digest or off. Also sets their time zone for the digest. A third-party app changes only the workspaces it was given (workspaceId is required) and can't change the time zone.

Endpoint#

Endpoint
https://api.orshot.com/v1/notification-preferences

Request Body#

ParameterTypeRequiredDescription
preferencesArrayNoUp to 200 items.
timezoneStringNoIANA time zone for the daily digest, e.g. Europe/Berlin. Can be null.

preferences[]#

ParameterTypeRequiredDescription
workspaceIdIntegerNonull applies to all your workspaces. Can be null.
eventKindStringYes"*" for every event. One of *, approval.item.added, approval.item.moved, approval.item.removed, approval.decision.created, approval.decision.revoked, approval.edit.started, approval.override.used, approval.render.blocked, template.edited, template.render_gate.changed, comment.created, comment.resolved, comment.hidden, approval_flow.created, approval_flow.updated, approval_flow.archived, approval_flow.duplicated, workspace_group.updated.
channelStringYesOne of inapp, email, slack.
modeStringYesOne of instant, digest, off.

Headers#

HeaderRequiredDescription
AuthorizationYesBearer <API key or OAuth token>
X-Orshot-User-IdWith an API keyThe user id of the owner, admin or member this call is for. OAuth tokens don't send it. See Acting for a Team Member below.
X-Session-IdNoGroups the calls of one agent or MCP session in the activity history.

Acting for a Team Member#

This acts for one person. With an API key, send X-Orshot-User-Id with the user id of an owner, admin or member of the workspace: the answer is theirs, as their own OAuth token would get it, within the key's workspace. It changes something of theirs, so the key needs move access as well: a key with only read gets 403 enterprise_api_required. Without the header, API keys get 403 permission_denied, code approval.person_required. See acting for a team member.

Request#

JavaScript
await fetch("https://api.orshot.com/v1/notification-preferences", {
  method: "PUT",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <ORSHOT_OAUTH_TOKEN>",
  },
  body: JSON.stringify({
    "preferences": [
      {
        "eventKind": "*",
        "channel": "email",
        "mode": "digest"
      }
    ],
    "timezone": "Europe/Berlin"
  }),
});
JSON
{
  "preferences": [
    {
      "workspaceId": null,
      "eventKind": "*",
      "channel": "email",
      "mode": "digest"
    }
  ],
  "timezone": "Europe/Berlin",
  "warnings": []
}

Response Fields#

Responds 200 with:

FieldTypeDescription
preferencesArrayList of NotificationPreference, fields below.
preferences[].workspaceIdIntegerCan be null.
preferences[].eventKindString"*" or an event kind.
preferences[].channelStringOne of inapp, email, slack.
preferences[].modeStringOne of instant, digest, off.
timezoneStringCan be null.
warningsArrayNon-blocking notices, each { code, message? }, for example no_approver. Always present on writes, empty when there is nothing to say.

Error Responses#

Every error has the same body: error, code, message and helpUrl, plus the fields that apply (required, role, context, blockers, violations, issues, current). Branch on error; code is more specific. See the error reference.

Status CodeErrorDescription
401oauth_token_invalidThe OAuth token is invalid, expired or revoked.
403api_key_missingNo Authorization: Bearer header.
403permission_deniedYou don't have access to do this. Ask an owner or admin. code names the capability, for example approval.item.decide_denied; required and role say what was missing. With code: insufficient_scope: the OAuth token lacks workspace:approvals:write. API keys without X-Orshot-User-Id get approval.person_required: this acts for one person. With code: approval.member_header_not_member: X-Orshot-User-Id names someone who isn't an owner, admin or member of the workspace now. With code: approval.member_header_not_allowed: an OAuth token sent X-Orshot-User-Id.
403plan_requiredThe workspace's plan doesn't include Approvals, or doesn't include this part of it.
403enterprise_api_requiredApprovals through third-party apps need an Enterprise plan. Contact hi@orshot.com to turn it on.
404not_foundThis doesn't exist or isn't available to you. Reviewers get this, never 403, for flows and templates outside their access.
422validation_failedSome fields aren't valid: the fields listed in issues. issues lists each field with a path and a reason.
422validation_failedWith code: approval.member_header_invalid: X-Orshot-User-Id isn't a user id.
429rate_limit_exceededMore than 120 approvals requests in a minute from one person or key. Wait for Retry-After.
503approvals_unavailableApprovals aren't available right now. Try again in a moment. Also returned while approvals are not switched on for the API.
Was this page helpful?

Ready to automate?

Start rendering images, PDFs and videos from your templates in under 2 minutes. Free plan, no credit card.

Get your API key
  • Image, PDF and video generation via API
  • Visual editor with AI and smart layouts
  • Zapier, Make, MCP and 50+ integrations
  • White-label embed for your own app
  • 100 free credits a month, no credit card required