Worked push samples

The operation list below documents each endpoint with its parameters, but an integrator runs one chain: register a device token → send a push → read the delivery receipt → retire the token. These samples render that chain as ordered calls with the real response envelopes you branch on. The end-to-end guide is Push integration — client SDK setup is out of scope here; 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. Every sample shows cURL and TypeScript, matching this page’s language note. Errors follow Devotel Orbit’s { error, meta } envelope.

1. Register the device

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

cURL

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"
  }'

TypeScript

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/device-tokens', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    user_id: 'user_8a1f2c',
    platform: 'ios',
    token: '9f3a1c5d…',
    app_install_id: 'install_abc123',
  }),
})
const { data } = await res.json()
// data.id is the Orbit device-token id.

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 — the send below targets devices by it. For platform: "web", supply the subscription envelope (PushSubscription.toJSON()) instead of token. Once your first token lands, fire POST /api/v1/push/test-send to validate the provider credential chain against the calling user’s own devices.

2. Send a push

POST /api/v1/push/send takes one of two targeting shapes: device_token_ids (specific devices, as here) or user_ids (everywhere a user registered; ["*"] 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

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 '{
    "device_token_ids": ["deviceToken_7e2c1b", "deviceToken_8b44aa"],
    "title": "Your order is ready",
    "body": "Pickup is available at counter 4.",
    "data": { "order_id": "ord_91z" },
    "deep_link": "myapp://orders/ord_91z"
  }'

TypeScript

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/send', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    device_token_ids: ['deviceToken_7e2c1b', 'deviceToken_8b44aa'],
    title: 'Your order is ready',
    body: 'Pickup is available at counter 4.',
    data: { order_id: 'ord_91z' },
    deep_link: 'myapp://orders/ord_91z',
  }),
})
const { data } = await res.json()
// data.notifications is the per-device acceptance verdict.

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). Supply a future send_at (ISO-8601) to hold the send for a later instant; a scheduled send answers 202 instead, and GET /api/v1/push/scheduled/{id} reads the queued row back until DELETE cancels it while still scheduled (409 once it has left).

3. Read send status

GET /api/v1/push/notifications is the delivery log: every per-device row carries its status, the delivered_at / opened_at receipts the client SDK acks, and any provider error. Poll it (or listen for the push.delivered / push.opened webhooks) to reconcile the send above to a delivered / failed / skipped breakdown.

cURL

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

TypeScript

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/notifications', {
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
const { data } = await res.json()
// data[] — one row per device-targeted notification, newest first.

200

{
  "data": [
    {
      "id": "pushNotif_2",
      "device_token_id": "deviceToken_7e2c1b",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "delivered",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": "2026-08-30T12:01:02.000Z",
      "opened_at": null,
      "error": null,
      "platform": "ios",
      "user_id": "user_8a1f2c"
    },
    {
      "id": "pushNotif_3",
      "device_token_id": "deviceToken_8b44aa",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "failed",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": null,
      "opened_at": null,
      "error": "BadDeviceToken",
      "platform": "android",
      "user_id": "user_8a1f2c"
    }
  ],
  "meta": {
    "request_id": "req_push_list",
    "timestamp": "2026-08-30T12:03:00.000Z"
  }
}

Page the log with ?cursor=<last-row-created_at>&limit=<page-size> when it grows past one screen. A skipped row never leaves the send-time status — no receipt arrives for a gated device.

4. Errors

Two error classes show up on every integration — read the issues list on 422s and map 404s on ids your tenant has never seen. 422 — malformed registration. A device registers with an unknown platform (must be ios, android, huawei, or web), or with no token / subscription for the platform it claims:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid enum value. Expected 'ios' | 'android' | 'huawei' | 'web', received 'macos'",
    "status": 422,
    "details": {
      "issues": [
        {
          "field": "platform",
          "message": "Invalid enum value. Expected 'ios' | 'android' | 'huawei' | 'web', received 'macos'"
        }
      ]
    }
  },
  "meta": {
    "request_id": "req_push_reg_err",
    "timestamp": "2026-08-30T12:04:00.000Z"
  }
}

