In OneSignal, a User represents an individual with one or more Subscriptions to messaging channels such as push notifications, SMS, and email. Each user can have up to 20 subscriptions and is identified by a unique OneSignal ID.

Initially, users are anonymous until identified using an External ID, enabling tracking across platforms and devices.

User properties

Property	Description
`onesignal_id`	A unique UUID v4 automatically assigned by OneSignal to each user. Cannot be edited but may change after setting an External ID. See below for more details.
`external_id`	The primary identifier for a user across platforms. See below for more details.
`tags`	Custom data associated with users, such as preferences or behavior. Learn more about Data Tags.
`language`	The user’s preferred language in ISO 639-1 format. Auto-set by our SDK when the user is created. Can be updated using the API or `setLanguage` method. See Multi-language messaging for details.
Aliases	Custom `key : value` strings made up of an alias label (the key) and an alias ID (the value). See Aliases for details.
`timezone_id`	The user's timezone in IANA TZ format. Auto-set by our SDK based on the user's device settings when last accessing your application. Can be updated using our Create user or Update user API.
Location	The `lat` and `long` GPS coordinates of the mobile push Subscription if location tracking is enabled. See Location-Triggered Notifications for more details.
`country`	The country code in ISO 3166-2 format based on the user's IP address detected by our SDK.
First Session, `first_active`	The first date and time the user was created within OneSignal.
Purchases	The SKUs of "consumable" in-app purchases made by the user while the OneSignal SDK has been active in your application.

OneSignal ID

The OneSignal ID is a UUID v4 generated by OneSignal to represent a user. It cannot be manually edited but may change when the External ID is assigned.

A OneSignal ID is created in the following scenarios:

A user downloads or re-installs and opens your mobile app.
A current user uninstalls, re-installs, and opens your mobile app.
A user subscribes to your website.
A current web user clears browser cache and returns to your website.
You create a user or Subscription without setting an External ID like using our Create user API or CSV Import.
You remove the External ID, like calling OneSignal.logout.

The OneSignal ID will be the same for all Subscriptions with matching External IDs. When you identify a user with OneSignal.login and the External ID already exists within the OneSignal app, the current OneSignal ID on the Subscription will be deleted and replaced with the identified OneSignal ID.

If a user uninstalls and re-installs your mobile app on the same device or clears browser cache and returns to your website, a new OneSignal ID and Push Subscription ID will be created. If you call OneSignal.login, then the original OneSignal ID and data will continue for the new Subscription.

Email and SMS subscriptions created with the OneSignal.User.addEmail and OneSignal.User.addSms methods will also be associated with the current OneSignal ID. See Mobile SDK reference and Web SDK reference for details on these methods.

External ID

The External ID is a String value assigned by you to identify and link users in OneSignal with your internal system. This helps you track users across multiple Subscriptions and consolidates multiple OneSignal IDs into one user profile.

An External ID is set via the OneSignal.login method or through the Create user API.

The External ID can be removed from the Subscription via the OneSignal.logout method.

If the External ID exists within the OneSignal app, it will have the same OneSignal ID. Note that the current push subscription will always be transferred to the currently logged in user (OneSignal ID), as they represent the current owners of that push subscription.

If the user is no longer identifiable in your app, the OneSignal.logout method will remove the External ID from the Push Subscription.

📘
External IDs should be unique values
Generic values such as -1, 0, 1, NA, NULL, null, UNQUALIFIED cannot be set for an External ID.

Anonymous vs. identified users

Users without an External ID are considered anonymous in OneSignal. The below examples illustrate how this works.

Scenario: No External ID

User subscribes to your website: OneSignal ID OSID1.
Same user downloads your app: OneSignal ID OSID2.
Result: The user has two separate profiles in OneSignal.

Scenario: With External ID

User subscribes to your website and is assigned External ID EIDA: OneSignal ID OSID1.
Same user downloads your app and is assigned the same External ID EIDA.
Result: The two profiles merge into one: OneSignal ID OSID1.

Best practices

Always set an External ID to consolidate user profiles.
Avoid generic placeholder values for External IDs.
Use OneSignal.login for seamless tracking across platforms.
Only the External ID can update OneSignal ID. Set custom Aliases after you call OneSignal.login.

Monthly active users

For billing purposes, a Monthly Active User (MAU) is defined as a mobile push subscription that has been active within the past 30 days.

Example

If a user has multiple subscriptions linked by a shared External ID:

iOS mobile push subscription on iOS
Android mobile push subscription
Web push subscription
Email subscription

You would be billed for two MAUs, if both iOS and Android mobile push subscriptions have been active in the last 30 days. Email and web push subscriptions do not count toward MAU billing.

📘
In-app messages are included with mobile push subscriptions.

User properties

OneSignal ID

External ID

📘External IDs should be unique values

Anonymous vs. identified users

Scenario: No External ID

Scenario: With External ID

Best practices

Monthly active users

📘

📘
External IDs should be unique values