OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Onboarding With OneSignal

Guide on moving to OneSignal: Migration steps, importing devices and getting started quickly.

Moving to OneSignal? Good choice! We are happy to have you!

Whether you are moving millions of users or just getting started, this checklist walks through getting set up as fast as possible.

Quick Reference


Step 1. Setup OneSignal

Recommended: Use the SDK Integration.

  • Discussion of API-only integration

Step 2. Migrating Users to OneSignal

Optional, requires having previous subscribers.

Step 3. Connect User Data to OneSignal

Understanding OneSignal Device Records data.

Step 4. Send OneSignal Event Data & User Attributes

Add Custom User Attributes and Event data to target users with push and customize push messages.

Step 5. Outcomes

OneSignal's Advance Analytics to get more insight into your messaging campaigns.

Step 6. Sending Messages

Send messages to users! Including:

Step 1. Setup OneSignal

If you haven't done so already, head to and setup an account. It's free! If you have other team members that need access to your account, see our Account Management page.

SDK Implementation is recommended for Push and required for In-App Messages. Our SDKs are open source and easy to setup. On average, customers get setup and send their first push in under 30 minutes.

Email and SMS only integrations do not require our SDK. However, our SDKs provide methods for passing in email and sms records to your OneSignal app.

Server API Integrations

Server API-only integrations are recommended if you are not using Push Notifications or In-App Messaging channels. You can create and update email and sms records with the Add a device and Edit device APIs.

For push notifications, server API-only integration is not recommended due to each platform's requirements. One example, iOS has a standardized APNS push payload but Android has a non-standard push payload and Web Push requires Service Workers; both of which would need additional dev work to handle notifications client side. See OneSignal's Custom Push Payload here.

Also, please see our article on Build vs Buy for more details.

Step 2. Migrating Users to OneSignal

Once the OneSignal SDK is integrated, your users will automatically show in your OneSignal Audience page upon users updating and opening the App or returning to the Website.

Previously subscribed devices will not be shown a prompt, they will continue to be subscribed within OneSignal and can get push immediately.


Data Required for Push Notifications

You cannot directly import devices without the device having a push token associated with the record. A Push Token is generated through the website or mobile app when the user subscribes.

Phone number, email address, IP address are not enough information to target a user for push.



Importing Web Push Subscribers

Detailed steps to automatically and silently move subscribers to OneSignal.

Importing Mobile Push Subscribers

What to expect when transferring mobile app subscribers from another provider.

Importing Email Addresses

OneSignal supports email integrations with Sendgrid, Mandrill, and Mailgun.

Importing Phone Numbers

You can use our CSV Upload functionality to import SMS subscribers to OneSignal. You will need a Twilio account to send SMS.

Importing Web Push Subscribers

Due to the way Browsers have setup Web Push, you cannot directly migrate subscriber data from a different push provider into OneSignal. However, if your site meets the below requirements, then current subscribers will be automatically moved into OneSignal when they return to the site. No prompt will be shown and they can get push immediately upon return. They should also stop getting push from the previous provider.


  1. You must have an HTTPS website.
  2. Your users must be subscribed to the same origin you are adding to OneSignal.
  3. You must be able to add Service Worker files to your server (cannot select "My site is not fully https" in the OneSignal dashboard).

If your site does not meet these requirements, users will need to resubscribe to the site. You can continue to send push from the old provider until you are ready to fully move to OneSignal.

Importing Mobile App Subscribers

Before migrating, we recommend releasing your app with the OneSignal SDK. Any user that update and open the app with the OneSignal SDK active will automatically be added to OneSignal and will keep their current subscription status.

iOS subscribers can be imported and start getting push immediately. However, features like monitoring notification click rate wont work for devices without the OneSignal SDK active.

Android subscribers can be imported. However, they will not be able to receive notifications until they update to a version of your app with the OneSignal SDK. Therefore it's usually not beneficial to import them since they would get added to OneSignal automatically after they updated and opened your app anyway.

You can import your current subscribers using the API Add a device POST Endpoint.

Importing Custom User Attributes To OneSignal

If you are moving to OneSignal from another provider that has custom data/attributes about users, that data can be stored in OneSignal as Data Tags which are Key: Value pairs of string or number data. Data cannot be stored as arrays or objects in OneSignal.

If you track your own User IDs (like in your CRM or Database), you can add these to OneSignal user records as external_user_id's. See the Database, DMP, & CRM Integration guide for more details.


Only Import Necessary Data

OneSignal automatically collects common user data which you can view here in Data Collected by the OneSignal SDK.

For custom user data, it is recommended to only import data needed for sending messages.

List Import Option

If you map User IDs from your other provider or database as External User Ids, then you can use the Importing User Attributes option.

API Import Option

If importing this data from the API, you can map the User IDs to external_user_id: "123" and data attributes as tags: {"tag_key_1":"tag_value_1","tag_key_2":"tag_value_2"}.

SDK Import Option

If using our SDK, you can add the external_user_id with our setExternalUserId method upon login to the app/site.

For data tags, use our Tagging Methods in areas that capture the data needed for push.

Step 3. Connect User Data to OneSignal

Recommended Step

OneSignal stores user data as a device record with a unique Player ID (OneSignal User ID) when the device:

For example, a User that subscribes to Push Notifications on your website and downloads your iOS mobile app will have 2 OneSignal Player ID records. If you incorporate Email, then that single User will have 3 records: 2 Push Records (web and iOS) + 1 Email Record.

To associate multiple Player ID records together, use External User Ids to map your Database/DMP/CRM User ID to the current Player ID. The "external_user_id" can be anything like an email, username, or Database User ID.

Step 4. Send OneSignal Event Data & User Attributes

Recommended Step

Custom User data can be stored in OneSignal as Data Tags which are key : value pairs of string or number data.

Tags can be used for Segmentation and Message Personalization.

Helpful setup guides:

Step 5. Outcomes

Outcomes are OneSignal's advanced analytics that lets you track actions users take after clicking or receiving messages.

For instance, tracking "clicks" is nice, but setting Outcomes can show you how much revenue was brought in from a push. Also track user behavior after entering the app/site, like did they read/share/update/interact with a post or another user. Other tracking includes click stats like country or language or app version.

Step 6. Sending Messages

Now, you have likely subscribed users and are ready to start sending messages!


Congrats πŸŽ‰

If you have come this far you have fully integrated OneSignal and are now a master!

Updated 8 days ago

Onboarding With OneSignal

Guide on moving to OneSignal: Migration steps, importing devices and getting started quickly.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.