Import User Tags

Upload a CSV list of User Data Tags to set custom properties or create segments.

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

For more options on adding tags, see Set Tags: Tracking User Events and Attributes.


Trying to import email addresses or phone numbers?

(1) See Import Email Addresses guide
(2) See Import Phone Numbers guide.

Dashboard CSV Upload


  • Must have external_id and/or subscription_id column(s) with matching cases (e.g. must use "external_id" and not "external_ID").
  • Limited to UTF-8 encoding.
  • Columns must be unique.
  • No quotes.
  • Commas only, no semi-colons.
  • Max file size: 1 GB
  • Remove any + sign from your CSV file name.

CSV Column Options

These are the available properties you can set in the first row of your CSV.

Column HeadersDescription
subscription_id and/or external_idRequired At least one of these properties must be included.
If using external_id without subscription_id then the External ID must be set within the OneSignal App before any tags can be added. See Aliases & External ID for details.

When using both external_id and subscription_id, it will update the subscription with the set External ID value.
Data Tag KeysYou can include up to 1000 data tag keys. Tags are custom key : value pairs that can be unique per user. It is recommended to review the Data Tags guide before implementation.

Example CSV Column Headers:


CSV Upload Steps

Navigate to Audience > Subscriptions > Update/Import Users.

Under "Update data tags" select Upload CSV. There is also a CSV Template you can download to check your format.

After uploading check for any errors. You may need to fix the CSV then upload again if you have any errors.

If your import is taking longer than expected, please try again. It can help to break larger files down and to import multiple smaller files. If you continue to face issues, please contact our support team at [email protected].

Select the column(s) that are a data tag

Checked columns will be imported as tags. Uncheck the columns you do not want set as tags.

Advanced Settings

If you want to create a segment to send messages to this list, toggle on the Automatically create a segment for this import to set a new tag and create a segment for these users.

Delete existing data tag values when the uploaded value is null

Check this option if you want to delete the tag on the user if the key is present on the user and no value set in the CSV.

Review and click Confirm and Update when ready to import. You will get an email to the current address when the upload is finished.

Export Users Over Tag Limit

Navigate to Audience > Subscriptions > Arrow next to Export.

This 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 plan entitlement.

Export from Dashboard

Once you have selected Export you'll shortly receive an email to your account 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 whether 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.
  2. 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.