Notify API reference

Notify API · Client

post/v1/client/devicesAuth

Register this device

Registers the app's APNs or FCM token, or the browser's web push subscription, for the signed-in recipient (call it on every app start; the same token again refreshes it). A token registered to another recipient moves to this one, at most 3 times per token per UTC day; a recipient registers at most 10 times per hour. Call `DELETE /v1/client/devices/{device_id}` when the user signs out on this device. Safe to repeat, so it takes no `Idempotency-Key`.

Request body

channel*object

`apns` (Apple), `fcm` (Firebase Cloud Messaging) or `webpush` (a browser subscription).

tokenstring

The device token, for `apns` (hex) and `fcm`. Stored hashed and encrypted; responses only show its last 6 characters. Not used for `webpush`.

Example: "740f4707bebcf74f9b7c25d48e3358945f6aa01da5ddb387462c7eaf61bb78ad"

subscriptionobject

The browser push subscription, for `webpush` only.

app_id*string

The app the token belongs to: the iOS bundle id for `apns`, the Firebase project id for `fcm`, the site origin for `webpush`. Push is sent with the credential configured for this app.

Example: "com.example.app"

environmentobject

APNs only, required there: `sandbox` for development builds, `production` for TestFlight and App Store builds. A token sent to the wrong environment fails with `BadDeviceToken`.

platformobject

The operating system. Defaults to `ios` for `apns`, `android` for `fcm` and `web` for `webpush`.

timezonestring

The device's IANA time zone, used for quiet hours when the recipient has none.

Example: "Europe/Lisbon"

Response · 200 Already registered to this recipient: refreshed.

id*string · uuid

The device's id.

channel*object

The channel.

token_last6*string

The last 6 characters of the token (for `webpush`, of the endpoint). The full token is never returned.

Example: "bb78ad"

app_id*string

Bundle id, Firebase project id or site origin.

Example: "com.example.app"

environment*object

APNs environment; null for other channels.

platform*object

The operating system.

timezone*string

The device's IANA time zone.

Example: "Europe/Lisbon"

state*object

`active` receives pushes; `invalid` was rejected by the provider; `pruned` was removed (the provider reported it dead, or it was evicted as the oldest of more than 20).

state_reason*string

Why the device is not active (`evicted`, `unregistered`, `bad_device_token` …).

last_seen_at*string · date-time

Last registration or refresh.

moved_at*string · date-time

When the token last moved here from another recipient (a shared device signed in as someone else).

created_at*string · date-time

When the device was first registered.

updated_at*string · date-time

Last change.

Example

Request

POST https://api.notify.productcraft.co/v1/client/devices
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "channel": {},
  "token": "740f4707bebcf74f9b7c25d48e3358945f6aa01da5ddb387462c7eaf61bb78ad",
  "subscription": {},
  "app_id": "com.example.app",
  "environment": {},
  "platform": {},
  "timezone": "Europe/Lisbon"
}

Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "channel": {},
  "token_last6": "bb78ad",
  "app_id": "com.example.app",
  "environment": {},
  "platform": {},
  "timezone": "Europe/Lisbon",
  "state": {},
  "state_reason": "string",
  "last_seen_at": "2026-01-01T00:00:00.000Z",
  "moved_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}