Users
Managing your users in OneSignal.
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). To learn more, check out the User Model Migration Guide.
Please refer to Version 9 of our documentation for device-centric information.

User
A user represents a person with one or more subscriptions to the different messaging channels of your application i.e push notifications, SMS and email. Users are automatically assigned a unique identifier called OneSignal ID. Users are considered anonymous until identified with an alias.
A user must have at least one of the following, otherwise it is deleted:
- a subscription
- an alias
User Properties
In addition to subscriptions and aliases, a user can have the following properties.
Property | Description |
---|---|
OneSignal ID | UUID assigned by OneSignal to represent the user. Cannot be edited. Can be used to update users through the API. |
External ID | OneSignal's default alias and represents an identified user. See Aliases & External ID for more details. |
Data Tags | Custom event or user data. See Data Tags for more details. |
Language | The user's preferred language. See Language & Localization for more details. |
Timezone ID | The most recent time zone the user's device was in when accessing your application. Timezone is tracked based on IANA TZ format. |
Location | GPS coordinates of the device. Location tracking must be turned on and accepted by the user. See Location-Triggered Notifications for more details. |
Country | The ISO 3166-2 country code of the IP address detected on the user's device the last time it communicated with OneSignal servers. |
Last Active | The last date and time the user was active in your application. |
First Session | The first date and time the user was created within OneSignal. |
Amount Spent | The amount the user has spent on your mobile app's "consumable" in-app purchases while the OneSignal SDK has been active in your application. |
Purchases | The SKUs of "consumable" in-app purchases made by the user while the OneSignal SDK has been active in your application. |
Test Subscriptions for a User
You can set a user's subscriptions as Test Subscriptions to access when sending test messages.
See Find & Set Test Subscriptions for details.
User Lifecycle
All users start as anonymous, with a OneSignal ID and a Subscription ID. When you identify a user in your app / site (via OneSignal.login
) this assigns your provided ID to OneSignal's built-in alias called External ID.
For example, if a user installs your app on multiple devices (or uninstalls and reinstalls your app on the same device), each time this creates a new OneSignal ID and Subscription ID. Setting the External ID (calling OneSignal.login
) every time users identify themselves will associate all data and history together under a single OneSignal user with the same OneSignal ID. See Aliases & External ID for details.
Assigning External ID and Aliases
The External ID and aliases needs to be a unique identifier for a user. Do not assign an External ID or alias to a user before you are able to uniquely identify them. Generic values such as 0, NA, NULL can not be set for an External ID.
It is recommended to always use External ID. Then if needed, add additional custom user aliases. See Aliases & External ID for details.
Anonymous user becomes a new identified user
When you identify the user with OneSignal.login
, if the External ID does not yet exist in your OneSignal app, the current anonymous user becomes a newly identified user.
New Subscription IDs will have the same OneSignal ID when calling OneSignal.login
with the associated External ID.
Anonymous user identified as an already existing user
When you identify the user with OneSignal.login
, if the External ID already exists in your OneSignal app, then the current anonymous user’s data automatically merges to the existing identified user.
The anonymous OneSignal ID is deleted and the identified OneSignal ID is set on the Subscription ID.
Data tags set on the anonymous user will be merged and existing tag values will be updated on the identified OneSignal ID.
Identified user becomes an anonymous user
Calling OneSignal.logout
method removes the OneSignal ID and sets an anonymous OneSignal ID on the current Push Notification Subscription ID.
Data tags and Aliases are disassociated with the Push Notification Subscription ID and new anonymous OneSignal ID.
Email, SMS and any other Push Notification Subscription IDs remain with the identified OneSignal ID. They are not transferred to the new anonymous OneSignal ID.
User deletion
You can delete users via their OneSignal ID, External ID or custom aliases. This deletes all Subscription IDs and data associated with the user. More details in the Delete Users guide.
Example User Lifecycles
Common examples and recommendations on how to address users in OneSignal.
Login User (Recommended)
It is recommended to call OneSignal.login
as soon as you identify the user in your app, even before adding the email and/or phone number subscriptions or custom user aliases. The login
method associates the OneSignal ID and External ID with all Subscription IDs for that user.
- A new User1 downloads your app on Android. This creates:
- a new OneSignal ID (example
OSID1
). - a new Android Subscription ID (example
SID_Android1
).
- a new OneSignal ID (example
- User1 identifies themself and you call
OneSignal.login
to set an External ID (exampleEID1
).- The user is identified and has OneSignal ID (
OSID1
), External ID (EID1
), and Subscription ID (SID_Android1
).
- The user is identified and has OneSignal ID (
- User1 provides you their email address and phone number which you set with
OneSignal.User.addEmail
andOneSignal.User.addSms
.- An Email Subscription ID (
SID_Email1
) and SMS Subscription ID (SID_Sms1
) are created. - The user1 OneSignal ID (
OSID1
), External ID (EID1
) has 3 Subscription IDs:SID_Android1
,SID_Email1
, andSID_Sms1
.
- An Email Subscription ID (
- This same User1 subscribes to your website. This creates:
- a new OneSignal ID (example
OSID2
). - a new Web Push Subscription ID (
SID_Web1
). - The web subscription and OneSignal ID are currently anonymous.
- a new OneSignal ID (example
- User1 logs in to identify themself on your website. You call
OneSignal.login
with the same identifier used on the mobile app.- The External ID (
EID1
) is set on this Subscription (SID_Web1
). - The current OneSignal ID (
OSID2
) is replaced with User1's original OneSignal ID (OSID1
). - User1 is identified and has OneSignal ID (
OSID1
), External ID (EID1
), and 4 Subscription IDs:SID_Web1
,SID_Android1
,SID_Email1
, andSID_Sms1
.
- The External ID (
Creating Email & SMS Subscriptions Before Login
It is recommended to identify the user with OneSignal.login
before adding custom user aliases, email addresses and/or phone number subscriptions. However, if your app allows anonymous users to provide email addresses and phone numbers, this is what to expect.
- A user downloads your app on iOS. This creates:
- a new OneSignal ID (example
OSID3
). - a new iOS Subscription ID (example
SID_iOS3
).
- a new OneSignal ID (example
- The user provides their email address and phone number which you set with the SDK methods:
OneSignal.User.addEmail
andOneSignal.User.addSms
.- A new Email Subscription ID (
SID_Email3
) and new SMS Subscription ID (SID_Sms3
) is created. - The Email and SMS Subscription IDs gets the same OneSignal ID (
OSID3
).
- A new Email Subscription ID (
- The user logs in to identify themself in the iOS app as User1. You call
OneSignal.login
with External IDEID1
.- The iOS Push Subscription (
SID_iOS3
) gets External ID (EID1
) and OneSignal ID (OSID1
). - However,
OSID3
is still set on the Email and SMS Subscriptions. - You will need to call
OneSignal.User.addEmail
andOneSignal.User.addSms
again to add these subscriptions toOSID1
.
- The iOS Push Subscription (
Login only sets the OneSignal ID on the Push Subscription
If you add the Email and/or Phone number before calling
OneSignal.login
you will need to calladdEmail/addSms
again to set the Email and Phone number Subscription IDs to the current OneSignal ID.
Notes on CSV and API Imports
If you import your existing email addresses and phone numbers using the Import Phone Numbers CSV, Import Email Addresses CSV or Create user API without setting an External ID. This creates:
- a new OneSignal ID.
- a new Email or SMS Subscription ID.
It is always recommended to include the identified external_id
in your CSV uploads to associate the Subscription with a User or use the Create subscription API if the user is already known in OneSignal.
If you imported the data without an known External ID, these subscriptions will be "fixed" to the identified OneSignal ID and External ID under the following situations:
- Calling the SDK
OneSignal.User.addSms/addEmail
methods on the mobile apps or website with the same phone number/email address you imported. - Use the CSV Upload options again with the
external_id
column and correct ID. - Use the Update user API.
Updated 12 days ago