Importing User Attributes or Data Tags

Upload a CSV list of Data Tags to Users.

This feature allows you to add, remove, and update data tags from device records and create segments using a CSV. This feature does not import or transfer devices into OneSignal or across OneSignal apps.


Migrating or Importing Devices to OneSignal?

See our Onboarding With OneSignal guide for more details on importing device records.

OneSignal doesn't provide an option to transfer users from one app to another. Please reach out to our Support Team with more details on your use case.


Importing Email Addresses or Phone Numbers?

See Import Email Addresses guide or Import Phone Numbers guide.



The CSV must contain a column with player_id or external_user_id for device matching. If the external_user_id was not added to OneSignal before this upload, you can include the external_user_id column with the player_id column to add that property.

  • Limited to UTF-8 Encoding
  • Columns must be unique
  • Comma Separated Values only
  • No quotes

Using the Dashboard CSV Uploader

Navigate to Audience and select Update/Import Users


shows the 'Update/Import Users' button to select from

Select Upload CSV under Update users with external_user_id or player_id. If you need an example CSV Template, there is one provided for download.


After uploading the CSV, you get a preview of the import with associated columns of data.

Which columns would you like to import as tags?

You can check and uncheck specific columns detected from the CSV. If you uncheck a column it will be ignored completely from the upload.

Automatically Creating Segments

Toggling on Automatically create a segment for this import will set another tag on every device and create a segment for all devices within the import based on the Segment Name you select.

Deleting Tags

Checking Delete identifier and tag values if columns are empty will delete all tags if the CSV row for that column contains an empty value. In the example, you will see the "tag_to_delete" column contains empty values and has the option checked. Upon upload, the records with this empty data will have the tag deleted if the tag already exists on those records.


Once finished, select Confirm and Update. You will receive an email stating your CSV Import has finished.


What if I don't have the external_user_id set?

OneSignal intentionally does not automatically collect Personally Identifiable Information for data privacy reasons. If you have not enriched OneSignal with the external_user_id property or Data Tags, it can be difficult to map the device record in OneSignal with your database user record. Based on Data Collected by the OneSignal SDK like IP Address and Device (along with any data tags you may have set), you could try Exporting User Data from OneSignal and match any data within your database to map users to a CSV and upload using the player_id and adding the external_user_id and other tag columns.

For proper device matching, we highly recommend adding the external_user_id through our client-side SDK. See External User Ids for more details.

What are the restrictions for this feature?

This is a Paid OneSignal Account. This is not available for Free tiered customers.

CSV file with a player_id and/or external_user_id columnIf using external_user_id it must be set within OneSignal before uploading.
CSV restrictions- Must have player_id and/or external_user_id column and spelled correctly
- Must be comma separated values (,)
- Cannot use semi-colons ; or JSON
- Must remove quotes (", ')

What Format should my CSV be in?

  • The first row must have player_id and/or external_user_id as columns. Please ensure you spell these correctly.
  • Do not use quotes around any parameters. Please remove all quote marks.
  • Parameters must be separated by commas. Semi-colons do not work.

Example Format:


CSV Import Max File Size

The max file size supported by our CSV import is 1 GB. Please be aware that on occasions a larger file size can potentially fail during upload due to a possible timeout. Having a fast and stable internet connection or splitting the upload into multiple files is highly encouraged.