Push Notifications API

Send push notifications to your end users’ iOS and Android devices through Apple Push Notification service (APNs) and Firebase Cloud Messaging (FCM). Orbit holds your provider credentials and exposes a single send endpoint that fans out to the right transport. Base path: /api/v1/push Authentication: API key (X-API-Key) or session JWT.

Using the SDKs

import { Orbit } from "@devotel-orbit/node";

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

const res = await orbit.push.list();

Python (same call via the SDK’s escape hatch):

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/push")

The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches everything else through the generic client.request() escape hatch above. See the Python SDK. Returns the typed ApiResponse envelope. See the SDK index at SDK quickstart.

Device tokens

Your mobile app registers each device’s push token after the user grants permission. Re-register on token rotation; APNs and FCM both rotate tokens periodically.

Method	Path	Purpose
`POST`	`/api/v1/push/register`	Register a device token (mobile app SDK)
`POST`	`/api/v1/push/device-tokens`	Register or update a token (server-side)
`GET`	`/api/v1/push/device-tokens`	List tokens for the current user
`DELETE`	`/api/v1/push/device-tokens/{id}`	Unregister a token

Register a device token

POST /api/v1/push/register and POST /api/v1/push/device-tokens are the same operation — the first exists for older SDK clients; new integrations should call /device-tokens. Supply the native APNs or FCM token for ios / android / huawei, or a Web Push subscription envelope for platform: web. Registering a token that already exists just refreshes its owner and last-seen time — it does not create a duplicate.

curl -X POST https://api.orbit.devotel.io/api/v1/push/register \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_abc123",
    "platform": "ios",
    "token": "6f3c1a9b…device-push-token"
  }'

201 Created returns the token’s Orbit id — save it if you want to target specific devices when sending:

{
  "data": {
    "id": "deviceToken_01J9ZABCDEF1",
    "user_id": "usr_abc123",
    "platform": "ios",
    "token": "6f3c1a9b…device-push-token",
    "app_id": null,
    "app_install_id": null,
    "device_id": null,
    "notification_channel": null
  },
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-15T12:00:00Z"
  }
}

List device tokens

GET /api/v1/push/device-tokens lists the tenant’s registered tokens, newest first, capped at 200 rows. Pass ?user_id=<id> to scope the list to one user.

curl "https://api.orbit.devotel.io/api/v1/push/device-tokens?user_id=usr_abc123" \
  -H "X-API-Key: dv_live_sk_your_key_here"

200 OK returns the rows — use the id values to target a send by device_token_ids, and enabled to see whether a token currently receives pushes:

{
  "data": [
    {
      "id": "deviceToken_01J9ZABCDEF1",
      "user_id": "usr_abc123",
      "platform": "ios",
      "token": "6f3c1a9b…device-push-token",
      "app_id": null,
      "app_install_id": null,
      "device_id": null,
      "endpoint": null,
      "notification_channel": "default",
      "created_at": "2026-08-10T09:12:00Z",
      "last_seen_at": "2026-08-15T11:58:00Z",
      "enabled": true
    },
    {
      "id": "deviceToken_01J9ZABCDEF2",
      "user_id": "usr_abc123",
      "platform": "android",
      "token": "fcm:9a7c…registration-token",
      "app_id": "com.example.myapp",
      "app_install_id": null,
      "device_id": null,
      "endpoint": null,
      "notification_channel": null,
      "created_at": "2026-08-09T17:40:00Z",
      "last_seen_at": "2026-08-12T08:21:00Z",
      "enabled": true
    }
  ],
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-15T12:00:00Z"
  }
}

Unregister a device token

DELETE /api/v1/push/device-tokens/{id} removes a token so the device no longer receives pushes — for example on sign-out.

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

Success is 204 No Content with an empty body. An unknown id returns 404 Not Found (NOT_FOUND).

Sending

Method	Path	Purpose
`POST`	`/api/v1/push/send`	Send a push notification to specific devices (`device_token_ids`) or users (`user_ids`)
`GET`	`/api/v1/push/notifications`	List sent notifications

Example — send to a user’s devices

Target a send with either user_ids (every registered device for those users) or device_token_ids (specific device tokens). At least one of the two is required.

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": ["usr_abc123"],
    "title": "Your order has shipped",
    "body": "Tracking #1Z999AA10123456784",
    "data": { "order_id": "ord_42" },
    "deep_link": "myapp://orders/ord_42"
  }'

To notify specific devices instead, pass device_token_ids with the ids returned from /api/v1/push/device-tokens:

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_01J9ZABCDEF1", "deviceToken_01J9ZABCDEF2"],
    "title": "Your order has shipped",
    "body": "Tracking #1Z999AA10123456784"
  }'