The same 422 shape answers a send with neither device_token_ids nor user_ids supplied. A send that resolves to zero deliverable tokens answers NO_DEVICE_TOKENS (422), and user_ids: ["*"] over the recipient cap answers BROADCAST_TOO_LARGE (422). 404 — unknown device id. A token id not known to this tenant — a deleted record, a typo, or another tenant’s id:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Device token 'deviceToken_000000' not found",
    "status": 404
  },
  "meta": {
    "request_id": "req_push_404",
    "timestamp": "2026-08-30T12:05:00.000Z"
  }
}

The identification token an OS hands you on reinstall is new every time — re-register rather than updating a stale id, and DELETE /api/v1/push/device-tokens/{id} on logout retires the current one.

5. Categories, scheduled sends and wake telemetry

Three smaller surfaces round out the chain above: notification categories (the action-button sets clients render), scheduled sends you queued with send_at, and the device wake telemetry your client reports after each push wake. Read one category.

GET /api/v1/push/categories/{id}

A category record carries the wire-bound identifier your client matches on, the optional sound and its action buttons.

{
  "data": {
    "id": "pushCategory_01J9Z8Q2XT",
    "name": "Invoice reminders",
    "identifier": "INVOICE_REMINDER",
    "sound": "chime.aiff",
    "actions": [
      {
        "identifier": "PAY_NOW",
        "title": "Pay now",
        "options": ["foreground"]
      }
    ],
    "created_at": "2026-08-20T09:15:00.000Z",
    "updated_at": "2026-08-20T09:15:00.000Z"
  },
  "meta": {
    "request_id": "req_push_cat_read",
    "timestamp": "2026-10-14T09:00:00.000Z"
  }
}

Create categories. POST /api/v1/push/categories echoes the stored record with 201. identifier must be UPPER_SNAKE_CASE and is immutable after create because clients cache it; to change one, delete and recreate. A marketing category typically carries actions; a transactional one often needs neither actions nor a sound.

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/push/categories \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Promotions",
    "identifier": "PROMO_DROP",
    "sound": "default",
    "actions": [
      { "identifier": "SHOP_NOW", "title": "Shop now", "options": ["foreground"] },
      { "identifier": "DISMISS", "title": "Dismiss", "options": [] }
    ]
  }'

TypeScript

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/categories', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Promotions',
    identifier: 'PROMO_DROP',
    sound: 'default',
    actions: [
      { identifier: 'SHOP_NOW', title: 'Shop now', options: ['foreground'] },
      { identifier: 'DISMISS', title: 'Dismiss', options: [] },
    ],
  }),
})
console.log(await res.json())

{
  "data": {
    "id": "pushCategory_01KB3MTG42",
    "name": "Promotions",
    "identifier": "PROMO_DROP",
    "sound": "default",
    "actions": [
      { "identifier": "SHOP_NOW", "title": "Shop now", "options": ["foreground"] },
      { "identifier": "DISMISS", "title": "Dismiss", "options": [] }
    ],
    "created_at": "2026-10-14T09:01:00.000Z",
    "updated_at": "2026-10-14T09:01:00.000Z"
  },
  "meta": {
    "request_id": "req_push_cat_mktg",
    "timestamp": "2026-10-14T09:01:00.000Z"
  }
}

A transactional category with no actions and no sound:

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/push/categories \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Order updates", "identifier": "ORDER_UPDATE" }'

TypeScript

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/categories', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Order updates', identifier: 'ORDER_UPDATE' }),
})
console.log(await res.json())

{
  "data": {
    "id": "pushCategory_01KB3MWQ87",
    "name": "Order updates",
    "identifier": "ORDER_UPDATE",
    "sound": null,
    "actions": [],
    "created_at": "2026-10-14T09:01:30.000Z",
    "updated_at": "2026-10-14T09:01:30.000Z"
  },
  "meta": {
    "request_id": "req_push_cat_txn",
    "timestamp": "2026-10-14T09:01:30.000Z"
  }
}

Read a queued scheduled send.

GET /api/v1/push/scheduled/{id}

Returns the full queued row, payload included, so you can inspect what will go out and at which send_at before the scheduler dispatches it.

