Server REST API Reference
Log InSign Up

Create subscription (by alias)

post https://api.onesignal.com/apps//users/by///subscriptions

Add a new subscription to your user.

Overview

Use this API to add one subscription to an existing user. Subscriptions represent a user's intent to receive messages through a given channels. See Subscriptions for more details.

How to use this API

You must first have a User created. If you are trying to add a new subscription to your OneSignal app without a user, then use the Create user API instead; which can create the user and add multiple subscriptions in a single request.

Identify your user

To create a subscription on a user, they must be identifiable via the alias_label and alias_id in the path parameters. The most commonly used and recommended alias is the external_id, but you can also use the onesignal_id or a custom alias. See Users and Aliases for details.

Required properties

At minimum, a subscription must have a type and token to be identifiable in OneSignal.

For example, if the type is 'Email' then the token must be a valid email address. If the type is 'SMS' then token must be a valid phone number in E.164 format, and if the type is one of the *Push options, then the token must be a valid push token.

Subscriptions are uniquely identified via their type and token. If the given type, token pair exists on a subscription already within the app, then that subscription will be transferred to the user set in the path parameters.

Body parameters

subscription

Type object

Description

Represents a user's intent to receive messages through a given channel. See Subscriptions for details.

Use this subscription object to create or update one subscription associated with a user.


Subscription property definitions (click to expand)

type

Type string

Description

Enum of SubscriptionType, representing the type of subscription (e.g., push notification, email, SMS). Choose the subscription type based on the channel in which you have the matching token. See Subscriptions for details.

Valid values include:

  • Email
  • SMS
  • iOSPush
  • AndroidPush
  • HuaweiPush
  • FireOSPush
  • WindowsPush
  • macOSPush
  • ChromeExtensionPush
  • ChromePush
  • FirefoxPush
  • SafariPush

token

Type string

Description

The push token, email address, or phone number associated with the subscription. Ensure the token is valid and correctly formatted for the chosen subscription type.

Email format: Should be a valid email address that you confirmed can receive emails.

SMS format: Phone number must be in E.164 format.

iOSPush APNS token format: 64 characters, hexadecimal characters only (0-9,a-f).

AndroidPush FCM token format: Typically 163 characters, alphanumeric characters, may contain hyphens, colons and underscore.


{
  "subscriptions": [
    {
      "type": "Email",
      "token": "[email protected]"
    },
    {
      "type": "SMS",
      "token": "+15551234567"
    },
    {
      "type": "iOSPush",
      "token": "7abcd49d0affb7426a8f1202420e8f4e2fc4df58e49501adc383f3bd66df8636"
    },
    {
      "type": "AndroidPush",
      "token": "dQGm89TZQXiTvLsRIj_GBo:APA91bpgqFgqkP2qYvV1uW2kdK5Z3TjgCXB_1jkL6VJrgH3hoYn16MvFY19tzDE4OuSgKjYC7itbFpSJYHBfKLWt-xZYBpgCVhYn9K5neV_9-Zj7s9mOSjRUJ2IwEwVSYhR-j5ICF9WB"
    }
  ]
}

enabled

Type bool

Description

Indicates if the subscription is currently active. Defaults to true if omitted. Set this to false if the user has unsubscribed.

If you are changing the subscriptions status via our REST API, then use in conjunction with the notification_types property to indicate how and why you changed it.


notification_types

Type number

Description

Indicates the reason for the Subscription's status details. Values are updated automatically when events are detected by our SDK but you should set them manually when updating via our REST API.

When creating Subscriptions, we recommend setting this to 1 if the Subscription's token is able to receive messages and the user has given permission to receive messages on this channel. Otherwise, you should omit the Subscription and just add the User properties.

Can be used in conjunction with the enabled property.

📘

Changing Subscription Statuses

When changing a subscription status, we recommend settingnotification_types to 1when setting enabled to trueand setting notification_types to -31when setting enabled to false.

1 denotes a subscribed subscription and -31 denotes a subscription that has been unsubscribed via the REST API. For a full list of possible notification_types values and their definitions, please see below.

