Worked sequences

The operation list below documents each endpoint with its parameters, but the push lifecycle — register a device → send → ack engagement → schedule — spans several calls, and the response bodies are what you branch on. These sequences show each call with the body it returns. The end-to-end workflow guide is Push integration; this section adds the per-operation worked bodies the operations list below doesn’t carry. Copy a request as written, substitute your own ids, and compare the response envelope. Errors follow Devotel Orbit’s { error, meta } envelope.

Sequence 1 — register a device token

A device becomes reachable once it registers a token against an Orbit user. The same token upserts on re-register (idempotent), and passing app_install_id retires the previous token on a reinstall.

curl -X POST https://api.orbit.devotel.io/api/v1/push/device-tokens \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_8a1f2c",
    "platform": "ios",
    "token": "9f3a1c5d7b2e0486aab2f8c1d3e5b7a9c2d4e6f8a1b3c5d7e9f1b3d5f7a9c1e3f5",
    "app_install_id": "install_abc123"
  }'

201

{
  "data": {
    "id": "deviceToken_7e2c1b",
    "user_id": "user_8a1f2c",
    "platform": "ios",
    "token": "9f3a1c5d7b2e0486aab2f8c1d3e5b7a9c2d4e6f8a1b3c5d7e9f1b3d5f7a9c1e3f5",
    "app_id": null,
    "app_install_id": "install_abc123",
    "device_id": null,
    "notification_channel": null
  },
  "meta": {
    "request_id": "req_push_reg",
    "timestamp": "2026-08-30T12:00:00.000Z"
  }
}

Save the returned id — you can target this device directly with device_token_ids on send. For platform: "web", supply the subscription envelope (PushSubscription.toJSON()) instead of token. Node SDK escape hatch. The call is the same body through orbit.request when the typed SDK surface doesn’t cover a field yet:

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! })

const { data } = await orbit.request('POST', '/push/device-tokens', {
  body: {
    user_id: 'user_8a1f2c',
    platform: 'ios',
    token: '9f3a1c5d…',
    app_install_id: 'install_abc123',
  },
})
// data.id is the Orbit device-token id.

Once your first token lands, fire POST /api/v1/push/test-send to validate the whole provider credential chain against the calling user’s own devices, with no campaign stats pollution.

Sequence 2 — send with targeting

POST /api/v1/push/send takes exactly one of two targeting shapes: device_token_ids (specific devices) or user_ids (everywhere a user registered). user_ids: ["*"] broadcasts to every opted-in device, capped at 100,000 deliverable tokens. An immediate send returns 201; read notifications[] per device — a top-level success does not mean every device accepted.

curl -X POST https://api.orbit.devotel.io/api/v1/push/send \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["user_8a1f2c"],
    "title": "Your order is ready",
    "body": "Pickup is available at counter 4.",
    "data": { "order_id": "ord_91z" },
    "deep_link": "myapp://orders/ord_91z"
  }'

201

{
  "data": {
    "notifications": [
      {
        "id": "pushNotif_2",
        "deviceTokenId": "deviceToken_7e2c1b",
        "transport": "apns",
        "status": "sent"
      },
      {
        "id": "pushNotif_3",
        "deviceTokenId": "deviceToken_8b44aa",
        "transport": "fcm",
        "status": "failed",
        "error": "BadDeviceToken"
      }
    ],
    "total": 2,
    "sent": 1,
    "devices_targeted": 2
  },
  "meta": {
    "request_id": "req_push_send",
    "timestamp": "2026-08-30T12:01:00.000Z"
  }
}

Per-device status is sent (provider accepted), failed (provider rejected — read the error string; permanent failures retire the token), or skipped (frequency cap or suppression gated it). Provider-reported permanent failures retire the token automatically.

Sequence 3 — ack engagement

The client SDK (or service worker) acks delivered when the device renders the push and opened when the user taps it. The update is idempotent — the matching push.delivered / push.opened webhook fires only on the first genuine transition, so duplicate acks don’t re-emit.

curl -X POST https://api.orbit.devotel.io/api/v1/push/notifications/pushNotif_2/ack \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "event": "opened", "at": "2026-08-30T12:02:10.000Z" }'

200

{
  "data": {
    "id": "pushNotif_2",
    "event": "opened",
    "at": "2026-08-30T12:02:10.000Z"
  },
  "meta": {
    "request_id": "req_push_ack",
    "timestamp": "2026-08-30T12:02:10.000Z"
  }
}

Sequence 4 — schedule a future send

Supply send_at (ISO-8601 with offset) on /push/send to hold the payload for a future instant. The request returns 202 with a scheduled-push id; the queued row replays through the send path at send time, so targeting, caps, and suppression gates run identically.

curl -X POST https://api.orbit.devotel.io/api/v1/push/send \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["user_8a1f2c"],
    "title": "Renewal reminder",
    "body": "Your subscription renews tomorrow.",
    "send_at": "2026-09-01T09:00:00+02:00"
  }'

202

{
  "data": {
    "id": "scheduledPush_01J9ZABCDXYZ",
    "status": "scheduled",
    "send_at": "2026-09-01T07:00:00.000Z"
  },
  "meta": {
    "request_id": "req_push_sched",
    "timestamp": "2026-08-30T12:05:00.000Z"
  }
}

Read the queued row back — the full payload, attempt count, and last error are on it; cancel it with DELETE /api/v1/push/scheduled/{id} while it is still scheduled (returns 409 once the send has left):

curl https://api.orbit.devotel.io/api/v1/push/scheduled/scheduledPush_01J9ZABCDXYZ \
  -H "X-API-Key: dv_live_sk_your_key_here"

200

{
  "data": {
    "id": "scheduledPush_01J9ZABCDXYZ",
    "payload": {
      "title": "Renewal reminder",
      "body": "Your subscription renews tomorrow.",
      "user_ids": ["user_8a1f2c"]
    },
    "send_at": "2026-09-01T07:00:00.000Z",
    "status": "scheduled",
    "attempts": 0,
    "last_error": null,
    "sent_at": null,
    "created_by": "user_admin_1",
    "created_at": "2026-08-30T12:05:00.000Z",
    "updated_at": "2026-08-30T12:05:00.000Z"
  },
  "meta": {
    "request_id": "req_push_sched_get",
    "timestamp": "2026-08-30T12:05:01.000Z"
  }
}

Errors to handle. These are the tenant-owned controls you configure — run broadcasts under the deliverable-cap 422 and handle the pre-send gates:

Code	Status	Trigger
`VALIDATION_ERROR`	422	Neither `device_token_ids` nor `user_ids` supplied, or a field fails schema
`NO_DEVICE_TOKENS`	422	Target resolves to zero deliverable tokens after suppression / disabled filtering
`BROADCAST_TOO_LARGE`	422	`user_ids: ["*"]` would exceed the 100,000-recipient broadcast cap
`INVALID_PUSH_ENDPOINT`	422	On registration — the web-push `subscription.endpoint` is not publicly reachable
`NOT_FOUND`	404	Device token / scheduled push / notification id is unknown to this tenant

API Reference

All Endpoints

Worked sequences