Notify API reference

Notify API · Recipients

post/v1/workspaces/{workspace_id}/recipients/{external_id}/devicesAuth

Register a device

Registers an APNs or FCM token, or a browser web push subscription, for the recipient. Registering a token the recipient already has refreshes it (200). A token registered to another recipient of the workspace moves to this one (a shared device signed in as someone else), at most 3 times per token per UTC day. A recipient keeps at most 20 active devices: registering more marks the least recently seen as `pruned` (`evicted`). The token is stored hashed and encrypted; responses show its last 6 characters only.

Path parameters

workspace_id*string · uuid

Id of the workspace.

external_id*string

Your user id for the recipient (URL-encoded): 1-255 of `A-Z a-z 0-9 . _ : @ | -`.

Headers

Idempotency-Keystring

A key (1..256 chars, [A-Za-z0-9._:-]) makes retries safe: a replay returns the original response for 24 h.

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/workspaces/{workspace_id}/recipients/{external_id}/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"
}