Device Registration

Registration tells Native Notify "this device can receive pushes, on this token". Call it on every app launch and whenever the push token changes — it is an idempotent upsert, so repeats are cheap and never create a duplicate.

POST https://app.nativenotify.com/api/universal/device/register

Get the device token

The token always comes from the platform — never from Native Notify. Install the package for your stack, get the token, then register it with the call below.

UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .badge, .sound]) { granted, _ in
    guard granted else { return }
    DispatchQueue.main.async { UIApplication.shared.registerForRemoteNotifications() }
}

// APNs answers here with the device token:
func application(_ application: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    let apnsToken = deviceToken.map { String(format: "%02x", $0) }.joined()
    // → register it as tokens.apnsToken
}

Request

curl -X POST https://app.nativenotify.com/api/universal/device/register \
  -H "Content-Type: application/json" \
  -d '{
    "appId": 123,
    "appToken": "yourAppToken",
    "deviceId": "A1B2C3D4-install-key",
    "platform": "ios",
    "subscriberId": "user_8241",
    "appVersion": "2.4.0",
    "timezone": "America/New_York",
    "tokens": { "apnsToken": "0c9d8e…" }
  }'

At least one token is required. Token values are capped at 400 characters (web endpoints at 1000), and Expo push tokens are rejected here (unsupported_token_type) — that is the Expo path.

Response — 201

{
  "ok": true,
  "device": {
    "appId": 123,
    "deviceId": "A1B2C3D4-install-key",
    "platform": "ios",
    "subscriberId": "user_8241",
    "appVersion": "2.4.0",
    "timezone": "America/New_York",
    "environment": "production",
    "createdAt": "2026-09-20T14:02:11.000Z",
    "lastSeenAt": "2026-09-23T09:10:44.000Z"
  },
  "tokens": { "apnsToken": "registered" }
}

tokens reports, per token you sent, what happened: "registered" (not seen before), "refreshed" (already on this device) or "reassigned" (the token moved here from another device).

Rules worth knowing

• Re-registering never duplicates. The unique keys are (app, deviceId) for devices and (app, token type, token) for tokens.
• Omitted optional fields keep their stored value — sending appVersion alone never wipes the subscriber id or the environment. Re-registering without subscriberId does not detach the device from its subscriber; deregister it instead.
• Token rotation is normal. When APNs/FCM hands you a new token, register again — same deviceId, new value.
• Platform pairing is enforced: apnsToken from an ios device, fcmToken from an android device, webPush from a web device — anything else is 400 token_platform_mismatch.
• A registration clears the token's dead flag. Failure strikes are stored per device, so re-registering the same device keeps its history; a token that moves to a different device is treated as fresh.

Deregister

POST https://app.nativenotify.com/api/universal/device/deregister

curl -X POST https://app.nativenotify.com/api/universal/device/deregister \
  -H "Content-Type: application/json" \
  -d '{ "appId": 123, "appToken": "yourAppToken", "deviceId": "A1B2C3D4-install-key" }'

{ "ok": true, "deviceId": "A1B2C3D4-install-key", "removed": true, "tokensRemoved": 1 }

A hard delete of the device row and its tokens, and idempotent: an unknown deviceId still answers 200 with "removed": false, so a logout that runs twice never fails. Call it when a user logs out, or to stop pushes for an install.

Errors

Errors use the envelope { "error": { "code", "message", "field"? } }. Every code below answers 400, except environment_disabled (403):

Registered? Prove it with a test send to that deviceId, or read the app's counts with /api/universal/health.