Skip to main content

​
Overview

OneSignal’s user and subscription system enables fine-grained tracking of how users engage with your app or website across multiple messaging channels—push, email, and SMS. Each user can have multiple subscriptions, and each subscription is tied to a messaging channel and device. This structure allows you to personalize messaging, analyze behavior, and monitor cross-platform engagement. Think of Users as the parent and Subscriptions as the children. The following are the properties available when users and subscriptions are created and viewed via our APIs.

​
Identity

These properties are used to identify and link users within your OneSignal app.

​
OneSignal ID

  • Type: string (UUID v4)
  • Access: Read-only
  • API Mapping: user.identity.onesignal_id, alias_label=onesignal_id
The unique ID assigned by OneSignal to each user. It connects all the user’s subscriptions across different channels.

​
External ID

  • Type: string
  • Access: Read-write
  • API Mapping: user.identity.external_id, alias_label=external_id
A developer-assigned unique ID to match OneSignal data with your internal user data. Best Practice: Use a stable identifier (e.g. user ID) that doesn’t change when a user updates their email or phone number.
json
{
  "identity": {
    "external_id": "user_12345"
  }
}

​
Custom alias

  • Type: string
  • Access: Read-write
  • API Mapping: user.identity.your_custom_alias, alias_label=your_custom_alias
Optional aliases to link users across additional systems. Best Practice: Always set an external_id and use custom aliases for additional mappings.
json
{
  "identity": {
    "custom_alias_label": "custom_alias_id_12345"
  }
}

​
User properties

​
Country

The country code where the user was detected. Based on the IP address when the user last interacted with our SDK or set with our Create user or Update user APIs.

​
First Session

  • Type: integer (unix timestamp in seconds)
  • Access: Read-write
  • API Mapping: user.properties.first_active
The date & time the first subscription associated with the user was created with our SDK or our Create user or Update user APIs.

​
IP Address

  • Type: string
  • Access: Read-write
  • API Mapping: user.properties.ip
Identifies the user’s network location when using our mobile or web SDKs or set with our Create user or Update user APIs. When detected via our SDK, it is not stored on our servers when users are in the EU for GDPR reasons. This property can be disabled for all users by OneSignal. See Handling Personal Data for details.

​
Language

  • Type: string (ISO 639-1)
  • Access: Read-write
  • API Mapping: user.properties.language
The ISO 639-1 formatted language code of the device detected the first time the subscription was created and can be updated via our SDK setLanguage method or Create user and Update user APIs. See Multi-language messaging for more details.

​
Last session

  • Type: integer (unix timestamp in seconds)
  • Access: Read-write
  • API Mapping: user.properties.last_active
The date and time the user’s push subscription last visited your app or website with the OneSignal SDK. Email and SMS subscriptions tied to the same user will have the same last session as the most recently active push subscription. Its recommended to let our SDK update it when the user interacts with the app or website but can be updated with the Create user and Update user APIs.

​
Location

  • Type: float (latitude and longitude)
  • Access: Read-write
  • API Mapping: user.properties.lat & user.properties.long
The latitude and longitude of the device. See Location-triggered notifications for details. Its recommended to let our SDK update it when the user interacts with the app but can be updated with the Create user and Update user APIs.
json
{
  "properties": {
    "lat": 37.7749,
    "long": -122.4194
  }
}

​
Tags

  • Type: object (key-value strings)
  • Access: Read-write
  • API Mapping: user.properties.tags
User-level properties or events that can be used for segmentation and targeting. See Tags for details.
json
{
  "properties": {
    "tags": {
      "premium_user": "true",
      "last_purchase": "2023-05-15",
      "favorite_category": "electronics"
    }
  }
}

​
Timezone

  • Type: string (TZ identifier)
  • Access: Read-write
  • API Mapping: user.properties.timezone_id
The timezone ID of the device based on the last time the user interacted with the app or website. Its recommended to let our SDK update it when the user interacts with the app or website but can be updated with the Create user and Update user APIs.

​
Subscription properties

​
App version

  • Type: string
  • Access: Read-write
  • API Mapping: subscription.app_version
The version of your mobile app as detected by our SDKs or specified in our API. Our SDK sets this based on the following criteria:
  • Android: Android Studio versionCode in your App build.gradle
  • iOS: Xcode App Version

