Generate a compressed CSV export of all of your current user data
Overview
This API can be used to generate a compressed CSV export of all of your current Subscriptions data. The file will be compressed using GZip.
How to use this API
By default, this will export all subscriptions within the app. You can filter the CSV using a segment_name
or by pulling subscriptions that are last_active_since
a specific time. For example, if you want all subscriptions that used the app since January 1st, 2024, you can set last_active_since
to be 1704067200
.
After you make this request, you will likely get a 200 OK
response with a csv_file_url
.
{
"csv_file_url": "https://onesignal.com/csv_exports/b2f7f966-d8cc-11e4-bed1-df8f05be55ba/users_184948440ec0e334728e87228011ff41_2015-11-10.csv.gz"
}
Depending on how large the file is, the URL may 404
with the following error:
This XML file does not appear to have any style information associated with it. The document tree is shown below.
<Error>
<Code>NoSuchKey</Code>
<Message>The specified key does not exist.</Message>
</Error>
On average, the file is generated at a rate of 2,000 records per second. You will need to setup a period retries depending on the file size.
After the file is generated, it can be accessible via the URL for 3 days. The filename includes random v4 uuid as part of the resource name to be unguessable.
404 error responses
You can check if the file is complete by making a GET request to the
csv_file_url
value. This file may take time to generate depending on how many records are being pulled. If the file is not ready, a 404 error will be returned. In which case, you set setup a retry to pull again after some time has passed. Otherwise the file itself will be returned.
Concurrent exports
Only one concurrent export is allowed per OneSignal account. Please ensure you have successfully downloaded the
.csv.gz
file before exporting another app.
CSV data
The CSV will contain the following data. Extra fields data maps to the extra_fields
property and are not present unless specified in the request.
Default data
Data available in the CSV without specifying extra_fields
.
- id
- identifier
- session_count
- language
- timezone
- game_version
- device_os
- device_type
- device_model
- ad_id
- tags
- last_active
- playtime
- amount_spent
- created_at
- invalid_identifier
Default CSV export definitions (click to expand)
id
id
Description
Maps to the Subscription ID. See Subscriptions for details.
identifier
identifier
Description
Maps to the token
of the subscription.
- Push subscriptions - the push token or
null
if the subscription is unsubscribed. Seeinvalid_identifier
for confirmation. - Email subscriptions - the email address.
- SMS subscriptions - the phone number.
session_count
session_count
Description
The number of times the user has opened the app. This metric can be used to identify active users and those who should be re-engaged.
language
language
Description
Should be the user's language property in ISO 639-1 format. Lower case.
Its possible the value of this is wrong depending on if a custom value was passed into the Create user or Update user APIs.
timezone
timezone
Description
This field has been deprecated and not available via this export.
game_version
game_version
Description
Maps to the subscription's app_version
property.
The version of your app that the user is currently using. This information is useful for troubleshooting, filtering users based on app versions, and ensuring compatibility.
device_os
device_os
Description
The device's operating system version. This data is beneficial for providing operating system specific support and updates.
device_type
device_type
Description
Maps to the subscription type
property.
device_type | type |
---|---|
0 | iOSPush |
1 | AndroidPush |
2 | FireOSPush |
5 | ChromePush |
7,17 | SafariPush |
11 | |
14 | SMS |
For a complete list, see device_type
integer values codes for Add a device API .
device_model
device_model
Description
The device's hardware string. Example:
Linux armv
is an Android device subscribed to web push.- See iOS Hardware Strings for details on iOS devices.
ad_id
ad_id
Description
Deprecated. The Google Advertising ID. OneSignal no longer tracks the ad_id
. This value may be present on older subscriptions or if you are using an old version of our SDK that used to collect this data. See Data Collected by the OneSignal SDK for details.
tags
tags
Description
Maps to the user's tags
object. See Tags for details.
last_active
last_active
Description
The most recent time the subscription was active in your app.
playtime
playtime
Description
Maps to session_time
subscription property. The total amount of time in seconds the user had the mobile app open.
amount_spent
amount_spent
Description
The amount the user spent on consumable in-app purchases.
created_at
created_at
Description
Maps to the first_active
time of the user. The time the user was first created. Represented as a Unix timestamp in seconds.
invalid_identifier
invalid_identifier
Description
Boolean showing whether the token
is invalid, meaning the subscription is unsubscribed from receiving messages on that channel.
t
means they areunsubscribed
f
means they aresubscribed
extra_fields
extra_fields
Additional fields that can be added to the CSV file.
- external_user_id
- onesignal_id
- location
- country
- rooted
- ip
- web_auth
- web_p256
- unsubscribed_at
- notification_types
Extra fields CSV export definitions (click to expand)
external_user_id
external_user_id
Description
Recommended. Maps to the external_id
of the user. See Users for details.
onesignal_id
onesignal_id
Description
OneSignal's user ID. See Users for details.
location
location
Description
Adds the lat
and long
coordinates if set. See Location-Triggered Notifications for details.
country
country
Description
Country code in ISO 3166-1 Alpha 2 format.
rooted
rooted
Description
Only available to OneSignal SDKs. Indicates if the Android device is rooted or jail-broken.
ip
ip
Description
The IP address if detected. Can be IPv4 or IPv6 format.
web_auth
web_auth
Description
Only available to OneSignal SDKs. The web_auth
key for web push.
web_p256
web_p256
Description
Only available to OneSignal SDKs. The web_p256
for web push.
unsubscribed_at
unsubscribed_at
Description
The last date and time the subscription was detected as unsubscribed. To get the current subscription status, check invalid_identifier
.
notification_types
notification_types
Description
Indicates the reason for the Subscription's status details. Values are updated automatically when events are detected but can also be updated programmatically with the Create user, Create subscription (by alias), and Update subscription APIs.
Notification types definitions (click to expand)
1
or positive number = Subscribed- The Subscription can receive messages on this channel.
- Can be used with
enabled
property if you are enabling messages on behalf of the user. For push Subscriptions, a validtoken
must still be set to receive push notifications. See our SDK setup docs for details.
0
,-99
= Never Subscribed- The Subscription has not subscribed to the channel yet.
-2
= Unsubscribed- The Subscription cannot receive messages on this channel.
- Can be used with
enabled
property set tofalse
if you are turning off messages on behalf of the user. Recommended value when turning off message permissions. - Automatically set when the user unsubscribes.
-3
,-5
= AndroidSupport Library Error
- Add or update your app's Android Support Library.
-4
,-8
,-11
,-12
= AndroidGoogle Play Services Library Error
- Check the logcat. See Getting a Debug Log.
- Upgrade your Google Play Services Library in your app and check the app's logcat for Google Play Services errors. See Getting a Debug Log.
-6
= AndroidInvalid Google Project Number
- The FCMv1 Sender ID doesn't match the original in which this
token
belongs. Check the app's logcat. See Getting a Debug Log.
- The FCMv1 Sender ID doesn't match the original in which this
-7
,-9
= AndroidOutdated Google Play Services App
- Update or enable the Google Play Services app on the device.
-10
= Not Subscribed.- Push Subscription uninstalled app or unsubscribed in device settings.
- Web push blocked notifications, cleared all data and workers.
-13
= iOSmissing_push_capability
.- Review the SDK setup docs to make sure all steps are implemented. See Channel setup.
-14
,-16
,-17
= iOSAPNS Errors
- The device is having an issue connecting to APNS. Check the Troubleshooting iOS guide and Getting a Debug Log.
-15
= iOSSimulator Error
- iOS Simulator required iOS 16.4+ Use a different simulator or device.
-18
= Never Prompted- The Subscription was never prompted to subscribe. This only tracks the required permission prompt and does not include in-app messages.
-19
= Prompted But Never Answered- The Subscription was prompted but didn't provide an answer.
-20
,-21
= temp_web_record. Web, pushsubscriptionchange permission revoked-22
= Manually Unsubscribed.- Permission was revoked.
-23
,-24
= WebService Worker Error
.-31
= Disabled via API.-98
= SMS Subscription awaiting double opt-in.