Devices

A device is a push token poolse can send to: to ring a phone for a call while the app is closed, and to deliver notifications. Register tokens with the signed-in user's end-user JWT. A token is always attached to the user whose JWT registered it.

To push to your own app, poolse needs your APNs and FCM credentials. Set them up on the dashboard's Push page. The full setup is in Push setup (iOS & Android).

There is no API to list a user's devices.

Register a device

POST/v1/devices

End-user JWT

Call it on every app launch with the token the OS gives you. It is safe to repeat.

Field	Type	Required	Description
`token`	string	yes	The push token.
`platform`	`"ios"` \| `"android"`	yes
`kind`	`"voip"` \| `"alert"`	no	Default `voip`. iOS only. See below.
`environment`	`"production"` \| `"sandbox"`	no	Default `production`. Use `sandbox` for an iOS debug build, whose tokens only work against the APNs sandbox.

iOS registers two tokens, and they must not be mixed up:

kind: "voip": the PushKit VoIP token. It carries incoming calls only. A call push sent to a regular APNs token is dropped by Apple without an error.
kind: "alert": the regular APNs token, for notifications such as messages and missed calls.

Android registers one FCM token. Leave kind out. It is not used for Android.

A token belongs to one phone, so it belongs to one user at a time. When a token that is already registered is registered again by another user in your tenant (someone else signed in on the same phone), it moves to the new user. Each registration replaces the token's platform, environment and kind with the values sent, so the latest registration always describes the token.

Response

201:

{
  "id": "e4b2c7a9-1f3d-4e6a-8b0c-5d7f9a1e3c25",
  "tenant_id": "65787825-3152-4c1e-9b8a-0d6f4e2a7c11",
  "user_id": "11111111-2222-3333-4444-555555555555",
  "platform": "ios",
  "environment": "production",
  "kind": "voip",
  "last_registered_at": "2026-10-27T09:12:44.123456Z",
  "inserted_at": "2026-10-01T18:02:10.000000Z",
  "updated_at": "2026-10-27T09:12:44.123456Z"
}

The token itself is never returned.

curl -X POST https://api.poolse.dev/v1/devices \
  -H "Authorization: Bearer $USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{"token":"'"$PUSHKIT_TOKEN"'","platform":"ios","kind":"voip"}'

Errors

All validation errors use validation_failed (422) with no details. The message names the field:

When	Message
`token` missing or empty	`token` is required.
`platform` missing or not `ios` / `android`	`platform` must be one of: ios, android.
`environment` not `production` / `sandbox`	`environment` must be one of: production, sandbox.
`kind` not `voip` / `alert`	`kind` must be one of: voip, alert.
The token could not be stored	`Could not register device.`

Remove a device

DELETE/v1/devices/:token

End-user JWT

Removes a push token from the calling user, so the phone stops ringing and receiving notifications for them. Call it on sign-out. URL-encode the token in the path.

204, also when the token was not registered to this user.

curl -X DELETE "https://api.poolse.dev/v1/devices/$PUSHKIT_TOKEN" \
  -H "Authorization: Bearer $USER_JWT"

poolse also deletes a token on its own when the push service rejects it as invalid.