{
  "data": {
    "id": "scheduledPush_01J9ZABCDXYZ",
    "payload": {
      "title": "Order shipped",
      "body": "Your order is on its way",
      "user_ids": ["user_123"]
    },
    "send_at": "2026-10-20T09:00:00.000Z",
    "status": "scheduled",
    "attempts": 0,
    "last_error": null,
    "sent_at": null,
    "created_by": "user_admin_1",
    "created_at": "2026-10-14T09:05:00.000Z",
    "updated_at": "2026-10-14T09:05:00.000Z"
  },
  "meta": {
    "request_id": "req_push_sched_read",
    "timestamp": "2026-10-14T09:06:00.000Z"
  }
}

Cancel it while still queued. DELETE /api/v1/push/scheduled/{id} is a guarded status change, not a hard delete: only a row still in scheduled status is cancelled. It answers 200 with the id and its new status, 404 for an unknown id and 409 once the push has left scheduled (sent or failed).

cURL

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

TypeScript

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/scheduled/scheduledPush_01J9ZABCDXYZ', {
  method: 'DELETE',
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
})
console.log(await res.json())

{
  "data": {
    "id": "scheduledPush_01J9ZABCDXYZ",
    "status": "cancelled"
  },
  "meta": {
    "request_id": "req_push_sched_cancel",
    "timestamp": "2026-10-14T09:07:00.000Z"
  }
}

Report wake telemetry. Your client calls POST /api/v1/push/telemetry after a push wake with battery level, wake count and delivery latency; the dashboard aggregates it so operators can see the app is not draining devices. device_token_id and platform ("ios", "android", "web" or "huawei") are required and validated; battery_pct may be omitted where the platform does not expose it (web), and the authenticated user id is taken from the session, not from your body. The 201 echoes the accepted report.

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/push/telemetry \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "device_token_id": "deviceToken_7e2c1b",
    "platform": "ios",
    "battery_pct": 82,
    "on_charger": false,
    "wake_count": 3,
    "delivery_latency_ms": 410
  }'

TypeScript

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/telemetry', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    device_token_id: 'deviceToken_7e2c1b',
    platform: 'ios',
    battery_pct: 82,
    on_charger: false,
    wake_count: 3,
    delivery_latency_ms: 410,
  }),
})
console.log(await res.json())

{
  "data": {
    "id": "deviceTelemetry_01J9Z8K3MN",
    "user_id": "user_8a1f2c",
    "platform": "ios",
    "battery_pct": 82
  },
  "meta": {
    "request_id": "req_push_telemetry",
    "timestamp": "2026-10-14T09:10:00.000Z"
  }
}

Test your push configuration. POST /api/v1/push/test-send fires one fixed-shape notification at every enabled device owned by the calling operator and answers 200 with the sent / failed counts plus one verdict per device. Your configuration delivered everywhere when failed is 0 and sent is greater than zero — that is the verdict the dashboard’s tester renders as success.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/push/test-send" \
  -H "X-API-Key: dv_live_sk_your_key_here"

TypeScript

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/test-send', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
})
const { data } = await res.json()
// data.failed === 0 && data.sent > 0 — every targeted device accepted.

{
  "data": {
    "tested": 2,
    "sent": 1,
    "failed": 1,
    "results": [
      {
        "deviceTokenId": "deviceToken_7e2c1b",
        "provider": "apns",
        "platform": "ios",
        "status": "sent"
      },
      {
        "deviceTokenId": "deviceToken_8b44aa",
        "provider": "fcm",
        "platform": "android",
        "status": "failed",
        "error": "BadDeviceToken"
      }
    ]
  },
  "meta": {
    "request_id": "req_push_testsend",
    "timestamp": "2026-10-14T09:12:00.000Z"
  }
}

When every device accepts, the envelope reads "tested": 2, "sent": 2, "failed": 0. Read the provider-level reason from the error string on each failed verdict. A permanent provider rejection such as BadDeviceToken also retires the dead token; register the device again to retest it. With no enabled device registered to the calling user, the endpoint answers NO_DEVICE_TOKENS (422) instead.

API Reference

All Endpoints

Worked push samples