POST
/
apps
/
{app_id}
/
users
/
by
/
{alias_label}
/
{alias_id}
/
subscriptions
curl --request POST \
  --url https://api.onesignal.com/apps/{app_id}/users/by/{alias_label}/{alias_id}/subscriptions \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '{
  "subscription": {
    "type": "Email",
    "token": "<string>",
    "enabled": true,
    "notification_types": 123,
    "session_time": 123,
    "session_count": 123,
    "app_version": "<string>",
    "device_model": "<string>",
    "device_os": "<string>",
    "test_type": 123,
    "sdk": "<string>",
    "rooted": true,
    "web_auth": "<string>",
    "web_p256": "<string>"
  }
}'
"//The subscription was created successfully \n//with the data provided in the request\n{}"

​
Overview

This API allows you to add a new subscription to an existing User using an alias identifier. A subscription reflects a user’s intent to receive messages through a specific communication channel, such as email, SMS, or push notifications. See Subscriptions for additional context.

If you’re looking to create a new user and add subscriptions simultaneously, use the Create User API instead.

​
How to use this API

To attach a subscription, the user must already exist and be referenced using an alias. The alias_label and alias_id path parameters define how the user is identified:

  • Common alias: external_id
  • Other options: onesignal_id, or custom aliases

For details, refer to Users and Aliases.

​
Required Fields

Each subscription must include at least:

  • type: the channel (e.g., Email, SMS, iOSPush)
  • token: the unique identifier for the channel (e.g., email address, phone number, push token)

If the specified type and token already exist in the app, the subscription will be transferred to the user identified in the path parameters.

Headers

​
Authorization
string
default:Key YOUR_APP_API_KEY
required

Your App API key with prefix Key. See Keys & IDs.

Path Parameters

​
app_id
string
required

Your OneSignal App ID in UUID v4 format. See Keys & IDs.

​
alias_label
string
default:external_id
required

The alias name or key to locate the user. Most commonly set as external_id but can be the onesignal_id or a custom alias.

​
alias_id
string
required

The specific identifier for the given alias to identify the user.

Body

application/json
​
subscription
object
required

The subscription's properties.

Response

200
application/json

200

The response is of type object.