Tags: Import User Attributes

Upload a CSV list of Data Tags to Users.

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

See Set Tags: Tracking User Events and Attributesfor all available options for getting tags into OneSignal.


Migrating or Importing Users to OneSignal?

See our Onboarding With OneSignal guide for more details on importing user 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.


Caution when combining with User Model APIs

If you are using the User Model APIs or SDKs (Mobile SDKs 5 or higher, Web SDK 16 or higher), then we advise testing this feature before importing all data. There may be cases where the External ID set with the SDK and the External ID set with the CSV do not produce matching OneSignal IDs.

If you are using User Model SDKs (Mobile SDKs 5 or higher, Web SDK 16 or higher), you should consider using the Create user or Update user API.

CSV file with onesignal_id, subscription_id and/or external_id columnsIf using external_id without onesignal_id or subscription_id then the External ID must be set within OneSignal before any tags can be set. See Aliases & External ID for details.

If using subscription_id and external_id the External ID for the subscription will update.

If using onesignal_id and external_id:
- If external_id doesn't exist, it will be set.
- If external_id does exist, no change will occur.
CSV restrictions- UTF-8 Encoding
- Must be comma separated values (,)
- Cannot use semi-colons ; or JSON
- Must remove quotes (", ')
Max File Size: 1 GBPlease 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.

Dashboard CSV Uploader

Navigate to Audience and select Update/Import Users

Under "Update users with external_id or subscription_id" select Upload CSV. 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 row and create a segment for all users 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 in each row for that column containing an empty value.

Export Users Over Tag Limit

Navigate to Audience > Subscriptions > Export.

In the secondary arrowed dropdown on Export, there is the ability to export all subscriptions with N tags. Note. N will change depending on your plan type, and is the plan-specific data tag limit. This ensures you can always remove tags for subscriptions above your current plans entitlement.


The image shows the export ability for subscriptions above 10 data tags.

Export from Dashboard

Once you have selected Export you'll shortly receive an email to your accounts email address, to begin the download. We provide this via email as you may export thousands or even millions of subscriptions.
The CSV will have two formats depending on if you are exporting all subscriptions or the subscriptions with data tags above the plan allowance:

  1. Exporting All Users: This will include all metadata and columns shown in your dashboard. Data Tags export as a JSON blob. for example.
    "first_name": "Ruby",
    "last_name": "Childs",
    "twitter": "@rubychilds"
  1. Exporting Users with 10 Tags: This provides a limited number of columns including both subscription_id and external_id (if applicable), along with data tags, where each data tag key is a column, and each row represents a value that corresponds to that id.

Editing and Deleting Your Data Tags

The subscription data comes in a CSV format, which enables you to open in Excel, Google Sheets, or Apple's Numbers. Upon opening, you should now be able to effectively edit, or delete any tags as needed.

In order to delete a tag, you can leave the data column, but leave an empty cell for the corresponding value.

When saving the altered CSV, ensure you save it as a CSV. Some editors will default to you saving it in their default format, for example, *.xslx. Our importer does not accept any other formats other than CSV.

Uploading Your Data Tags

Now your data tags have been edited and deleted, you can now upload your subscribers back into OneSignal.


What if I don't have the external_id set?

OneSignal intentionally does not automatically collect Personally Identifiable Information for data privacy reasons. If you have not enriched OneSignal with the external_id property or Data Tags, it can be difficult to map the user 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 onesignal_id and adding the external_id and other tag columns.

For proper user matching, we highly recommend adding the external_id through our client-side SDK. See Aliases & External ID for more details.