Notification types definitions (click to expand)
  • 1 or positive number = Subscribed
    • The Subscription can receive messages on this channel.
    • Can be used with enabled property if you are enabling messages on behalf of the user. For push Subscriptions, a valid token must still be set to receive push notifications. See our SDK setup docs for details.
  • 0, -99 = Never Subscribed
    • The Subscription has not subscribed to the channel yet.
  • -2 = Unsubscribed
    • The Subscription cannot receive messages on this channel.
    • Can be used with enabled property set to false if you are turning off messages on behalf of the user. Recommended value when turning off message permissions.
    • Automatically set when the user unsubscribes.
  • -3, -5 = Android Support Library Error
  • -4, -8, -11, -12 = Android Google Play Services Library Error
  • -6 = Android Invalid Google Project Number
    • The FCMv1 Sender ID doesn't match the original in which this token belongs. Check the app's logcat. See Getting a Debug Log.
  • -7, -9 = Android Outdated Google Play Services App
    • Update or enable the Google Play Services app on the device.
  • -10 = Not Subscribed.
    • Push Subscription uninstalled app or unsubscribed in device settings.
    • Web push blocked notifications, cleared all data and workers.
  • -13 = iOS missing_push_capability.
    • Review the SDK setup docs to make sure all steps are implemented. See Channel setup.
  • -14, -16, -17 = iOS APNS Errors
  • -15 = iOS Simulator Error
    • iOS Simulator required iOS 16.4+ Use a different simulator or device.
  • -18 = Never Prompted
    • The Subscription was never prompted to subscribe. This only tracks the required permission prompt and does not include in-app messages.
  • -19 = Prompted But Never Answered
    • The Subscription was prompted but didn't provide an answer.
  • -20, -21 = temp_web_record. Web, pushsubscriptionchange permission revoked
  • -22 = Manually Unsubscribed via dashboard.
    • Permission was revoked.
  • -23, -24 = Web Service Worker Error.
  • -31 = Disabled via REST API.
  • -98 = SMS Subscription awaiting double opt-in.

session_time

Type number

Description

The total amount of time the user has had the app open in seconds. Use this data to track user engagement and app usage patterns.


session_count

Type number

Description

The number of times the user has opened the app. This metric can be used to identify active users and those who should be re-engaged.


app_version

Type string

Description

The version of your app that the user is currently using. This information is useful for troubleshooting, filtering users based on app versions, and ensuring compatibility.


device_model

Type string

Description

The model of the user's device (e.g., iPhone 14). Use this data to optimize app performance and ensure compatibility with different device models.


device_os

Type string

Description

The device's operating system version. This data is beneficial for providing operating system specific support and updates.


test_type

Type number

Platform iOS mobile push

Description

Indicates which APS environment entitlement to use for your iOS app build.

  • If the iOS push token was generated in a Production environment, you can omit the test_type property (null) or set to 0.
  • If the iOS push token was generated in a Development environment, set test_type to 1 indicating "Development".
  • If the iOS push token was generated in an Ad-Hoc environment, set test_type to 2 indicating "Ad-Hoc".

sdk

Type string

Description

Only available to OneSignal SDKs. Indicates the OneSignal SDK version.


rooted

Type bool

Platform Android mobile push

Description

Only available to OneSignal SDKs. Indicates if the Android device is rooted or jail-broken.


web_auth

Type string

Platform Web push

Description

Only available to OneSignal SDKs. The web_auth key for web push. You should not import web push tokens; see Importing Web Push Subscriptions for details.


web_p256

Type string

Platform Web push

Description

Only available to OneSignal SDKs. You should not import web push tokens; see Importing Web Push Subscriptions for details.



Examples

Creating an email, SMS and iOS push subscription.

{
  "subscription": {
      "type": "Email",
      "token": "[email protected]",
      "enabled": true
    }
}

{
  "subscription": {
      "type": "SMS",
      "token": "the-phone-number-in-E.164-format",
      "enabled": true
    }
}

{
  "subscription":     {
      "type": "iOSPush",
      "token": "20bdb8fb3bdadc1bef037eefcaeb56ad6e57f3241c99e734062b6ee829271b71",
      "enabled": true,
      "notification_types": 1,
      "session_time": 98,
      "session_count": 6,
      "sdk": "",
      "device_model": "iPhone 14",
      "device_os": "18.0",
      "rooted": false,
      "test_type": 1,
      "app_version": "5.1.7",
      "web_auth": "",
      "web_p256": ""
    }
}
Language