Update the alert settings · Ownrecord docs

Sets whether high alerts are emailed in the mode of the request: immediate (the default) emails them to the members whose role handles them as they are raised; off keeps them in the inbox (and the Slack channels that take high alerts). Critical alerts are always emailed. Pass expectedVersion (the settings' version, 0 while the defaults apply) to refuse the change if someone else changed the settings meanwhile.

Needs org:write (owners and admins).

At a glance

REST: PATCH /api/v1/alert_settings
MCP tool: alert_settings_update
Operation ID: alert_settings.update
Scope: Organization
Permission: org:write
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key optional
Modes: Test and live
Authentication: API key with the org:write scope
Since: M7

Request

Body

A JSON object (Content-Type: application/json):

Field	Type	Required
`email`	object	Yes
`email.high`	one of `immediate`, `off`	Yes
`expectedVersion`	integer (at least 0)	No

Response

200 OK with a JSON object:

Field	Type	Description
`object`	`"alert_settings"`
`livemode`	boolean
`email`	object
`email.high`	one of `immediate`, `off`
`slackChannels`	array of object
`slackChannels[].id`	`sec_…` ID
`slackChannels[].object`	`"slack_channel"`
`slackChannels[].name`	string
`slackChannels[].urlHint`	string
`slackChannels[].minSeverity`	one of `high`, `critical`
`slackChannels[].createdAt`	date-time
`slackChannels[].createdBy`	string
`slackChannels[].lastTest`	object or null
`updatedAt`	date-time or null
`version`	integer (at least 0)

Examples

Keep high alerts out of email

HTTP

PATCH /api/v1/alert_settings
Authorization: Bearer or_test_…
Content-Type: application/json

{
  "email": {
    "high": "off"
  },
  "expectedVersion": 2
}

Response (200):

JSON

{
  "object": "alert_settings",
  "livemode": true,
  "email": {
    "high": "off"
  },
  "slackChannels": [
    {
      "id": "sec_01m4ttwd3veh9apbewxheq5xad",
      "object": "slack_channel",
      "name": "#tax-alerts",
      "urlHint": "hooks.slack.com …x7Qa",
      "minSeverity": "high",
      "createdAt": "2026-10-13T12:00:00.000Z",
      "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
      "lastTest": null
    }
  ],
  "updatedAt": "2026-10-13T12:00:00.000Z",
  "version": 3
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	`email.high` isn't `immediate` or `off`.	Fix the fields listed in `details.issues` and send the request again.
`version_conflict`	409	The settings changed since `expectedVersion`; reload and retry.	Fetch the object again and retry the change.
`permission_denied`	403	You can't change this organization's settings.	Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, resource_not_found, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Body#

Response#

Examples#

Keep high alerts out of email#

Errors#