ComRaidComRaid Docs
API referenceMobile

Register or refresh a device subscription (FCM token)

Registers a push token (201) or refreshes an owned active row (200). Present subscription_credential to update in place. Without ownership of an existing active token that already has a credential, ComRaid deactivates the previous endpoint (last-writer-wins) and issues a new subscription_id plus credential. A credential-less Endpoint (API / Dashboard / CSV import) holding the same token is taken over in place: same subscription_id and Contact, with a newly issued subscription_credential. subscription_credential is returned only when newly issued. Accepts Contact Properties (locale, timezone, language, country) and Subscription Properties (app_version, sdk_version, device.os/os_version/model). Create sets first_app_version and session_count=1; refresh updates current_* Properties and preserves first_app_version (does not increment session_count).

POST
/mobile/subscriptions

Registers a push token (201) or refreshes an owned active row (200). Present subscription_credential to update in place. Without ownership of an existing active token that already has a credential, ComRaid deactivates the previous endpoint (last-writer-wins) and issues a new subscription_id plus credential. A credential-less Endpoint (API / Dashboard / CSV import) holding the same token is taken over in place: same subscription_id and Contact, with a newly issued subscription_credential. subscription_credential is returned only when newly issued. Accepts Contact Properties (locale, timezone, language, country) and Subscription Properties (app_version, sdk_version, device.os/os_version/model). Create sets first_app_version and session_count=1; refresh updates current_* Properties and preserves first_app_version (does not increment session_count).

Authorization

mobileAppId
headerX-ComRaid-App-Id<token>

Publishable mobile app id (cr_app_...)

Request Body

application/json
  1. body
platform*string
Value in"android""ios"
token*string

FCM registration token or APNs device token

provider?string

When omitted, android defaults to fcm and ios defaults to apns. Use provider=fcm with platform=ios for Firebase Messaging registration tokens. APNs is not valid for android.

Value in"fcm""apns"
apns_environment?string

Required when provider is apns (or ios without an explicit fcm provider)

Value in"sandbox""production"
app_version?string

Subscription Property current_app_version (and first_app_version on create). Also stored under metadata.app_version for legacy clients.

sdk_version?string

Subscription Property sdk_version

locale?string

Contact Property locale (BCP 47), e.g. en-US

timezone?string

Contact Property timezone (IANA), e.g. America/New_York

language?string

Contact Property language (ISO 639), e.g. en

country?string

Contact Property country (ISO 3166-1 alpha-2), e.g. US

device?

Device facts. Recognized keys os, os_version, model become Subscription Properties; the whole object is also stored under metadata.device.

metadata?

Free-form metadata merged with device and app_version (not Properties)

subscription_credential?string

Ownership secret issued at registration. Required to refresh the same subscription in place once issued. Omit on first register.

Response Body

Existing owned token refreshed (same subscription_id)

application/json
  1. response
subscription_id*string
Formatuuid
contact_id?string

Anonymous or known Contact bound to this Subscription

Formatuuid
channel*"push"
Value in"push"
subscription_credential?string

Returned only when newly issued; store securely on device

anonymous*boolean

True when the Contact has no external_user_id yet

platform*string
Value in"android""ios"
provider?string
Value in"fcm""apns"
Example Request
curl -X POST 'https://api.comraid.io/mobile/subscriptions' \  -H 'Content-Type: application/json' \  -d '{  "platform": "android",  "token": "fcm-registration-token",  "app_version": "1.2.0",  "device": {    "model": "Pixel 8",    "os_version": "14"  }}'
Example Response
{  "subscription_id": "aa11a4c2-a467-43db-b413-c4ab0f5cf627",  "contact_id": "f245e2a3-e141-4d41-912c-b1c1f5bd5598",  "channel": "push",  "subscription_credential": "string",  "anonymous": true,  "platform": "android",  "provider": "fcm"}