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

Importing & Updating Users

OneSignal features - Adding, importing and/or migrating users to OneSignal. Both push and email.

Typically, users are added to OneSignal via the OneSignal SDK that is on your mobile app or website. In certain circumstances, you may also want to manually add users or user data to OneSignal. The ability to import users data will depend on the type of subscription and platform the user uses:

Data Required for Push Notifications

You cannot 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

Due to the way Web Push is setup by the browsers, you cannot directly migrate subscriber data from a different push provider to OneSignal. However, if your site is HTTPS and you can add files to your server, then there is a way to silently resubscribe users to OneSignal when they return to the site.

Requirements:

  1. You must have an HTTPS site
  2. Your users must be subscribed to the same origin/site currently (not a provided subdomain)
  3. You must be able to add files to your server (cannot select "My site is not fully https" in the OneSignal dashboard)

Then those previously subscribed users will be automatically resubscribed upon returning to your site with OneSignal installed properly.

Steps:

1 - Remove all your previous Push Provider's code from your site. Including their service workers.

2 - Follow our HTTPS Setup docs for Typical Setup or Custom Code Setup or Wordpress Setup.

IMPORTANT: Make sure to select the Auto-Resubscribe within the setup configuration. It should be selected for you automatically.

3 - Test your site to make sure you can subscribe and show up in the OneSignal Dashboard. See Troubleshooting Web Push if you are having issues. Then you can continue to send push notifications from your previous push provider to current subscribers. Upon revisiting your site, your subscribed users will now show up in your OneSignal Dashboard and will not be able to get notifications from the previous provider, so no duplicates will occur.


Importing Mobile App Subscribers

Before migrating, we recommend updating your app to have the OneSignal SDK. This way no users will be lost between the time you migrate your current subscribers and the time you update your app.

iOS - In the case of iOS devices, these subscribers can be imported, however some features like monitoring notification click rate wont work for devices with an old version of your app.

Android - In the case of Android devices, these 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 after they updated and opened your app anyway.

Import from another Mobile Push Provider or your own Database

If you are using another Mobile Push vendor, devices can be imported into OneSignal through our add device API.

If you need to bulk import 300,000 devices or more contact support providing a .csv file and we will import them over the next few days.

If you have under 300,000 devices and would like them imported, this will require a Paid Plan.

Import from Urban Airship

OneSignal supports automatically importing devices from Urban Airship. To access the Import Users page, go to App Settings and select the Import Users From Another Service tab.

When Android devices are imported from Urban Airship 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 after they updated and opened your app anyway.


Importing Email Subscribers

Email subscribers may be imported in two ways: CSV upload, or manually adding.

CSV Upload

We support uploading a list of email addresses via CSV. Click IMPORT/EXPORT -> Import/Update Users -> SELECT CSV TO UPLOAD Make sure you have an email field in the CSV file. All other fields will be added as tags.

CSV Email Upload

  • Must have email column
  • Limited to UTF-8 Encoding
  • Columns must be unique
  • 10 columns max

More details on email campaigns in Using Email FAQ

Manually Add Emails

Click IMPORT/EXPORT -> Manually Add Emails to open a new modal where you can add an individual user's email and tag data.

Adding Tags

In addition to adding a user's email, you may also add Data Tags to the user record. The Manually Add Users modal supports adding up to 10 tags.

If the email address you enter is not found in your OneSignal user list, a new user will be created. However, if the email address is found, the user will be updated with any tags that you add here. If a user already has a tag with a particular key (e.g. levels_completed), any value you add here will replace the value the user record previously had.


Updating Users

Required: OneSignal Paid Plan
Using a CSV, you can upload a list of Player Ids and/or External User Ids along with tag data to add/update tags and external user ids that may be missing.

In Users > All Users select IMPORT/EXPORT > Import/Update Users > SELECT CSV TO UPLOAD

Upload the .csv file that has either a player_id and/or an external_user_id column (one or both is required). Other columns will be the Data Tags where the top column is the "tag key" and each row under is the "tag value".

Format errors

Make sure you do not have quotes around the player_id, external_user_id and actual user ids in the csv file.

Example Format:

You will get a preview of the import. If the player_id or external_user_id column was not detect or entered incorrectly, it will tell you.

If you decide not to add specific tags, you can check them on or off.

You can automatically create a new segment for the imported list. This adds a tag to the newly imported list and auto-creates a segment based on the value you put.

You can delete tag values if a column is empty. See Removing Tags From A List for more.

Once you Confirm and Import you will get an email stating your CSV Import has finished.

Removing Tags From List

Get List of Player ids

You can use our Exporting Data guide to get a list of player ids.

Create CSV

In the CSV, make sure to have one column of player_id and/or external_user_id the other columns will be the tag keys to delete. For example if the tags to delete keys are key_1, key_2, etc, then each key needs to be in the first row:

Upload CSV to OneSignal

To delete the tags, select Delete identifier and tag values if columns are empty

Press Confirm and Import, we will email you when finished!


Importing & Updating Users


OneSignal features - Adding, importing and/or migrating users to OneSignal. Both push and email.

Suggested Edits are limited on API Reference Pages

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