Server REST API Reference
Log InSign Up

Export subscriptions CSV

post https://api.onesignal.com/players/csv_export?app_id=

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 .

Default CSV export definitions (click to expand)

id

Description

Maps to the Subscription ID. See Subscriptions for details.

identifier

Description

Maps to the token of the subscription.

  • Push subscriptions - the push token or null if the subscription is unsubscribed. See invalid_identifier for confirmation.
  • Email subscriptions - the email address.
  • SMS subscriptions - the phone number.

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

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

Description

This field has been deprecated and not available via this export.

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

Description

The device's operating system version. This data is beneficial for providing operating system specific support and updates.

device_type

Description

Maps to the subscription type property.

device_typetype
0iOSPush
1AndroidPush
2FireOSPush
5ChromePush
7,17SafariPush
11Email
14SMS

For a complete list, see device_type integer values codes for Add a device API .

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

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

Description

Maps to the user's tags object. See Tags for details.

last_active

Description

The most recent time the subscription was active in your app.

playtime

Description

Maps to session_time subscription property. The total amount of time in seconds the user had the mobile app open.

amount_spent

Description

The amount the user spent on consumable in-app purchases.

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

Description

Boolean showing whether the token is invalid, meaning the subscription is unsubscribed from receiving messages on that channel.

  • t means they are unsubscribed
  • f means they are subscribed

extra_fields

Additional fields that can be added to the CSV file.

Extra fields CSV export definitions (click to expand)

external_user_id

Description

Recommended. Maps to the external_id of the user. See Users for details.

onesignal_id

Description

OneSignal's user ID. See Users for details.

location

Description

Adds the lat and long coordinates if set. See Location-Triggered Notifications for details.

country

Description

Country code in ISO 3166-1 Alpha 2 format.

rooted

Description

Only available to OneSignal SDKs. Indicates if the Android device is rooted or jail-broken.

ip

Description

The IP address if detected. Can be IPv4 or IPv6 format.

web_auth

Description

Only available to OneSignal SDKs. The web_auth key for web push.

web_p256

Description

Only available to OneSignal SDKs. The web_p256 for web push.

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

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 valid token 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 to false 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 = Android Support Library Error
  • -4, -8, -11, -12 = Android Google Play Services Library Error
  • -6 = Android Invalid 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.
  • -7, -9 = Android Outdated 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 = iOS missing_push_capability.
    • Review the SDK setup docs to make sure all steps are implemented. See Channel setup.
  • -14, -16, -17 = iOS APNS Errors
  • -15 = iOS Simulator 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 = Web Service Worker Error.
  • -31 = Disabled via API.
  • -98 = SMS Subscription awaiting double opt-in.


Language