Skip to main content

​
Overview

This guide covers importing or updating users and their properties within the OneSignal dashboard using a CSV or manual entry. This is helpful for bulk updates like migrating users from another platform, updating user details, and creating lists of specific users (using Tags and Segments). Options for updating users include:
  • Creating new email and/or phone number Subscriptions
  • Setting External IDs
  • Updating user properties like Tags, subscription status, language, timezone, country, and suppression status
For other options to update or create users, see:

OneSignal dashboard Audience > Import

​
CSV import

Use a CSV file to import email addresses, phone numbers, external IDs, Tags, language, timezone, country, and more! Access the CSV importer in your OneSignal dashboard by navigating to Audience > Import and clicking Launch CSV Importer.

Import CSV screen

​
CSV requirements

Make sure your file meets the following requirements:
  • UTF-8 encoding (without BOM)
  • No non-printable characters (no special characters or non-ASCII characters)
  • Clean, unique column headers
  • File size under 150MB (about 2 million rows)
  • At least one Identifier from the following:
    • external_id — Recommended. Identifies Users across all Subscriptions.
    • email — Required for creating new email subscriptions.
    • phone_number — Required for creating new SMS subscriptions.
    • subscription_id — Only recommended for cases where you track Subscription IDs on your backend and want to set an external_id. The subscription_id will not link or merge Subscriptions. This means you cannot add emails or phone numbers via subscription_id identity, you must use external_id.
Only one identifier of each type is allowed per row. To associate multiple emails or phone numbers with the same user, use separate rows sharing the same external_id.
  • Including external_id helps deduplicate Users
  • Make sure the external_id is unique for each User and is the same ID used via the SDK login method. Otherwise it will reset when the User opens the app.

​
Supported columns

​
external_id
String
Your user ID. See External ID for more info. Should be the same ID used via the SDK login method.
​
email
String
The user’s email address. Creates an Email Subscription. Deduplicated if already present in the app.
​
phone_number
String in E.164 format
The user’s phone number in E.164 format like +15555551234. Creates an SMS Subscription. Deduplicated if already present in the app.
​
subscription_id
String (UUID v4 assigned by OneSignal)
Legacy use only recommended. Use when tracking OneSignal Subscription IDs on your backend.
​
subscribed
Boolean ('yes', 'no')
Sets subscription status for email, phone_number, and subscription_id.
​
suppressed
Boolean ('true', 'false')
Use with email to add or remove from the Suppression List.
  • true adds the email to suppression list.
  • false removes the email from suppression list.
​
timezone_id
String (IANA TZ formatted time zones)
The user’s timezone in IANA TZ format.
​
country
String (2-character ISO 3166-2 codes)
The user’s country code in ISO 3166-2 format.
​
language
String (ISO 639-1 codes)
The user’s language in ISO 639-1 format.
​
tags
String
Include up to 1,000 Tags per import. Use tag keys in the column headers and tag values in the rows. Or see below Import tags from a single column.

​
Import 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.
CSV header example
external_id,email,tags
Tags must be formatted as a JSON object enclosed in 2 sets of double quotes around each key-value pair.
CSV row example
userA,example@email.com,"{""level"":""30"",""color"":""teal""}"
When imported, OneSignal automatically converts each key-value pair into distinct tags. For example, the above row would be converted to 2 tags: level:30 and color:teal.

​
Use AI to check your CSV before import

If you have errors or questions about your CSV formatting, you can describe your CSV problem to an AI tool (like Claude, ChatGPT, or similar) to automatically clean or rebuild your file before importing again.
  • Deleting tags
  • Tag formatting
  • Identify invalid formats
  • Phone number formatting
  • Data from another platform
AI prompt example for deleting unwanted tags
I want to remove all tags except "user_name" from this CSV.

Please:
1. Keep only the "user_name" tag column.
2. Remove all other tag columns.
3. Format the CSV so it matches the OneSignal import requirements in this doc:
   https://documentation.onesignal.com/docs/en/import

Here is my CSV:
[PASTE CSV]
Always test with a small sample (5-10 rows) before importing thousands of records.

​
Map fields

After upload:
  • OneSignal auto-maps headers to known properties.
  • Review mappings before confirming.
    • Use external_id, email, phone_number, and/or subscription_id as identifiers for your users. Rarely will you want to use these for tags.
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.

Import CSV Map Fields screen

​
Handling warnings

If OneSignal detects format issues:
  • Fix the CSV and re-upload (recommended)
  • Or uncheck the affected column to skip importing it

​
Review

On the Review screen, you have the options to:
  • Autoamtically create a Segment for this import.
    • This option does 2 things: 1. Sets another tag on each user, and 2. Creates a Segment with this tag.
    • In this example, the tag will be list-a and the Segment will be called list-a.
    • Be mindful of your tag and segment limits for your plan.
  • Delete tags with blank values.
    • Selecting “Yes” will automatically delete any tags with a blank value.
    • In this example, you will delete tag1 from UserA and tag2 from UserB.
    • This is helpful to remove tags and stay under your plan limits.
external_id,tag1,tag2
UserA,,"tag2value"
UserB,"tag1value",

Import CSV Review screen

After clicking Confirm and Import, a status screen shows progress. You’ll get an email when import finishes.
You finished the import process!
  • Your import duration depends on file size.
  • Check your email and add contact@onesignal.com to your email contacts to ensure you receive the email confirmation.

​
Email confirmation

Once the CSV is finished uploading, you will get a confirmation email from contact@onesignal.com 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.

​
Common troubleshooting tips

The below are common issues we see with CSV imports. We recommend trying the Use AI to check your CSV before import section above as well if you are having issues.

​
Tag limits

  • Your Tag plan limit is on a per-user basis. You can have an unlimited amount of tags per app, but each user is subject to the plan limit.
  • Example: You plan limit is 20 tags per user.
    • If the user has 19 tags already, you can only add 1 more tag to that user.
    • Your app could have 1000 different tag combinations, but each user can only have 20 at a time.
  • Recommendation:
    • Use the dashboard CSV Export to export your user’s External ID, Tags, Email and/or Phone Number.
    • Setup the CSV headers with the tags you want to delete and import those first.
    • Setup a 2nd CSV with the tags you want to keep and import those second.
    • See above Import tags from a single column section for more details.

​
Tag overwrites & deletions

During a CSV import:
  • Tags included in your CSV are overwritten with the value provided.
  • Tags not included in your CSV remain unchanged on the user record.
If a tag is still present after import, verify that:
  • the header column contains the tag key.
  • the row contains no value.
  • you selected the “Delete tags with blank values” option in the Review screen.

​
Other sources of tags being added

If deleted tags reappear after import, an integration may be automatically writing them back. Common sources include:
  • Segment
  • HubSpot
  • Journeys
  • SDK Tagging methods
  • Custom APIs or ETL pipelines
Review integration mappings and event triggers to ensure they are not overwriting your CSV changes.
Need help?
  • Try the Use AI to check your CSV before import section above.
  • 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!

​
Manual entry

You can manually add user’s email and phone number Subscriptions through the OneSignal dashboard by navigating to Audience > Users > Update/Import Users > Manually Add Users.

Manually add users screen

On the New User screen, include the data you want and select Create User.