Push Notifications Without the SDK | User.com REST API Docs

# Push Notifications Without the SDK

If you can't integrate the mobile SDK - for example in React Native, Cordova, or similar frameworks - you can still send push notifications by registering FCM tokens directly via the REST API. No SDK installation required.

This approach also works for migrating tokens from another push provider (e.g. OneSignal) to Positive User.

# How it works

Call the ping endpoint with a contact identifier and an FCM token. Positive User will create or update the contact and associate the token. Once the token is registered and your Firebase Service Key is uploaded, you can send push campaigns immediately.

# Authentication

Generate a Mobile SDK Key in Settings → App Settings → Advanced → Mobile keys. Include it as a Token in the Authorization header on every request.

# Endpoint

POST https://<your-domain>.user.com/api/sdk/v1/ping/

Required headers:

Authorization: Token <Mobile SDK Key>
Accept: */*;version=2
Content-Type: application/json

# Payload

{
    "customer": {
        "user_id": "your-internal-user-id"
    },
    "device": {
        "os_type": "Android",
        "fcm_key": "<device_fcm_token>",
        "model": "Pixel 7",
        "version": "13"
    }
}

The payload must include both customer and device objects.

# `customer` fields

Field	Type	Description
`user_id`	`String`	Your internal identifier for the contact
`email`	`String`	Contact email
`userKey`	`String`	Positive User internal key

Any standard or custom contact attribute is also accepted here (e.g. first_name, marketing_agreement).

# `customer` matching behavior

Payload	What happens
Empty object	Creates a new anonymous contact and assigns the token
With `user_id`	Finds the contact by `user_id` and assigns the token. Creates the contact if none found.
With `email`	Always creates a new contact
With `userKey`	Finds the contact by internal key and assigns the token. Creates one if not found.

# `device` fields

Field	Required	Description
`fcm_key`	Yes	The FCM registration token from the device
`os_type`	Recommended	`"Android"` or `"iOS"`
`model`	Recommended	Device model name
`version`	Recommended	OS version string
`manufacturer`	No	Device manufacturer
`sdk`	No	Android API level

# Full example

curl -X POST 'https://your-domain.user.com/api/sdk/v1/ping/' \
  -H 'Content-Type: application/json' \
  -H 'Accept: */*;version=2' \
  -H 'Authorization: Token <Mobile SDK Key>' \
  -d '{
    "customer": {
        "user_id": "abc123",
        "email": "jane@example.com"
    },
    "device": {
        "os_type": "Android",
        "fcm_key": "<device_fcm_token>",
        "model": "Pixel 7",
        "manufacturer": "Google",
        "sdk": 33,
        "version": "13"
    }
}'

# Track notification clicks

To record a push notification click in Positive User analytics, call the clicked endpoint with the notification delivery ID and the contact's user key.

POST https://<your-domain>.user.com/api/sdk/v1/push-notification/<id>/clicked/

Headers:

Authorization: Token <Mobile SDK Key>
X-User-Key: <user_key>

<id> - the push notification delivery ID, available in the incoming RemoteMessage payload
<user_key> - the Positive User internal contact key (see Getting the user key below)

Error reference:

Status	Cause
`404 Not Found`	No push delivery found with that ID
`401 Unauthorized`	Missing or invalid `Authorization` header

# Getting the user key

The user key is the Positive User internal identifier for the current contact. You need it for the clicked endpoint and other direct API calls.

Android - available in the register() callback:

UserCom.getInstance().register(Customer(), object : CustomerUpdateCallback {
    override fun onSuccess(response: RegisterResponse) {
        val userKey = response.key
    }
    override fun onFailure(throwable: Throwable) {}
})

iOS - available as a property at any time after ping():

let userKey = UserSDK.default?.userId

# Remove an FCM token

To detach a specific FCM token from a contact - for example on logout - call the delete endpoint:

DELETE https://<your-domain>.user.com/api/sdk/v1/delete-fcm-token/

Headers:

Authorization: Token <Mobile SDK Key>
X-User-Key: <user_key>
Content-Type: application/json

Body:

{
    "fcm_key": "<token_to_remove>"
}

Example:

curl -X DELETE 'https://your-domain.user.com/api/sdk/v1/delete-fcm-token/' \
  -H 'Authorization: Token <Mobile SDK Key>' \
  -H 'X-User-Key: <user_key>' \
  -H 'Content-Type: application/json' \
  -d '{"fcm_key": "<device_fcm_token>"}'

# Panel setup

Before push campaigns can be sent, Positive User needs your Firebase Service Key. If you haven't done this yet:

In Firebase Console, go to Project settings → Service accounts
Click Generate new private key and download the JSON file
In Positive User, go to Settings → App Settings → Advanced → Mobile keys
Click Add SDK Admin and upload the file

See Setup & Configuration for step-by-step screenshots.

← Mobile App Inbox