Server REST API Reference
Log InSign Up

Create user

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

Create a new user or modify the subscriptions associated with an existing User.

🚧

Compatibility with Pre-User Model SDKs and APIs

If you are still using pre-User Model APIs or SDKs (Mobile SDKs version 4 or lower, Web SDKs version 15 or lower), we recommend thorough testing of this endpoint before switching to the new User Model. Discrepancies may occur where the External ID set through the SDK and the External ID set through the API do not generate matching OneSignal IDs.

To ensure a smooth transition, consider the following options:

Overview

Use this endpoint to:

  • Create a user: Register a new user in OneSignal’s system by providing user-specific data such as aliases, properties, and subscriptions. See Users for details.
  • Create new subscriptions, update, or transfer existing subscriptions: Add new subscriptions or associate existing subscriptions (such as push notifications, emails, or SMS) with a newly created user or an existing one. See Subscriptions for details.
  • Add new aliases: Assign custom identifiers to the user, such as external_id, facebook_id, and other custom labels to uniquely identify the user across multiple platforms. See Aliases for details.

How to use this API

To use this API, you must provide at least one user identifier (alias or subscription) and any relevant data you wish to store about the user.

Aliases: Any new or updated aliases will immediately be associated with the user upon request. You can use aliases like onesignal_id, external_id, or any custom alias that uniquely identifies the user. See Aliases for details.

User properties: You can use this to set up tags for personalized messaging or store relevant user information to improve targeting and engagement. See Users for details.

Subscriptions: A user can have a maximum of 20 subscriptions across different platforms. Subscriptions register the user’s devices, email addresses, or phone numbers to receive notifications. Subscriptions are linked to users when they are created or transferred if they already exist. See Subscriptions for details.

General usage guidelines

  1. Creating a new user: If the user does not exist, this API will create a new user with the provided aliases and user profile data.

  2. Adding new subscriptions: You can associate new subscriptions with an existing user by providing the subscription details (e.g., device type, push token).

  3. Transferring existing subscriptions: If a subscription exists and is tied to a different user, this API will transfer the subscription to the user specified in the request.

  4. Handling aliases: Ensure each user’s provided aliases are unique. The request will return an error if an alias conflicts with another user.


Body parameters

properties

Type object

Description

Lets you specify user data, including tags and activity.

  • User data helps you personalize your user experience, track user behavior, and improve engagement through targeted push notifications, emails, and text messages.

The user properties object represents a user's profile, including tags, user activity, and other relevant properties.


User properties definitions (click to expand)

tags

Type object

Description

Custom user events or properties are represented as key-value pairs. These tags can be used for various purposes, such as segmentation, personalization, and tracking user behavior. For more details, see Data Tags.

  • Only string key-value pairs are supported; arrays and other nested objects are not.
  • Use tags to specify attributes or events related to a user, enabling targeted engagement and personalized experiences.

language

Type string

Description

Language Abbreviation in ISO 639-1 format.

  • Specify the user's preferred language to tailor content and notifications to their linguistic preferences; the default is en.
  • Must be lowercase.

timezone_id

Type string

Description

Timezone ID based on the tz database "TZ identifier".

  • Use the timezone ID to schedule notifications and other time-sensitive communications per the user's local time.
  • The default is America/Los_Angeles

lat

Type number

Description

The user's current latitude.

  • Latitude data can be used for location-based targeting and personalized content delivery.
  • Acceptable values range between -90 to 90.

long

Type number

Description

The user's current longitude.

  • Longitude data, when paired with latitude, enables precise geographic targeting.
  • Acceptable values range between -180 to 180.

country

Type string

Description

Country code in ISO 3166-1 Alpha 2 format.

  • Use the country code to localize content.
  • Must be upper-case.

first_active

Type number

Description

The time the user was first created. Represented as a Unix timestamp in seconds.

  • Enables you to calculate the duration of a user's engagement from the first interaction.

last_active

Type number

Description

The most recent time the user was active in your app. Represented as a Unix timestamp in seconds.

  • Use this field to gauge user engagement and inactivity to and trigger re-engagement campaigns.

ip

Type number

Description

The user's IP address.

  • Typically included in the response from our API
  • Useful for geographical targeting.
  • Can be specified in IPv4 or IPv6 format.

Example

{
  "properties": {
    "tags": {
      "foo": "bar",
      "this": "that"
    },
    "language": "en",
    "timezone_id": "America/Los_Angeles",
    "lat": 37.7749,
    "long": -122.4194,
    "country": "US",
    "first_active": 1589788800,
    "last_active": 1589788800,
    "purchases": 0,
    "ip": 3232235777
  }
}

identity

Type object

Required If subscriptions isn't specified.

Description

Lets you identify your users using custom IDs from different sources, such as Facebook, Amplitude, Segment, and others.

  • The external_id is recommended to be set unless the user is anonymous. Even if setting additional custom aliases, the External ID is important for identifying users across multiple Subscriptions. See Users for more details.
  • Each alias label-value pair must be unique to the user. If another user has a matching alias, an error will be returned

Example

{
  "identity": {
    "external_id": "An ID, defined by you, to refer to this user in the future",
    "facebook_id": "user_facebook_id",
    "amplitude_id": "user_amplitude_id",
    "mixpanel_id": "user_mixpanel_id",
    "custom_alias_N": "An alternative ID you'll want for retrieving this user's profile data and tags"
  }
}

subscriptions

Type object[]

Required

This field is required if identity is not defined with at least one identity.

Description

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

Use this object to manage and update one or more subscriptions associated with a user.

A type must be specified when creating a subscription, and the token must match the type. For example, if the typeis 'EMAIL' then token must be a valid email address. If the type is 'SMS' then token must be a valid phone number in E.164 format .

Subscriptions are uniquely identified via their device type and token.

If a subscription with the same (type, token) pair already exists for the app, it will be transferred to the specified user. Otherwise, a new subscription will be created.

The user's subscriptions objects represents the properties associated with each subscription tied to that user. These include:


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 SMS phone number associated with the subscription. Ensure the token is valid and correctly formatted for the chosen subscription type.

Phone numbers must be in E.164 format to be valid.


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, then use in conjunction with the notification_types property.


notification_types

Type number

Description

Indicates the reason for the Subscription's status details. Values are updated automatically when events are detected.

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.

This is because 1 denotes an active subscription and -31 denotes a subscription that has been disabled via the 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.
    • Permission was revoked.
  • -23, -24 = Web Service Worker Error.
  • -31 = Disabled via 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.



Example

{
  "subscriptions": [
    {
      "type": "Email",
      "token": "[email protected]",
      "enabled": true
    },
    {
      "type": "SMS",
      "token": "phone_number_in_E.164_format",
      "enabled": true
    },
    {
      "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