Either variant returns 201 Created on an immediate send. The response carries one notifications[] entry per targeted device, so an APNs rejection or a frequency-cap skip on one device never masks the others’ delivery:

{
  "data": {
    "notifications": [
      {
        "id": "pushNotification_01J9ZABCDEF9",
        "deviceTokenId": "deviceToken_01J9ZABCDEF1",
        "transport": "apns",
        "status": "sent"
      },
      {
        "id": "pushNotification_01J9ZABCDEF10",
        "deviceTokenId": "deviceToken_01J9ZABCDEF2",
        "transport": "fcm",
        "status": "skipped",
        "error": "Frequency cap exceeded for this recipient — retry after 3600s"
      }
    ],
    "total": 2,
    "sent": 1,
    "devices_targeted": 2
  },
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-15T12:00:00Z"
  }
}

Each entry in the response notifications[] array carries a transport field — apns, fcm, webpush, or hms — identifying which transport was used to reach that device, alongside its deviceTokenId and delivery status. A status of sent, failed, or skipped is per-device; when a device could not be reached, its entry carries an error describing why.

List sent notifications

GET /api/v1/push/notifications returns the tenant’s notification log, newest first — the per-device rows recorded by /push/send — with delivery status and the delivered/opened timestamps the SDK ack endpoints set. Page older rows with ?cursor=<created_at of the last row>&limit=50; each page is capped at 200 rows.

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

200 OK returns the page:

{
  "data": [
    {
      "id": "pushNotification_01J9ZABCDEF9",
      "device_token_id": "deviceToken_01J9ZABCDEF1",
      "title": "Your order has shipped",
      "body": "Tracking #1Z999AA10123456784",
      "data": { "order_id": "ord_42" },
      "status": "opened",
      "sent_at": "2026-08-15T12:00:01Z",
      "delivered_at": "2026-08-15T12:00:03Z",
      "opened_at": "2026-08-15T12:04:47Z",
      "unread_count": 1,
      "notification_channel": null,
      "error": null,
      "created_at": "2026-08-15T12:00:01Z",
      "platform": "ios",
      "user_id": "usr_abc123"
    }
  ],
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-15T12:00:00Z"
  }
}

VoIP call devices

A separate registry from the device tokens above, used ONLY to deliver inbound-call pushes that wake a backgrounded or terminated mobile app — Apple PushKit (CallKit) on iOS, a high-priority FCM channel on Android. Registration is handled by the mobile app SDK; the list and revoke endpoints let a backend integration or admin tool audit and manage a user’s registered call devices.

Method	Path	Purpose
`POST`	`/api/v1/push/voip-devices`	Register or refresh a VoIP call-push token (mobile app SDK)
`GET`	`/api/v1/push/voip-devices`	List registered VoIP call devices, newest-seen first (optional `user_id` filter)
`DELETE`	`/api/v1/push/voip-devices/{id}`	Unregister a VoIP call device — for example on sign-out

Register with the raw PushKit token on iOS, or the call-channel FCM token on Android. Re-registering the same token refreshes it and clears any prior revocation.

curl -X POST https://api.orbit.devotel.io/api/v1/push/voip-devices \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_agent42",
    "platform": "ios",
    "voip_token": "9b04ef…pushkit-token",
    "bundle_id": "com.example.agentapp"
  }'

201 Created returns the registered device:

{
  "data": {
    "id": "voipDevice_01J9ZABCDEF9",
    "user_id": "usr_agent42",
    "platform": "ios",
    "voip_token": "9b04ef…pushkit-token",
    "bundle_id": "com.example.agentapp"
  },
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-15T12:00:00Z"
  }
}

The list response includes revoked devices (revoked_at set) alongside active ones, so you can see why a device stopped receiving call pushes — a bad token is marked revoked rather than deleted, and re-registering the same token clears the revocation automatically. Results are capped at 200 rows.

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

200 OK returns the devices, newest-seen first:

{
  "data": [
    {
      "id": "voipDevice_01J9ZABCDEF9",
      "user_id": "usr_agent42",
      "platform": "ios",
      "voip_token": "9b04ef…pushkit-token",
      "bundle_id": "com.example.agentapp",
      "revoked_at": null,
      "created_at": "2026-08-14T10:00:00Z",
      "last_seen_at": "2026-08-15T11:59:00Z"
    },
    {
      "id": "voipDevice_01J9ZABCDEF7",
      "user_id": "usr_agent42",
      "platform": "android",
      "voip_token": "fcm:7a1d…call-channel-token",
      "bundle_id": null,
      "revoked_at": "2026-08-13T08:31:00Z",
      "created_at": "2026-08-11T15:20:00Z",
      "last_seen_at": "2026-08-13T08:31:00Z"
    }
  ],
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-15T12:00:00Z"
  }
}

