Skip to main content

Notifications API

POST /api/v1/notifications​

Sends a push notification to one or more subscribers.

Request Body​

{
  "subscriberIds": ["user-123", "user-456"],
  "title": "Hello!",
  "body": "You have a new message.",
  "data": {
    "screen": "inbox"
  }
}

Response​

{ "id": "notif_def012", "sent": 2 }

Targets​

target.type is one of all, list (requires list_id), or segment (requires segment_id). A missing id or an unknown type returns 422 naming the field — targets are validated at creation so an unfannable job can never be published.

{ "target": { "type": "segment", "segment_id": "9f3c2a10-…" } }

Sends with a future scheduled_at are published to delivery at fire time, not at creation — cancelling before the scheduled time reliably prevents the send.

Smart channel​

channel_arbitration_mode — optional; explicit (default) or smart. Smart sends deliver each subscriber on their single top-ranked reachable channel class among the selected channels (90-day engagement ranking; personal history counts from 5 deliveries per class), with a fallback only on permanent delivery failure. Growth+ plans; smaller plans receive 403 with {"error": "feature_not_available", "feature": "smart_channel"}. See the Smart Channel guide.

On GET /api/v1/notifications/{id}, smart sends include a channel_arbitration readout: chosen[] buckets (class, source = personal | tenant | default, subscribers), suppressed_devices, rank_errors, fallback_steps, and fallback_dedup_errors. Aggregates only — there is no per-recipient decision log.

Audience filters​

Optionally narrow the audience by device or subscriber attributes with the top-level device_filters and subscriber_filters fields (Mongo-style predicates). Both are optional; when present they are ANDed.

{
  "target": { "type": "all" },
  "device_filters": {
    "os_version": { "$gte": { "major": 17, "minor": 0, "patch": 0 } }
  },
  "subscriber_filters": {
    "tier": { "$eq": "premium" }
  }
}

Supported operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists. Version-typed keys (os_version, sdk_version, app_version) take structured {major, minor, patch} operands. See the Audience Filters guide for the full reference, custom version fields, and indexing notes.