Import
Import or update users in OneSignal using CSV uploads, REST API, or manual entry. Supports email, SMS, tags, and more for seamless user onboarding or migration.
Overview
This guide walks you through the different ways to import user data into OneSignal. Whether you’re migrating from another platform or adding new subscribers, you can import or update Users and their Subscriptions using:
- SDKs — recommended for automatically adding new users and push subscriptions.
- CSV Importer — best for bulk importing and updating users.
- REST API — great for programmatic or automated updates.
- Manual Entry — ideal for adding or editing individual users.
The page within the Audience section
CSV import
Import or update email and phone number subscriptions along with their tags, language, timezone, country, subscription status (Email/SMS), and suppression status (Email only).
CSV Import screen
Prepare your CSV
Make sure your file meets the following standards:
- UTF-8 encoding (without BOM)
- No non-printable characters
- Clean, unique column headers
- File size under 150MB
Open your file in a plain text editor like VS Code or Sublime. Reopen with UTF-8 encoding and verify proper character display.
Your file must include at least one of:
external_id
— Recommended. Identifies Users across all Subscriptions.email
— Required for email subscriptions.phone_number
— Required for SMS subscriptions.subscription_id
— Not recommended. Used for legacy cases or where your backend tracks this unique subscription ID.
Only one identifier of each type is allowed per row. To associate multiple emails or numbers with the same user, use separate rows sharing the same external_id
.
- Including
external_id
helps deduplicate users, supports updates across channels, and enables future imports. - Make sure the
external_id
is unique for each user and is the same ID set via the SDKlogin
method. Otherwise it will reset when the user opens the app.
Available CSV columns
See external ID for more info.
Creates an Email subscription. Deduplicated if already present.
Use E.164 format like +15555551234
. Creates an SMS subscription.
For legacy use only. Use when tracking OneSignal subscription IDs.
Sets subscription status (Email/SMS only).
false
removes the email from suppression lists.
See ISO 3166-2.
Access CSV importer
- Go to Audience > Import
- Click Launch CSV Importer
- Upload your CSV (drag & drop or use file selector)
Mapping fields
After upload:
- OneSignal auto-maps headers to known properties.
- Review mappings before confirming.
Updating properties
Use external_id
, email
, phone_number
, or subscription_id
to identify the user you’re updating.
To add a new email or phone number to an existing user, you must use external_id
. Do not use subscription_id
— it will not link or merge subscriptions.
Handling warnings
If OneSignal detects format issues:
- Fix the CSV and re-upload (recommended)
- Or uncheck the affected column to skip importing it
Shows error message for incorrectly formatted phone numbers
Review
On the Review screen:
- Optionally, create a segment for this import
- Optionally, delete tags with blank values:
Creating a segment makes it quick and easy to send a message to these users immediately. However, if your CSV already contains a unique tag, you don’t need to create a segment here. Just use the tag you already set to create your segment.
Options to create a segment and delete empty tag values
After clicking Confirm and Import, a status screen shows progress. You’ll get an email when import finishes.
Import confirmation with status and record counts
contact@onesignal.com
to your email contacts to ensure you receive completion emails. Email confirmation & troubleshooting
Once the CSV is finished uploading, you will get a confirmation email with the following data:
-
Subscription record(s) added
- The number of new email and/or sms subscriptions created via the CSV upload.
0
means the list did not contain uniqueemail
and/orphone_number
identifiers to create the subscriptions.
-
Subscription record(s) modified
- The number of Subscriptions where some data changed, like tags set or other properties.
- Remember that Users can have multiple Subscriptions. For example, if you uploaded a list of 10 External IDs and each were associated with 20 subscriptions, you will see
200
subscription records modified.
-
Subscription updates skipped
- The number of Subscriptions that were skipped to the provided reason.
- If you uploaded a CSV of
email
and/orphone_number
those Subscriptions were likely created. - If the reason is “due to being over your app’s tag limit” then you need to remove tags and upload again. Or upgrade your plan.
-
Not imported
-
The number of rows that did not get updated or imported.
-
Usually occurs when:
- The
external_id
you set in the CSV does not exist on any subscriptions in the OneSignal app - The
email
and/orphone_number
subscriptions already exist in the OneSignal app.
-
-
Created new segment
- The name of the segment you created if applicable.
Example email confirmation.
In the example:
100
subscriptions were created because theemail
and/orphone_number
columns included unique email addresses and/or phone numbers that currently did not exist in the OneSignal app.37814
subscriptions were updated. This is not the count of Users. Remember that users can have multiple Subscriptions.621852
rows of the CSV did not get imported. Either because they did not have External IDs that mapped to users in the OneSignal app, or the emails and/or phone numbers already existed with no unique data to set.
Currently Segments only count the number of subscribed Subscriptions. They do not count unsubscribed subscriptions, though their data has been updated.
If your segment count doesn’t match the CSV, that is because the segment is not counting the unsubscribed subscriptions at this time.
This is currently being worked on. The new and improved segmentation will be available in late 2025.
Still having issues?
Contact support@onesignal.com
and share the CSV file you uploaded along with a screenshot of the confirmation email. We are happy to take a look!
CSV import history
You can see the history of imports in Audience > Import > CSV > View previous imports (please note that the any imports made using our previous single-channel CSV import process will not be included in this list).
REST API
For importing and updating users and subscriptions via our REST API:
Create user
Recommended. Can be used to create and/or update users and subscriptions.
Create subscription (by alias)
Use to add subscriptions to users only.
Manual entry
Navigate to Audience > Subscriptions > Arrow next to Update/Import Users > Manually Add Emails to open a new modal where you can add an individual user’s email and any data tags you would like to associate with that user.
The button drop-down menu showing the Manually Add Emails option highlighted
Navigate to Audience > Subscriptions > Arrow next to Update/Import Users > Manually Add Emails to open a new modal where you can add an individual user’s email and any data tags you would like to associate with that user.
The button drop-down menu showing the Manually Add Emails option highlighted
Navigate to Audience > Subscriptions > Arrow next to Update/Import Users > Manually Add Phone Numbers to open a new modal where you can add an individual user’s phone number and any data tags you would like to associate with that user.
The button drop-down menu showing the Manually Add Phone Numbers option highlighted