Create a new subscription for the user identified by the alias_label and alias_id in the path parameters. A subscription refers to the ways a user can receive messages sent from OneSignal like push notifications, SMS, and email. Learn more about subscriptions here.


You're Viewing User Model Documentation ๐ŸŽ‰

OneSignal is in the process of migrating from a device-centric model (player ID) to a new user-centric data model (OneSignal ID). In the new user-centric world, Users have a OneSignal ID, and what was the player ID is now known as the Subscription ID.

To learn more, check out the User Model Migration Guide.

Please refer to Version 9 of our documentation for device-centric information.

onesignal_id can be used as a special alias_label, with the UUID as the alias_id.

At minimum, a device type must be provided in the request when creating a new subscription. For example, for an iOS push subscription, it would look like the following:

  "subscription": {
    "type": "iOSPush"

A subscription is uniquely identified by its device type and token pair. If the given (type, token) pair exists on an existing subscription, that subscription will be transferred to this User.

Note: You can also create and modify existing subscriptions associated with a user. Refer to the create user documentation here.

Response codes:

  • 201: a new Subscription was created
  • 202: an existing Subscription was transferred to this User
  • 200: the subscription already exists on this user (cannot be used to update an existing subscription. Please use Update Subscription)

Response object fields:

idstringThe OneSignal Subscription ID (UUID)
app_idstringThe OneSignal Application ID (UUID)
typestringThe subscription types. Will be one of the following:
tokenstringThis field is depending on the subscription type.
For push subscriptions the token is the push token, for email subscriptions the token is the email address, for SMS subscriptions the token is the phone number
enabledbooleanWhether this subscription enabled or not
notification_typesnumberFor internal use only
session_timenumberTotal session duration in seconds
session_countnumberThe number of times a subscription has visited the app or site
sdkstringThe OneSignal SDK version installed on the subscription device
device_modelstringThe subscription device make and model
device_osstringThe subscription device operating system version
rootedboolean Whether the device is rooted or not
test_typenumberThis is used in deciding whether to use your iOS Sandbox or Production push certificate when sending a push when both have been uploaded. Set to the iOS provisioning profile that was used to build your app. 1 = Development 2 = Ad-Hoc Omit this field for App Store & Test Flight builds.
app_versionstringThe client application version
net_typenumberThe device network type.
net_type: 0 = wifi
net_type: 1 = cellular
carrierstringThe cellular carrier
web_authstringWeb only authorization key
web_p256string Web only p256 key