Skip to main content

​
Overview

We are updating our APIs to focus on Users! Your team’s integration with OneSignal is leveraging our device-centric APIs, which focuses on Players/Devices. Updating the integration you’ve built with OneSignal to a user-centric model will help our mutual customers unlock deeper multichannel potential. You can learn more about our new User Model here. Below is the information you’ll need to update the integration you’ve built with OneSignal. Updates must be made to partner-built integrations as soon as possible to enable mutual customers or prospects on our joint platforms. Please inform us when your team will have the resources to update to the new endpoints. Until the partner-built integration is supported by OneSignal’s user-centric APIs, mutual customers should refrain from migrating. If requested, OneSignal will communicate to mutual customers to let them know if the partner integration does not yet support our new user-centric data model. We will be de If you are using an endpoint not listed here, please follow up with us at integration@onesignal.com

​
Terminology updates:

Player Model (API Documentation V9)User Model (API Documentation V11)
External User ID (optional identifier)External ID (now a top-level identifier) - customer set User ID
-OneSignal ID (NEW) - OneSignal’s User ID
-Alias IDs (NEW) - optional user-level identifiers
Player ID, DeviceSubscription ID - Push, Email or SMS record

​
Integration updates

​
Stop using Player ID (Device) → Start using User IDs like External ID, Alias, or OneSignal ID

If your integration is leveraging Player ID as the key identifier representing OneSignal, you’ll need to adjust how your integration is working. The new API centers around users identified by one of External IDs, aliases, or OneSignal IDs instead of device records with Player IDs. Please note that Player IDs map directly to Subscription IDs, and that External and OneSignal IDs sit above these IDs at the user level in OneSignal’s new user-centric data model. One External ID/OneSignal ID can map to one or more Subscription IDs.

​
Edit Device API → Update User API for user properties

Updating properties such as tags will now be done with the Update User API. User properties will now be updated on the user level rather than the device level.

​
Edit Device API → Update Subscription API for subscription properties

If you are using the Edit Device API to update subscription properties, you will need to update the endpoint in use and update Player ID to Subscription ID in name only (the IDs will remain the same if it is an existing integration).

​
Edit Tags by EUID API → Update User API for updating or adding tags

With the shift to a user-centric data model, updating or adding tags is now occurring at the user level, leveraging the Update User API by using a users External ID or OneSignal ID.

​
Create Notification API → Create Notification API for sending notifications

The updated version of our Create Notification API will allow you to create a notification leveraging External ID, OneSignal ID, and Alias IDs assigned to a User in OneSignal. Note: you can still use the Player/Subscription ID with the V11 Create Notification endpoint.

​
Required - OneSignal-Usage header

Please add the HTTP header “OneSignal-Usage” to indicate who is making a call to the OneSignal APIs. This should indicate your company name and that the endpoint is called from a partner integration. For example, if the Bluth Company was a partner of OneSignal and using our APIs, the header would be OneSignal-Usage: Bluth Company | Partner Integration

​
Obtaining the user-level IDs

If your integration stores the Player ID (aka Subscription ID) from OneSignal and relies on that identifier to send updates to OneSignal, you should migrate to our new user-level IDs. We prefer that you leverage External ID. However, not all OneSignal customers have configured External ID. Some Integration Partners are choosing to leverage both External ID and OneSignal ID for updates/functionality, while others are using just the OneSignal ID. More information on OneSignal ID and External ID are available in our documentation.

​
Using the Player ID

You can retrieve the OneSignal ID or External ID for a OneSignal via a GET request to the View User Identity by Subscription API with the known Player ID/ aka Subscription ID. 
## Find Identity via Subscription ID
curl "https://api.onesignal.com/apps/<APP_ID>/subscriptions/<SUBSCRIPTION_ID>/user/identity"
Example Response 
{
  "identity": {
    "onesignal_id": "fd1d8faf-e758-4919-8f0f-807f6d2b216c",
    "external_id": "<External ID will be here if it exists>"
  }
}

​
Adding custom aliases

New with the user-centric update on the OneSignal side is support for Aliases, which are unique identifiers that are stored as key:value pairs at the user-level. You may want to update your integration with OneSignal to allow customers to associate an ID (in addition to External ID) from your platform with a OneSignal User. For example, the Bluth Company could assign an Alias ID when leveraging the Create Alias(User) or Create Alias (by subscription) endpoints by adding an ID with their name as the key, and the ID as the unique value: bluth_company:1233-32322-2323. Again, Alias IDs (like External IDs) need to be a unique value, and will be maintained at the user level. If a subscription is updated with an Alias ID that is linked to a different user, that subscription will be reassigned to the other user. If you have any questions please reach out. You can optionally add Alias by making a POST request to the Create Alias API or via the subscription variant of the API if you have the Subscription ID (aka Player ID). 
## Create alias with subscription
curl -X "PATCH" "https://api.onesignal.com/apps/202d4f61-1ca9-42df-9d36-bb17d8613abf/subscriptions/a5edcddb-fe87-4a34-9936-b4e1704afb06/user/identity" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "identity": {
    "some_custom_alias": "<some_unique_identifier>"
  }
}'
Response 
{
  "identity": {
    "onesignal_id": "fd1d8faf-e758-4919-8f0f-807f6d2b216c",
    "some_custom_alias": "<some_unique_identifier>"
  }
}

​
Handling players with an External ID

If a Player in an end-user integration has an External ID set, you can add an Alias via a PATCH request to the Create Alias API. 
## Create alias
curl -X "PATCH" "https://api.onesignal.com/apps/<APP_ID>/users/by/external_id/<EXTERNAL_ID>/identity" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "identity": {
    "some_custom_alias": "<some_unique_identifier>"
  }
}'
Response 
{
  "identity": {
    "external_id": "<EXTERNAL_ID>",
    "onesignal_id": "41972ade-a8c1-4f42-a45e-728ffbb1c68c",
    "some_custom_alias": "<some_unique_identifier>"
  }
}

​
Guidance to customers via documentation

If your integration has existing records dependent on Player ID, we suggest storing External ID and or OneSignal ID (or both) on your end for a given Player ID. We will eventually be deprecating support for our previous device-centric model. You can follow instructions on how to get User-level IDs here. We suggest that you maintain documentation for the outdated version of the integration, as well as the new updated version of the integration (which will be helpful to new customers). We recommend including a call-out like this in your documentation for your OneSignal Integration, please make edits to best suit your documentation style:
OneSignal updated to a new user-centric data model. More details on this update can be found here. To continue to get the most out of the OneSignal-Partner Integration Name Here, please update to OneSignal’s latest SDKs and APIs as soon as possible:Please reach out to support@onesignal.com with any questions on this update.
⌘I