🚧
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:

Update to the User Model SDKs: Upgrade to the latest User Model SDKs (Mobile SDK 5+, Web SDK 16+). For more details, refer to the User Model Migration Guide.

Continue Using Pre-User Model APIs: If you are not ready to migrate, continue using the existing APIs for Adding a Device, Editing Tags with External User ID, and Editing a Device until the SDK migration is complete.

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

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.
Adding new subscriptions: You can associate new subscriptions with an existing user by providing the subscription details (e.g., device type, push token).
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.
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.

tags
language
timezone_id
lat
long
country
first_active
last_active
ip

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:

type
token
enabled
notification_types
session_time
session_count
app_version
device_model
device_os
test_type
sdk
rooted
web_auth
web_p256

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.

Can be used in conjunction with the enabled property. For example, when changing a subscription status.

If setting enabled to true, set notification_types to 1.
If setting enabled to false, set notification_types to -31.

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.

`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": ""
    }
  ]
}

Create user

🚧
Compatibility with Pre-User Model SDKs and APIs

Overview

How to use this API

General usage guidelines

Body parameters

`properties`

`tags`

`language`

`timezone_id`

`lat`

`long`

`country`

`first_active`

`last_active`

`ip`

`identity`

`subscriptions`

`type`

`token`

`enabled`

`notification_types`

`session_time`

`session_count`

`app_version`

`device_model`

`device_os`

`test_type`

`sdk`

`rooted`

`web_auth`

`web_p256`

🚧Compatibility with Pre-User Model SDKs and APIs

Overview

How to use this API

General usage guidelines

Body parameters

properties

tags

language

timezone_id

lat

long

country

first_active

last_active

ip

identity

subscriptions

type

token

enabled

notification_types

session_time

session_count

app_version

device_model

device_os

test_type

sdk

rooted

web_auth

web_p256

🚧
Compatibility with Pre-User Model SDKs and APIs

`properties`

`tags`

`language`

`timezone_id`

`lat`

`long`

`country`

`first_active`

`last_active`

`ip`

`identity`

`subscriptions`

`type`

`token`

`enabled`

`notification_types`

`session_time`

`session_count`

`app_version`

`device_model`

`device_os`

`test_type`

`sdk`

`rooted`

`web_auth`

`web_p256`