> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Register a Push Device

> Register an APNs, FCM or web push token for a contact

# Register a Push Device

Registers or refreshes a device, typically from your app backend after the app receives its APNs or Firebase token. Registering a known token again reactivates it, refreshes its metadata, and moves it to the contact you pass. An unknown email becomes a contact quietly: no lists and no `contact_added` sequences.

Each contact keeps up to 20 active devices; the least recently seen are retired. Returns `201` for a new token and `200` for a known one. Requires the `subscribers:write` scope.

## Request

<ParamField body="platform" type="string" required>
  `ios`, `android`, or `web`.
</ParamField>

<ParamField body="token" type="string" required>
  iOS: the hex APNs device token. Android: the FCM registration token. Web: the
  `PushSubscription` endpoint (also send `keys`).
</ParamField>

<ParamField body="keys" type="object">
  Web only: `PushSubscription.toJSON().keys` with `p256dh` and `auth`.
</ParamField>

<ParamField body="email" type="string">
  Contact to link. Created quietly when new.
</ParamField>

<ParamField body="subscriberId" type="string">
  Existing subscriber to link instead of `email`.
</ParamField>

<ParamField body="deviceName" type="string">
  Label shown in the dashboard.
</ParamField>

<ParamField body="appVersion" type="string">
  Your app version.
</ParamField>

<ParamField body="osVersion" type="string">
  Operating system version.
</ParamField>

<ParamField body="locale" type="string">
  Device locale, for example `en-US`.
</ParamField>

<ParamField body="timezone" type="string">
  IANA timezone.
</ParamField>

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/push/devices" \
  --header "Authorization: Bearer $SEQUENZY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"platform":"ios","token":"8f2c9e...","email":"jane@example.com","deviceName":"Jane iPhone","appVersion":"3.2.0"}'
```

## Responses

<ResponseExample>
  ```json 201 theme={null}
  {
    "success": true,
    "created": true,
    "device": {
      "id": "dev_123",
      "subscriberId": "sub_456",
      "platform": "ios",
      "status": "active",
      "invalidReason": null,
      "source": "api",
      "deviceName": "Jane iPhone",
      "userAgent": null,
      "appVersion": "3.2.0",
      "osVersion": "18.1",
      "locale": "en-US",
      "timezone": "America/New_York",
      "tokenPreview": "…9f3a21bc",
      "lastSeenAt": "2026-10-01T12:00:00.000Z",
      "createdAt": "2026-09-20T09:30:00.000Z"
    },
    "message": "Device registered."
  }
  ```

  ```json 400 theme={null}
  {
    "error": "iOS tokens are the hex APNs device token (64+ hex characters)."
  }
  ```

  ```json 401 theme={null}
  {
    "error": "Invalid API key"
  }
  ```

  ```json 403 theme={null}
  {
    "error": "API key is missing required scope: subscribers:write"
  }
  ```

  ```json 404 theme={null}
  {
    "error": "Subscriber not found."
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.