​
Channel

  • Type: string (enum)
  • Access: Read-only
  • API Mapping: subscription.type
Represents how the subscription can receive messages. Each subscription can only belong to one of three channels: push, email, and SMS. Push subscriptions can have specific Types that correspond to their platforms. For example a mobile subscription could have types iOSPush, AndroidPush, HuaweiPush, FireOSPush and web push subscriptions can have types like ChromePush, FirefoxPush, SafariPush. Mobile push subscriptions can receive both push and in-app messages. Web push, email, and SMS subscriptions cannot receive in-app messages.

​
Device

  • Type: string
  • Access: Read-write
  • API Mapping: subscription.device_model and subscription.device_os
The model of the user’s device and operating system version detected by our SDK when the push, email and SMS subscription was created. The operating system version will update when the user opens the app on the updated version. Will be blank for email and SMS subscriptions created outside of our SDK.
json
{
  "subscription": {
    "device_model": "iPhone12,1",
    "device_os": "14.4.1"
  }
}

​
Email

  • Type: string
  • Access: Read-write
  • API Mapping: subscription.token
An email address for a user. Applies to email subscriptions only. Example:
json
{
  "subscription": {
    "type": "Email",
    "token": "[email protected]"
  }
}

​
Phone Number

  • Type: string
  • Access: Read-write
  • API Mapping: subscription.token
A phone number for a user. Applies to SMS subscriptions only.
json
{
  "subscription": {
    "type": "SMS",
    "token": "+15551234567"
  }
}

​
Push Token

  • Type: string
  • Access: Read-write
  • API Mapping: subscription.token
The identifier provided by the push service (APNS, FCM, HMS) that allows for push notifications to be received. Applies to push subscriptions only. FCM Token format: Typically 163 characters, alphanumeric characters, may contain hyphens, colons and underscore. APNS Token format: 64 characters, hexadecimal characters only (0-9,a-f).
json
{
  "subscriptions": [
    {
      "type": "iOSPush",
      "token": "7abcd49d0affb7426a8f1202420e8f4e2fc4df58e49501adc383f3bd66df8636"
    },
    {
      "type": "AndroidPush",
      "token": "dQGm89TZQXiTvLsRIj_GBo:APA91bpgqFgqkP2qYvV1uW2kdK5Z3TjgCXB_1jkL6VJrgH3hoYn16MvFY19tzDE4OuSgKjYC7itbFpSJYHBfKLWt-xZYBpgCVhYn9K5neV_9-Zj7s9mOSjRUJ2IwEwVSYhR-j5ICF9WB"
    }
  ]
}

​
SDK Version

  • Type: string
  • Access: Read-only
  • API Mapping: subscription.sdk
The version of our native SDK used in the app. See GitHub > SDKs for details.

​
Sessions

  • Type: integer
  • Access: Read-write
  • API Mapping: subscription.session_count
The number of times the push subscription has opened your app or visited your website (with the OneSignal SDK). A new session is created when the user opens the mobile app or website in a new tab/window after it is put out of focus for more than 30 seconds. Email and SMS subscriptions tied to the same user will inherit the session counts from the most active push subscription.
json
{
  "subscription": {
    "session_count": 42
  }
}

​
Status

  • Type: boolean
  • Access: Read-write
  • API Mapping: subscription.enabled & invalid_identifier on CSV Export API
Represents the interest or ability of the user to receive messages for that channel. A subscription can either be subscribed or unsubscribed. Within our dashboard Audience > Subscriptions we try to provide additional context: Subscribed: The subscription should be able to receive messages. See When do push subscription statuses get updated? for more details. Unsubscribed: The subscription cannot receive messages.
  • Can be overridden for email subscriptions on a per-message basis. See Email unsubscribe links & headers.
  • Can be updated for email and SMS subscriptions in the dashboard (options button) or via the API.
  • This should only be handled by our SDK for push subscriptions. See SDK optIn and optOut methods for details.
Never Subscribed: A variation of unsubscribed. The subscription has never subscribed.

​
Status Details

  • Type: string
  • Access: Read-write
  • API Mapping: subscription.notification_types
Additional details about the subscription status.