Unregister with the device’s Orbit id:

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

Success is 204 No Content with an empty body; an unknown id returns 404 Not Found (NOT_FOUND).

Scheduled pushes

To send later, add an ISO 8601 send_at to POST /api/v1/push/send. When send_at is in the future the notification is stored instead of dispatched and the request returns 202 Accepted; a background worker replays it through the same fan-out and suppression logic when the time arrives. Omit send_at (or pass a past instant) to send immediately.

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": ["usr_abc123"],
    "title": "Flash sale starts soon",
    "body": "20% off for the next hour",
    "send_at": "2026-06-20T09:00:00Z"
  }'

202 Accepted confirms the push was queued, not sent — read it back or cancel it with the scheduled-push id:

{
  "data": {
    "id": "scheduledPush_01J9ZABCDXYZ",
    "status": "scheduled",
    "send_at": "2026-06-20T09:00:00Z"
  },
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-15T12:00:00Z"
  }
}

Manage scheduled pushes that have not yet been sent:

Method	Path	Purpose
`GET`	`/api/v1/push/scheduled`	List scheduled pushes (optional `status` filter: `scheduled`, `sent`, `cancelled`, `failed`)
`GET`	`/api/v1/push/scheduled/{id}`	Read a single scheduled push
`DELETE`	`/api/v1/push/scheduled/{id}`	Cancel a scheduled push that has not been sent yet

List the queue with GET /api/v1/push/scheduled — soonest send_at first, capped at 200 rows:

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

{
  "data": [
    {
      "id": "scheduledPush_01J9ZABCDXYZ",
      "payload": {
        "user_ids": ["usr_abc123"],
        "title": "Flash sale starts soon",
        "body": "20% off for the next hour"
      },
      "send_at": "2026-06-20T09:00:00Z",
      "status": "scheduled",
      "attempts": 0,
      "last_error": null,
      "sent_at": null,
      "created_by": "usr_admin1",
      "created_at": "2026-08-15T12:00:00Z",
      "updated_at": "2026-08-15T12:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-15T12:00:00Z"
  }
}

Read one scheduled push by id — including its full payload, attempt count, and any error from a failed dispatch:

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

{
  "data": {
    "id": "scheduledPush_01J9ZABCDXYZ",
    "payload": {
      "user_ids": ["usr_abc123"],
      "title": "Flash sale starts soon",
      "body": "20% off for the next hour"
    },
    "send_at": "2026-06-20T09:00:00Z",
    "status": "scheduled",
    "attempts": 0,
    "last_error": null,
    "sent_at": null,
    "created_by": "usr_admin1",
    "created_at": "2026-08-15T12:00:00Z",
    "updated_at": "2026-08-15T12:00:00Z"
  },
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-15T12:00:00Z"
  }
}

An unknown id returns 404 Not Found (NOT_FOUND).

Cancelling a scheduled push

DELETE /api/v1/push/scheduled/{id} cancels a push that is still in the scheduled state. Cancel is a guarded status flip, not a hard delete — the row remains queryable with status: "cancelled".

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

A successful cancel returns 200 OK with the new status:

{
  "data": {
    "id": "scheduledPush_01J9ZABCDXYZ",
    "status": "cancelled"
  },
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-15T12:00:00Z"
  }
}

Cancellation only succeeds while the push is still pending. If the worker has already dispatched it (sent / failed) or it was cancelled by an earlier request, the endpoint returns 409 Conflict with error code SCHEDULED_PUSH_NOT_CANCELLABLE — the push has already left and can no longer be recalled. Branch on this code rather than treating the cancel as a silent success. An unknown id returns 404 Not Found (NOT_FOUND).

{
  "error": {
    "code": "SCHEDULED_PUSH_NOT_CANCELLABLE",
    "message": "Scheduled push 'scheduledPush_01J9ZABCDXYZ' is already 'sent' and can no longer be cancelled",
    "status": 409
  }
}

API Reference

All Endpoints

Push Notifications API: register FCM and APNs devices

Push Notifications API

Using the SDKs

Device tokens

Register a device token

List device tokens

Unregister a device token

Sending

Example — send to a user’s devices

List sent notifications

VoIP call devices

Scheduled pushes

Cancelling a scheduled push

See also

​Push Notifications API

​Using the SDKs

​Device tokens

​Register a device token

​List device tokens

​Unregister a device token

​Sending

​Example — send to a user’s devices

​List sent notifications

​VoIP call devices

​Scheduled pushes

​Cancelling a scheduled push

​See also

Push Notifications API

Using the SDKs

Device tokens

Register a device token

List device tokens

Unregister a device token

Sending

Example — send to a user’s devices

List sent notifications

VoIP call devices

Scheduled pushes

Cancelling a scheduled push

See also