​
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 — Only recommended for use when adding the External ID to an existing subscription.
subscription_id can be used as an identifier for legacy cases, or where your backend tracks this unique Subscription ID. Not recommended to be used as an identifier for adding or updating properties.
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 SDK login method. Otherwise it will reset when the user opens the app.

​
Available CSV columns

​
external_id
Any unique alphanumeric value
See external ID for more info.
​
email
Valid email addresses
Creates an Email subscription. Deduplicated if already present.
​
phone_number
Valid phone numbers
Use E.164 format like +15555551234. Creates an SMS subscription.
​
subscription_id
UUID v4 assigned by OneSignal
For legacy use only. Use when tracking OneSignal subscription IDs.
​
subscribed
`yes`, `no`
Sets subscription status for email, phone_number, and subscription_id.
​
suppressed
`true`, `false`
false removes the email from suppression lists.
​
timezone_id
IANA TZ formatted time zones
See IANA TZ.
​
country
2-character ISO 3166-2 codes
See ISO 3166-2.
​
language
2-character ISO 639-1 codes
See ISO 639-1.
​
data tags
Alphanumeric values
Up to 1,000 tags. Use column headers as keys. See Tags.

​
Importing tags from a single column

Instead of using separate column headers for each tag key, you can set a single tags header, with each user row containing a JSON map of all key-value pairs within quotes. This is especially useful if you previously exported a CSV with tags and want to re-import it without reformatting. Example header: 
external_id,email,tags
Example rows: Tags must be formatted as a JSON object enclosed in quotes. 
userA,example@email.com,"{""level"":""30"",""Color"":""teal""}"
When imported, OneSignal automatically converts each key-value pair into distinct tags for the subscription record.

​
Access CSV importer

  1. Go to Audience > Import
  2. Click Launch CSV Importer
  3. 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:
external_id,tag1,tag2
2349-wefh-h34a,,"tag 2 value"
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

Import duration depends on file size. Add 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 unique email and/or phone_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/or phone_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:
    1. The external_id you set in the CSV does not exist on any subscriptions in the OneSignal app
    2. The email and/or phone_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 the email and/or phone_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