Import push subscribers

If you’re migrating from another push provider, you can import your existing push subscriber base into Pushwoosh from a CSV file. Tokens keep working as long as the app still uses the same APNs key, Firebase project, or HMS credentials. Users don’t need to reinstall the app or grant permission again.

This import registers devices with push tokens. It doesn’t create a segment. Imported devices get a CSV import tag that you can use to build one afterward. To import a list of already-registered User IDs or Hardware IDs into a segment instead, see Import a segment.

Supported platforms

Pushwoosh only imports push tokens for the platforms listed below. Any other value in device_type is skipped. See Why a row gets skipped.

The device_type column accepts two different formats, depending on where your file came from:

• A number, if your export uses OneSignal’s own platform codes.
• A word, if it’s an Amazon Pinpoint export or a file you built by hand.

Don’t mix the two formats in one file, because the same number means a different platform in each system. Pasting in a number from a non-OneSignal source can silently import devices under the wrong platform.

Platform	OneSignal device_type number	Accepted platform names
iOS	0	ios, apns, apns_sandbox, apns_voip
Android	1	android, gcm, fcm
Amazon	2	amazon, adm, fireos
Windows	6	windows, wns
macOS	9	macos, osx
Huawei (HMS)	13	huawei, hms

Rows with any other value are skipped, including:

• OneSignal’s own web push, email, and SMS device types.
• Platforms Pushwoosh doesn’t support, like the discontinued Windows Phone or Baidu push.

Web push subscriptions can’t be transferred from any provider. Those users need to re-subscribe through the Pushwoosh SDK on your website.

Prepare a CSV file

Your CSV must be under 100 MB. Name the columns exactly as shown below. Letter case does not matter. You cannot map columns in the UI, so rename any headers that don’t match:

Header	Maps to
identifier	Push token (required)
device_type	Platform (required)
external_id or external_user_id	User ID
language	Device language
tags	A JSON object of custom tag values
invalid_identifier	OneSignal’s “unsubscribed” flag. Rows flagged here are skipped

A timezone column, if present, isn’t imported, because its format differs between export versions.

Example CSV

Here’s a subscribers.csv with two devices, one using a platform name and one using a OneSignal numeric code:

identifier	device_type	external_id	language	tags
ios-token-0001	ios	user-1001	en	{"plan":"pro"}
android-token-0002	1	user-1002	en	{"plan":"free"}

Representation of subscribers.csv in plain text format:

identifier,device_type,external_id,language,tags
ios-token-0001,ios,user-1001,en,"{""plan"":""pro""}"
android-token-0002,1,user-1002,en,"{""plan"":""free""}"

ملاحظة

The tags value is a JSON object, and it contains quote marks. Building this file in Excel or Google Sheets, you don’t need to do anything, because those apps quote the cell for you automatically. Editing the file directly in a plain text editor, wrap the whole value in quotes and write every quote mark inside it as two quotes (" becomes ""), the same way the example above does.

How to import

Follow these steps to upload your CSV and register the devices in Pushwoosh.

1. Go to Audience → Import CSV and select the Import push subscribers card.

2. Select your CSV file.
3. Review the summary:
   • Total rows in the file, and how many are importable, broken down by platform.
   • Skipped rows, broken down by reason, with a link to download the skipped rows as a CSV (original columns plus a skip_reason column).
   • Custom tags detected in the tags column, with the type Pushwoosh inferred for each (string, integer, boolean, or date). If a tag name already exists in your account with a different type, it’s flagged as a conflict. You can change the type or skip that tag for this import.

4. Click Start import once you’re satisfied.

When the import finishes, you’ll see how many devices were imported, how many rows failed, and how many were skipped at preflight. Only the skipped-at-preflight count has a download link. Treat imported and failed as separate issues when you troubleshoot.

Why a row gets skipped

These are the skip reasons shown in the Map summary and in the skipped-rows CSV.

Reason	Cause
Web subscriptions	Bound to another provider’s keys. Can’t be transferred
Invalid tokens	Already rejected by APNs / FCM (OneSignal’s invalid_identifier flag)
Email addresses	Use Import email contacts instead
Phone numbers	Use Import SMS contacts instead
Duplicate tokens	The same push token appears more than once in the file. The first row wins and later rows are skipped
Unsupported platform	Platform isn’t one Pushwoosh supports (e.g. Windows Phone, Baidu)
Unknown platform	The platform value isn’t recognized at all
Empty push token	No value in the push token column

Re-importing the same file

Pushwoosh generates each imported device’s Hardware ID (HWID) from its push token, and the same token always produces the same HWID. So importing the same file again updates those existing devices instead of creating duplicates. It’s safe to re-run an import after fixing a mapping issue, or to periodically re-sync tag values from a new export.

After the import

Imported devices are tagged with CSV import, valued with the import date and time. The same tag is used by Segment import. Use it to build a segment from the imported devices, or find them individually in User Explorer.

No segment is created automatically.