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. Whenprovideris omitted, android →fcmand ios →apns. Useprovider: "fcm"with ios for Firebase Messaging tokens. For APNs, setmetadata.apns_environmenttosandboxorproduction. 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_aton that row. - Raw
addressvalues 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.