​
Subscription ID

  • Type: string (UUID v4)
  • Access: Read-only
  • API Mapping: subscriptions.id, subscription_id
UUID v4 assigned by OneSignal to represent the Subscription. Can be used to send messages or update the Subscriptions through the API. Example: Using View user API.
json
{
  "subscriptions": [
    {
      "id": "87c1a10a-931a-48b5-a6dc-718c8cd0c2cd"
 		}
  ]
}

​
Usage Duration

  • Type: integer (seconds)
  • Access: Read-write
  • API Mapping: subscription.session_time
The number of seconds a push subscription has had your mobile app or website (with the OneSignal SDK) open in the foreground. Data is sent to us after a session exceeds 60 seconds. Email and SMS subscriptions tied to the same user will inherit the usage duration from the Push Subscription.
json
{
  "subscription": {
    "session_time": 120
  }
}

​
FAQ

​
When do push subscription statuses get updated?

The subscription status will be updated in OneSignal automatically when the user:
  1. Interacts with the OneSignal SDK You can capture this event with our SDK Subscription Observer methods and send to your Database.
  2. Token Expiration If the device token has been inactive for over 270 days, Google FCM will expire the token, the subscription will be marked unsubscribed when a push is sent to it. If the user opens the app on this device, our SDK will refresh the token, keeping the original subscription status.
  3. Unsubscribed Notification Delivery After sending 2+ notifications to the unsubscribed device:
    • Android mobile subscriptions and web push subscriptions: FCM will alert OneSignal that the device is unsubscribed after the 2nd notification is sent to the unsubscribed device.
    • iOS mobile subscriptions: APNS will alert OneSignal that the device is unsubscribed after some time has passed between the user uninstalling the app or unsubscribed and has not opened the app when sending notifications to the subscription.

​
Example Unsubscribe Detection Flow:

  1. Notification 1 sent and user receives on device. The user decides to unsubscribe.
  2. Notification 2 sent, the OneSignal Dashboard shows “Delivered” but the user does not actually receive it.
  3. Notification 3 sent, the OneSignal Dashboard shows Unsubscribed for Android and web subscriptions. iOS subscriptions may take additional notifications and time for the unsubscribed event to be sent to OneSignal from Apple.
  4. Notification 4 will not be sent to that device.
To protect user privacy, Apple doesn’t want developers to know when a user removes the app. Some details provided by Apple can be found here: https://developer.apple.com/forums/thread/670868If a device unsubscribes and opens the app, OneSignal detects this unsubscribe event right away and updates the record through our SDK. However if the device uninstalls the app or unsubscribes and does not open the app, it may take several weeks for Apple to report the unsubscribe event.Apple will wait a random amount of time, typically over 14 days, before reporting a device is unsubscribed. The unsubscribed detection requires at least two notifications to be sent to the app, after the app is uninstalled.Apple also has an edge case where development apps must have at least one currently installed in order to determine that another one is uninstalled and can’t get notifications (in addition to the random multi-day delay involved). Details here: https://developer.apple.com/library/archive/technotes/tn2265/_index.html#//apple_ref/doc/uid/DTS40010376-CH1-TNTAG34If you need to remove older devices, you can delete them using our dashboard or API.

​
How do I manage subscriptions across multiple devices?

Users often have multiple devices (e.g., smartphone, tablet, desktop browser) and may use your service on all of them. OneSignal automatically handles this by:
  1. Creating separate push subscriptions for each device
  2. Allowing you to link these subscriptions using the External ID
  3. Maintaining separate push tokens while sharing user-level properties
Best Practice: Use the External ID consistently across all of a user’s devices to ensure proper linking.

​
What happens when a user changes devices?

When a user gets a new device:
  1. Their old push subscription remains in your OneSignal account but will eventually be marked as unsubscribed
  2. A new push subscription is created when they install your app on the new device
  3. If you set the same External ID on the new device, OneSignal will link it to the same user
  4. User-level properties and tags will transfer to the new device automatically

​
How do I handle subscription deletions?

If you need to comply with data deletion requests or clean up old subscriptions:
  1. Use the Delete User API to remove a user and all their subscriptions
  2. For selective deletion, use the Delete Subscription API
  3. Set up automated clean-up jobs to remove subscriptions older than a certain age using our API