This guide walks you through the methods for importing user data into OneSignal. Whether you're migrating from another platform or adding new subscribers, we've got you covered with detailed instructions and troubleshooting tips.

You can import or update your users and subscriptions using:

• SDKs — the recommended approach for getting new users and push subscriptions.
• CSV Importer (via the OneSignal Dashboard) — best for bulk imports and updates.
• REST API — ideal for automated or programmatic updates.
• Manual Entry (via the OneSignal Dashboard) — perfect for adding a few individual users.

Depending on your needs, choose the method that fits best.

---

CSV import

You can import email addresses and phone numbers to create email and SMS subscriptions and also update their data tags, language, timezone, country, subscription status (Email and SMS only), and suppression status (Email only) properties using our CSV importer tool.

Prepare your CSV

To avoid errors during import, please ensure the following:

• UTF-8 Encoding: Your file must be encoded in UTF-8. This ensures special characters (like emojis, accents, and non-Latin scripts) are properly recognized.
• Byte Order Marker (BOM): Avoid using a Byte Order Marker at the start of the file, as this can cause parsing issues. If you're using Excel or other spreadsheet tools, be sure to save as UTF-8 without BOM.
• Non-printable Characters: Check for any hidden or non-printable characters (especially copied/pasted from other apps or editors). These can silently break the import.
• Clean Column Headers: Column headers should be clear and free of stray spaces, punctuation, or formatting.
• No Duplicate Columns: Column headers should be unique.

If you're unsure whether your file meets these standards:

• Open it in a plain text editor (like VS Code or Sublime) and click File > Reopen with Encoding > UTF-8
• Ensure it opens cleanly and characters display correctly.

Your CSV file should include at least one identifier column:

• external_id — Recommended. Used to identify Users across all their Subscriptions.
• email — Required for email subscriptions.
• phone_number — Required SMS subscriptions.
• subscription_id — Not recommended. This unique ID is created by OneSignal for a single subscription. It cannot be transferred or changed. This is used for legacy purposes or setting external_id on known subscription IDs that you may be tracking in your backend.

At this time, CSVs can only have a single identifier of each type per row. If you have a user with multiple email addresses or phone numbers, include those secondary or tertiary identifiers on a separate row with the same External ID.

📘

Pro tip: Use External ID

Include an external_id with your email phone_number and subscription_id to identify Users across all their Subscriptions, prevents duplicate users, and makes future updates easier.

Available column details:

Access CSV importer

1. Navigate to Audience > Import.
2. Click Launch CSV Importer.
3. Either drag and drop your CSV file or use the file selector
   1. Having trouble? Download the provided Example CSV to see the correct format

Mapping fields

After uploading, you'll map your CSV columns to OneSignal properties on the Map Fields step.

• If column headers match known properties, OneSignal auto-maps them.
• Always review the mappings to ensure they are correct.

Updating properties

To update an existing user's tags or other properties, the CSV must include either an external_id, a subscription ID, an email address, and/or a phone_number to identify the user to be updated.

If you are adding a new email addresses or phone number to an existing user, you must specify an external_id. Using a subscription_id will either fail or result in replacing the email address or phone number if set on an email or sms subscription. It does not transfer or change the subscription type.

Warnings

Warnings will appear if data is improperly formatted. If you see a warning about incorrectly formatted data, you have two options:

• Fix your CSV file and restart the import (recommended).
• Uncheck the problematic column to exclude it from import.

Review

On the Review page:

• Optionally, create a segment from this import. This will set a data tag to create the segment. Keep an eye on your tag and segment limits.
• Choose to delete tags where the row value is empty. For example, when using the CSV below, the tag called tag1 would be deleted for this user.
  CSV

  external_id,tag1,tag2
  2349-wefh-h34a,,"tag 2 value" 
  

📘

Pro tip: Tags & segments

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.

• After clicking Confirm and Import, you'll see success status and estimated completion time.
• An email will be sent to you when the import fully completes.

🚧

Import time estimations

The amount of time it takes to import the data is estimated on the Finish screen.

Larger files will take time to finish.

Add [email protected] to your email contacts list to make sure you get the confirmation email from us.

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.

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.

🚧

Segment count errors

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 [email protected] 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.
• Update user — Use to update user data only.
• Create subscription (by alias) — Use to add subscriptions to users only.
• Update subscription — Use to update subscription properties only.

---

Manual entry

Manually add users

Navigate to Audience > Users > Arrow next to Update/Import Users > Manually Add User.

On the next page, enter the details of the user and click Create User to create a new user. You can add the user as a test user by checking the box labelled "Add as Test User". Either a phone number or email is required to manually add a new user, which will create an SMS and/or email subscription respectively that is associated with this user:

Manually add emails

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.

Manually add phone numbers

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.