ComRaidComRaid Docs

Endpoints

Register, list, and deactivate push Endpoints (FCM for Android, APNs for Expo iOS, or FCM for Firebase iOS), and manage Channel opt-outs.

Endpoints and Subscriptions

An Endpoint is a Channel plus an address (for example a push token). A Subscription is the SDK-facing name for a push Endpoint registered by the mobile SDK — same core row, different audience.

Register FCM endpoint

React Native apps should register anonymously via POST /mobile/subscriptions with X-ComRaid-App-Id, then bind the user with login(externalUserId, jwt). See React Native SDK. The endpoint below is for product backends using secret API keys.

POST https://api.comraid.io/contacts/{external_user_id}/endpoints
Authorization: Bearer cr_sk_...
Content-Type: application/json

{
  "channel": "push",
  "provider": "fcm",
  "address": "fcm_registration_token",
  "platform": "android",
  "metadata": {
    "device_id": "device_abc",
    "app_version": "5.2.0"
  }
}
  • Platforms: android, ios. When provider is omitted, android → fcm and ios → apns. Use provider: "fcm" with ios for Firebase Messaging tokens. For APNs, set metadata.apns_environment to sandbox or production. Never send Expo Push tokens.
  • Upserts/creates the Contact if needed.
  • May deactivate older Active Endpoints for the same project/provider/address when appropriate.
  • Creates a fresh Endpoint row and sets last_seen_at on that row.
  • Raw address values are redacted in normal API responses.

List endpoints for a Contact

Returns Endpoints for the Contact. Provider tokens (address) are omitted.

GET https://api.comraid.io/contacts/{external_user_id}/endpoints
Authorization: Bearer cr_sk_...
{
  "endpoints": [
    {
      "endpoint_id": "11111111-1111-4111-8111-111111111111",
      "channel": "push",
      "provider": "fcm",
      "platform": "android",
      "is_active": true,
      "created_at": "2026-11-03T10:00:00Z",
      "last_seen_at": "2026-11-03T10:00:00Z"
    }
  ]
}

Deactivate endpoint

Marks the Endpoint Inactive. Soft deactivation — the row is retained.

DELETE https://api.comraid.io/endpoints/{endpoint_id}
Authorization: Bearer cr_sk_...

Permanent FCM token errors also deactivate Endpoints automatically during send processing.

Opt-out per Channel

Opted out is a hard gate per Contact per Channel: no Deliveries on that Channel while Opted out. It is separate from Inactive Endpoints and from Category preferences. Only push is supported in V1.

PUT https://api.comraid.io/contacts/{external_user_id}/opt-outs/push
Authorization: Bearer cr_sk_...
Content-Type: application/json

{
  "opted_out": true
}
GET https://api.comraid.io/contacts/{external_user_id}/opt-outs
Authorization: Bearer cr_sk_...

Set opted_out to false to clear the opt-out (opt in again). Skipped Deliveries use outcome skipped when a Contact is Opted out.

From the app (App ID + Subscription credential), use POST /mobile/subscriptions/{id}/opt-out and POST /mobile/subscriptions/{id}/opt-in — same Contact Channel gate, different auth. SDKs wrap these as optOut / optIn. Request bodies and responses are in the API Reference.

Communication preferences

Set Category-level push preferences for a Contact. Sends with a matching category are skipped when the preference is disabled. Preferences only apply when the Contact is not Opted out of the Channel.

PUT https://api.comraid.io/contacts/{external_user_id}/preferences
Authorization: Bearer cr_sk_...
Content-Type: application/json

{
  "preferences": [
    {"category": "marketing", "channel": "push", "enabled": false}
  ]
}

Read the current preferences back — for example to render a notification-settings screen or confirm a preference change. The Contact must already exist (unlike PUT, this does not create one).

GET https://api.comraid.io/contacts/{external_user_id}/preferences
Authorization: Bearer cr_sk_...
{
  "contact_id": "e11a3d2a-a5b2-4f8c-8f2a-45f8fb78a89d",
  "external_user_id": "user_123",
  "preferences": [
    {
      "category": "marketing",
      "channel": "push",
      "enabled": false,
      "updated_at": "2026-09-09T10:00:00Z"
    }
  ]
}

Mobile session (HTTP-only)

POST /mobile/subscriptions/{id}/session (mobileSubscriptionSession) records an SDK session: increments session_count, refreshes last_seen_at, and upserts first-class Properties (locale, timezone, app/OS versions). It is distinct from Contact attributes.

There is no SDK method for session today — call it over HTTP with X-ComRaid-App-Id and subscription_credential. Session is HTTP-only until a product/SDK wrapper lands. Prefer the SDK for register, login, logout, token rotation, opt-in/out, and attributes when your platform ships those methods. Schemas: API Reference.

On this page