Notifications API

Manage notification rules and read a person's inbox.

Notifications tell your team when something changes. A rule says "when a record of this type is created, updated or deleted, notify people with this title". This API manages the rules and reads a person's own inbox.

Endpoints

Method Path Permission What it does
GET /orgs/{orgId}/notification-rules notifications:read List rules
POST /orgs/{orgId}/notification-rules notifications:create Create a rule
GET /orgs/{orgId}/notification-rules/{ruleId} notifications:read Get a rule
PUT /orgs/{orgId}/notification-rules/{ruleId} notifications:create Change a rule
DELETE /orgs/{orgId}/notification-rules/{ruleId} notifications:delete Delete a rule
GET /orgs/{orgId}/notifications any member The caller's inbox
GET /orgs/{orgId}/notifications/unread-count any member How many are unread
POST /orgs/{orgId}/notifications/read/{notificationId} any member Mark one read
POST /orgs/{orgId}/notifications/read-all any member Mark all read

Rules

{
  "id": "0190f900-…",
  "name": "New large order",
  "object_type": "invoices",
  "event": "created",
  "title": "A new invoice was created",
  "audience": "all_members",
  "enabled": true,
  "created_at": "2026-10-01T08:00:00Z",
  "updated_at": "2026-10-01T08:00:00Z"
}

POST /orgs/{orgId}/notification-rules

Field Type Required Notes
name string Yes Up to 120 characters
object_type string Yes A record type key. Must exist
event string Yes created, updated or deleted
title string Yes The notification text, up to 200 characters
audience string No all_members (the only option, and the default)

Response 201 with the rule. The rule is enabled. Errors: 400 VALIDATION_ERROR (the message names the field), 403 FORBIDDEN.

PUT /orgs/{orgId}/notification-rules/{ruleId}

Send any of name, object_type, event, title, audience, enabled. Fields you leave out are unchanged. Response 200 with the rule. Set enabled to false to pause a rule without deleting it.

GET /notification-rules answers a plain array of rules. DELETE answers 204 No Content.

The inbox

The inbox always belongs to the person making the call, so it is meant for apps that act as a signed-in person. An API key belongs to a service account, not a team member, so its inbox is not useful.

{
  "data": {
    "notifications": [
      {
        "id": "0190f910-…",
        "title": "A new invoice was created",
        "object_type": "invoices",
        "record_id": "0190f0aa-…",
        "event": "created",
        "read": false,
        "created_at": "2026-10-04T09:30:00Z"
      }
    ],
    "next_cursor": "0190f910-…"
  }
}
Parameter Notes
unread true for unread only
limit Maximum 100
cursor The next_cursor of the previous page. It is null at the end

read_at is present once read. GET …/unread-count returns { "data": { "count": 3 } }. POST …/read/{id} and POST …/read-all answer 204 No Content.

  • Flows: for richer automation, such as sending a message when something happens
  • In the product: Notifications