{ "openapi": "3.0.0", "info": { "version": "1.2.2", "title": "OneSignal", "description": "A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com", "contact": { "name": "OneSignal DevRel", "email": "devrel@onesignal.com", "url": "https://onesignal.com" }, "termsOfService": "https://onesignal.com/tos" }, "servers": [ { "url": "https://onesignal.com/api/v1" } ], "components": { "securitySchemes": { "app_key": { "type": "http", "scheme": "bearer" }, "user_key": { "type": "http", "scheme": "bearer" } }, "schemas": { "App": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "name": { "type": "string", "description": "The name of your app, as displayed on your apps list on the dashboard. This can be renamed." }, "players": { "type": "integer", "readOnly": true }, "messageable_players": { "type": "integer", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "android_gcm_sender_id": { "type": "string", "description": "Android: Your Google Project number. Also known as Sender ID.", "writeOnly": true }, "gcm_key": { "type": "string", "description": "Android: Your Google Push Messaging Auth Key", "nullable": true }, "chrome_web_origin": { "type": "string", "description": "Chrome (All Browsers except Safari) (Recommended): The URL to your website. This field is required if you wish to enable web push and specify other web push parameters.", "nullable": true }, "chrome_key": { "type": "string", "description": "Not for web push. Your Google Push Messaging Auth Key if you use Chrome Apps / Extensions.", "nullable": true }, "chrome_web_default_notification_icon": { "type": "string", "description": "Chrome (All Browsers except Safari): Your default notification icon. Should be 256x256 pixels, min 80x80.", "nullable": true }, "chrome_web_sub_domain": { "type": "string", "description": "Chrome (All Browsers except Safari): A subdomain of your choice in order to support Web Push on non-HTTPS websites. This field must be set in order for the chrome_web_gcm_sender_id property to be processed.", "nullable": true }, "apns_env": { "type": "string", "enum": [ "sandbox", "production" ], "description": "iOS: Either sandbox or production", "nullable": true }, "apns_p12": { "type": "string", "description": "iOS: Your apple push notification p12 certificate file, converted to a string and Base64 encoded.", "writeOnly": true }, "apns_p12_password": { "type": "string", "description": "iOS: Required if using p12 certificate. Password for the apns_p12 file.", "writeOnly": true }, "apns_certificates": { "type": "string", "readOnly": true, "nullable": true }, "safari_apns_certificates": { "type": "string", "readOnly": true }, "safari_apns_p12": { "type": "string", "description": "Safari: Your apple push notification p12 certificate file for Safari Push Notifications, converted to a string and Base64 encoded.", "writeOnly": true }, "safari_apns_p12_password": { "type": "string", "description": "Safari: Password for safari_apns_p12 file", "writeOnly": true }, "apns_key_id": { "type": "string", "description": "iOS: Required if using p8. Unique identifier for the p8 authentication key.", "nullable": true }, "apns_team_id": { "type": "string", "description": "iOS: Required if using p8. Team ID generated by Apple for your developer account.", "nullable": true }, "apns_bundle_id": { "type": "string", "description": "iOS: Required if using p8. Bundle ID for your app in the Apple ecosystem.", "nullable": true }, "apns_p8": { "type": "string", "description": "iOS: Required if using p8. Base64 encoded p8 key", "nullable": true }, "safari_site_origin": { "type": "string", "description": "Safari (Recommended): The hostname to your website including http(s)://", "nullable": true }, "safari_push_id": { "type": "string", "readOnly": true, "nullable": true }, "safari_icon_16_16": { "type": "string", "readOnly": true }, "safari_icon_32_32": { "type": "string", "readOnly": true }, "safari_icon_64_64": { "type": "string", "readOnly": true }, "safari_icon_128_128": { "type": "string", "readOnly": true }, "safari_icon_256_256": { "type": "string", "description": "Safari: A url for a 256x256 png notification icon. This is the only Safari icon URL you need to provide." }, "site_name": { "type": "string", "description": "All Browsers (Recommended): The Site Name. Requires both chrome_web_origin and safari_site_origin to be set to add or update it.", "nullable": true }, "basic_auth_key": { "type": "string", "readOnly": true, "nullable": true }, "organization_id": { "type": "string", "description": "The Id of the Organization you would like to add this app to.", "writeOnly": true }, "additional_data_is_root_payload": { "type": "boolean", "description": "iOS: Notification data (additional data) values will be added to the root of the apns payload when sent to the device. Ignore if you're not using any other plugins, or not using OneSignal SDK methods to read the payload.", "writeOnly": true } } }, "Apps": { "type": "array", "items": { "$ref": "#/components/schemas/App" } }, "SegmentNotificationTarget": { "type": "object", "properties": { "included_segments": { "type": "array", "description": "The segment names you want to target. Users in these segments will receive a notification. This targeting parameter is only compatible with excluded_segments.\nExample: [\"Active Users\", \"Inactive Users\"]\n", "items": { "type": "string" } }, "excluded_segments": { "type": "array", "description": "Segment that will be excluded when sending. Users in these segments will not receive a notification, even if they were included in included_segments. This targeting parameter is only compatible with included_segments.\nExample: [\"Active Users\", \"Inactive Users\"]\n", "items": { "type": "string" } } } }, "PlayerNotificationTarget": { "type": "object", "properties": { "include_player_ids": { "type": "array", "description": "Specific playerids to send your notification to. _Does not require API Auth Key.\nDo not combine with other targeting parameters. Not compatible with any other targeting parameters.\nExample: [\"1dd608f2-c6a1-11e3-851d-000c2940e62c\"]\nLimit of 2,000 entries per REST API call\n", "items": { "type": "string" }, "nullable": true, "deprecated": true }, "include_external_user_ids": { "type": "array", "description": "Target specific devices by custom user IDs assigned via API.\nNot compatible with any other targeting parameters\nExample: [\"custom-id-assigned-by-api\"]\nREQUIRED: REST API Key Authentication\nLimit of 2,000 entries per REST API call.\nNote: If targeting push, email, or sms subscribers with same ids, use with channel_for_external_user_ids to indicate you are sending a push or email or sms.\n", "items": { "type": "string" }, "nullable": true, "deprecated": true }, "include_email_tokens": { "type": "array", "description": "Recommended for Sending Emails - Target specific email addresses.\nIf an email does not correspond to an existing user, a new user will be created.\nExample: nick@catfac.ts\nLimit of 2,000 entries per REST API call\n", "items": { "type": "string" } }, "include_phone_numbers": { "type": "array", "description": "Recommended for Sending SMS - Target specific phone numbers. The phone number should be in the E.164 format. Phone number should be an existing subscriber on OneSignal. Refer our docs to learn how to add phone numbers to OneSignal.\nExample phone number: +1999999999\nLimit of 2,000 entries per REST API call\n", "items": { "type": "string" } }, "include_ios_tokens": { "type": "array", "description": "Not Recommended: Please consider using include_player_ids or include_external_user_ids instead.\nTarget using iOS device tokens.\nWarning: Only works with Production tokens.\nAll non-alphanumeric characters must be removed from each token. If a token does not correspond to an existing user, a new user will be created.\nExample: ce777617da7f548fe7a9ab6febb56cf39fba6d38203...\nLimit of 2,000 entries per REST API call\n", "items": { "type": "string" } }, "include_wp_wns_uris": { "type": "array", "description": "Not Recommended: Please consider using include_player_ids or include_external_user_ids instead.\nTarget using Windows URIs. If a token does not correspond to an existing user, a new user will be created.\nExample: http://s.notify.live.net/u/1/bn1/HmQAAACPaLDr-...\nLimit of 2,000 entries per REST API call\n", "items": { "type": "string" } }, "include_amazon_reg_ids": { "type": "array", "description": "Not Recommended: Please consider using include_player_ids or include_external_user_ids instead.\nTarget using Amazon ADM registration IDs. If a token does not correspond to an existing user, a new user will be created.\nExample: amzn1.adm-registration.v1.XpvSSUk0Rc3hTVVV...\nLimit of 2,000 entries per REST API call\n", "items": { "type": "string" } }, "include_chrome_reg_ids": { "type": "array", "description": "Not Recommended: Please consider using include_player_ids or include_external_user_ids instead.\nTarget using Chrome App registration IDs. If a token does not correspond to an existing user, a new user will be created.\nExample: APA91bEeiUeSukAAUdnw3O2RB45FWlSpgJ7Ji_...\nLimit of 2,000 entries per REST API call\n", "items": { "type": "string" } }, "include_chrome_web_reg_ids": { "type": "array", "description": "Not Recommended: Please consider using include_player_ids or include_external_user_ids instead.\nTarget using Chrome Web Push registration IDs. If a token does not correspond to an existing user, a new user will be created.\nExample: APA91bEeiUeSukAAUdnw3O2RB45FWlSpgJ7Ji_...\nLimit of 2,000 entries per REST API call\n", "items": { "type": "string" } }, "include_android_reg_ids": { "type": "array", "description": "Not Recommended: Please consider using include_player_ids or include_external_user_ids instead.\nTarget using Android device registration IDs. If a token does not correspond to an existing user, a new user will be created.\nExample: APA91bEeiUeSukAAUdnw3O2RB45FWlSpgJ7Ji_...\nLimit of 2,000 entries per REST API call\n", "items": { "type": "string" } }, "include_aliases": { "type": "object", "properties": { "alias_label": { "type": "array", "items": { "type": "string" } } }, "nullable": true }, "target_channel": { "type": "string", "enum": ["push", "email", "sms"] } } }, "NotificationTarget": { "anyOf": [ { "$ref": "#/components/schemas/SegmentNotificationTarget" }, { "$ref": "#/components/schemas/PlayerNotificationTarget" } ] }, "BasicNotification": { "allOf": [ { "$ref": "#/components/schemas/NotificationTarget" }, { "type": "object", "properties": { "id": { "type": "string" }, "value": { "type": "integer", "readOnly": true }, "name": { "type": "string", "description": "Required for SMS Messages.\nAn identifier for tracking message within the OneSignal dashboard or export analytics.\nNot shown to end user.", "writeOnly": true, "nullable": true }, "aggregation": { "type": "string", "enum": [ "sum", "count" ], "readOnly": true }, "isIos": { "type": "boolean", "description": "Indicates whether to send to all devices registered under your app's Apple iOS platform.", "writeOnly": true, "nullable": true }, "isAndroid": { "type": "boolean", "description": "Indicates whether to send to all devices registered under your app's Google Android platform.", "writeOnly": true, "nullable": true }, "isHuawei": { "type": "boolean", "description": "Indicates whether to send to all devices registered under your app's Huawei Android platform.", "writeOnly": true, "nullable": true }, "isAnyWeb": { "type": "boolean", "description": "Indicates whether to send to all subscribed web browser users, including Chrome, Firefox, and Safari.\nYou may use this instead as a combined flag instead of separately enabling isChromeWeb, isFirefox, and isSafari, though the three options are equivalent to this one.\n", "writeOnly": true, "nullable": true }, "isChromeWeb": { "type": "boolean", "writeOnly": true, "nullable": true, "description": "Indicates whether to send to all Google Chrome, Chrome on Android, and Mozilla Firefox users registered under your Chrome & Firefox web push platform." }, "isFirefox": { "type": "boolean", "writeOnly": true, "nullable": true, "description": "Indicates whether to send to all Mozilla Firefox desktop users registered under your Firefox web push platform." }, "isSafari": { "type": "boolean", "writeOnly": true, "nullable": true, "description": "Does not support iOS Safari. Indicates whether to send to all Apple's Safari desktop users registered under your Safari web push platform. Read more iOS Safari" }, "isWP_WNS": { "type": "boolean", "writeOnly": true, "nullable": true, "description": "Indicates whether to send to all devices registered under your app's Windows platform." }, "isAdm": { "type": "boolean", "writeOnly": true, "nullable": true, "description": "Indicates whether to send to all devices registered under your app's Amazon Fire platform." }, "isChrome": { "type": "boolean", "writeOnly": true, "nullable": true, "description": "This flag is not used for web push Please see isChromeWeb for sending to web push users. This flag only applies to Google Chrome Apps & Extensions.\nIndicates whether to send to all devices registered under your app's Google Chrome Apps & Extension platform.\n" }, "channel_for_external_user_ids": { "type": "string", "writeOnly": true, "description": "Indicates if the message type when targeting with include_external_user_ids for cases where an email, sms, and/or push subscribers have the same external user id.\nExample: Use the string \"push\" to indicate you are sending a push notification or the string \"email\"for sending emails or \"sms\"for sending SMS.\n" }, "app_id": { "type": "string", "description": "Required: Your OneSignal Application ID, which can be found in Keys & IDs.\nIt is a UUID and looks similar to 8250eaf6-1a58-489e-b136-7c74a864b434.\n", "writeOnly": true }, "external_id": { "type": "string", "description": "Correlation and idempotency key.\nA request received with this parameter will first look for another notification with the same external_id. If one exists, a notification will not be sent, and result of the previous operation will instead be returned. Therefore, if you plan on using this feature, it's important to use a good source of randomness to generate the UUID passed here.\nThis key is only idempotent for 30 days. After 30 days, the notification could be removed from our system and a notification with the same external_id will be sent again.\n See Idempotent Notification Requests for more details\nwriteOnly: true\n", "nullable": true }, "contents": { "allOf": [ { "$ref": "#/components/schemas/StringMap" }, { "description": "Required unless content_available=true or template_id is set.\nThe message's content (excluding the title), a map of language codes to text for each language.\nEach hash must have a language code string for a key, mapped to the localized text you would like users to receive for that language.\nThis field supports inline substitutions.\nEnglish must be included in the hash.\nExample: {\"en\": \"English Message\", \"es\": \"Spanish Message\"}\n", "writeOnly": true } ] }, "headings": { "allOf": [ { "$ref": "#/components/schemas/StringMap" }, { "description": "The message's title, a map of language codes to text for each language. Each hash must have a language code string for a key, mapped to the localized text you would like users to receive for that language.\nThis field supports inline substitutions.\nExample: {\"en\": \"English Title\", \"es\": \"Spanish Title\"}\n", "writeOnly": true } ] }, "subtitle": { "allOf": [ { "$ref": "#/components/schemas/StringMap" }, { "description": "The message's subtitle, a map of language codes to text for each language. Each hash must have a language code string for a key, mapped to the localized text you would like users to receive for that language.\nThis field supports inline substitutions.\nExample: {\"en\": \"English Subtitle\", \"es\": \"Spanish Subtitle\"}\n", "writeOnly": true } ] }, "data": { "type": "object", "description": "Channel: Push Notifications\nPlatform: Huawei\nA custom map of data that is passed back to your app. Same as using Additional Data within the dashboard. Can use up to 2048 bytes of data.\nExample: {\"abc\": 123, \"foo\": \"bar\", \"event_performed\": true, \"amount\": 12.1}\n", "writeOnly": true, "nullable": true }, "huawei_msg_type": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Huawei\nUse \"data\" or \"message\" depending on the type of notification you are sending. More details in Data & Background Notifications.\n", "writeOnly": true, "nullable": true }, "url": { "type": "string", "description": "Channel: Push Notifications\nPlatform: All\nThe URL to open in the browser when a user clicks on the notification.\nNote: iOS needs https or updated NSAppTransportSecurity in plist\nThis field supports inline substitutions.\nOmit if including web_url or app_url\nExample: https://onesignal.com\n", "writeOnly": true, "nullable": true }, "web_url": { "type": "string", "description": "Channel: Push Notifications\nPlatform: All Browsers\nSame as url but only sent to web push platforms.\nIncluding Chrome, Firefox, Safari, Opera, etc.\nExample: https://onesignal.com\n", "writeOnly": true, "nullable": true }, "app_url": { "type": "string", "description": "Channel: Push Notifications\nPlatform: All Browsers\nSame as url but only sent to web push platforms.\nIncluding iOS, Android, macOS, Windows, ChromeApps, etc.\nExample: https://onesignal.com\n", "writeOnly": true, "nullable": true }, "ios_attachments": { "type": "object", "description": "Channel: Push Notifications\nPlatform: iOS 10+\nAdds media attachments to notifications. Set as JSON object, key as a media id of your choice and the value as a valid local filename or URL. User must press and hold on the notification to view.\nDo not set mutable_content to download attachments. The OneSignal SDK does this automatically\nExample: {\"id1\": \"https://domain.com/image.jpg\"}\n", "writeOnly": true, "nullable": true }, "template_id": { "type": "string", "description": "Channel: Push Notifications\nPlatform: All\nUse a template you setup on our dashboard. The template_id is the UUID found in the URL when viewing a template on our dashboard.\nExample: be4a8044-bbd6-11e4-a581-000c2940e62c\n", "writeOnly": true, "nullable": true }, "content_available": { "type": "boolean", "description": "Channel: Push Notifications\nPlatform: iOS\nSending true wakes your app from background to run custom native code (Apple interprets this as content-available=1). Note: Not applicable if the app is in the \"force-quit\" state (i.e app was swiped away). Omit the contents field to prevent displaying a visible notification.\n", "writeOnly": true, "nullable": true }, "mutable_content": { "type": "boolean", "description": "Channel: Push Notifications\nPlatform: iOS 10+\nAlways defaults to true and cannot be turned off. Allows tracking of notification receives and changing of the notification content in your app before it is displayed. Triggers didReceive(_:withContentHandler:) on your UNNotificationServiceExtension.\n", "writeOnly": true }, "target_content_identifier": { "type": "string", "description": "Channel: Push Notifications\nPlatform: iOS 13+\nUse to target a specific experience in your App Clip, or to target your notification to a specific window in a multi-scene App.\n", "writeOnly": true, "nullable": true }, "big_picture": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Android\nPicture to display in the expanded view. Can be a drawable resource name or a URL.\n", "writeOnly": true, "nullable": true }, "huawei_big_picture": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Huawei\nPicture to display in the expanded view. Can be a drawable resource name or a URL.\n", "writeOnly": true, "nullable": true }, "adm_big_picture": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Amazon\nPicture to display in the expanded view. Can be a drawable resource name or a URL.\n", "writeOnly": true, "nullable": true }, "chrome_big_picture": { "type": "string", "description": "Channel: Push Notifications\nPlatform: ChromeApp\nLarge picture to display below the notification text. Must be a local URL.\n", "writeOnly": true, "nullable": true }, "chrome_web_image": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Chrome 56+\nSets the web push notification's large image to be shown below the notification's title and text. Please see Web Push Notification Icons.\n", "writeOnly": true, "nullable": true }, "buttons": { "type": "array", "items": { "$ref": "#/components/schemas/Button" }, "description": "Channel: Push Notifications\nPlatform: iOS 8.0+, Android 4.1+, and derivatives like Amazon Buttons to add to the notification. Icon only works for Android.\nButtons show in reverse order of array position i.e. Last item in array shows as first button on device.\nExample: [{\"id\": \"id2\", \"text\": \"second button\", \"icon\": \"ic_menu_share\"}, {\"id\": \"id1\", \"text\": \"first button\", \"icon\": \"ic_menu_send\"}]\n", "writeOnly": true, "nullable": true }, "web_buttons": { "type": "array", "items": { "$ref": "#/components/schemas/Button" }, "description": "Channel: Push Notifications\nPlatform: Chrome 48+\nAdd action buttons to the notification. The id field is required.\nExample: [{\"id\": \"like-button\", \"text\": \"Like\", \"icon\": \"http://i.imgur.com/N8SN8ZS.png\", \"url\": \"https://yoursite.com\"}, {\"id\": \"read-more-button\", \"text\": \"Read more\", \"icon\": \"http://i.imgur.com/MIxJp1L.png\", \"url\": \"https://yoursite.com\"}]\n", "writeOnly": true, "nullable": true }, "ios_category": { "type": "string", "description": "Channel: Push Notifications\nPlatform: iOS\nCategory APS payload, use with registerUserNotificationSettings:categories in your Objective-C / Swift code.\nExample: calendar category which contains actions like accept and decline\niOS 10+ This will trigger your UNNotificationContentExtension whose ID matches this category.\n", "writeOnly": true, "nullable": true }, "android_channel_id": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Android\nThe Android Oreo Notification Category to send the notification under. See the Category documentation on creating one and getting it's id.\n", "writeOnly": true }, "huawei_channel_id": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Huawei\nThe Android Oreo Notification Category to send the notification under. See the Category documentation on creating one and getting it's id.\n", "writeOnly": true, "nullable": true }, "existing_android_channel_id": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Android\nUse this if you have client side Android Oreo Channels you have already defined in your app with code.\n", "writeOnly": true }, "huawei_existing_channel_id": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Huawei\nUse this if you have client side Android Oreo Channels you have already defined in your app with code.\n", "writeOnly": true, "nullable": true }, "android_background_layout": { "type": "object", "description": "Channel: Push Notifications\nPlatform: Android\nAllowing setting a background image for the notification. This is a JSON object containing the following keys. See our Background Image documentation for image sizes.\n", "properties": { "image": { "type": "string", "description": "Asset file, android resource name, or URL to remote image." }, "headings_color": { "type": "string", "description": "Title text color ARGB Hex format. Example(Blue) \"FF0000FF\"." }, "contents_color": { "type": "string", "description": "Body text color ARGB Hex format. Example(Red) \"FFFF0000\"." } }, "writeOnly": true }, "small_icon": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Android\nIcon shown in the status bar and on the top left of the notification.\nIf not set a bell icon will be used or ic_stat_onesignal_default if you have set this resource name.\nSee: How to create small icons\n", "writeOnly": true, "nullable": true }, "huawei_small_icon": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Huawei\nIcon shown in the status bar and on the top left of the notification.\nUse an Android resource path (E.g. /drawable/small_icon).\nDefaults to your app icon if not set.\n", "writeOnly": true, "nullable": true }, "large_icon": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Android\nCan be a drawable resource name or a URL.\nSee: How to create large icons\n", "writeOnly": true, "nullable": true }, "huawei_large_icon": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Huawei\nCan be a drawable resource name or a URL.\nSee: How to create large icons\n", "writeOnly": true, "nullable": true }, "adm_small_icon": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Amazon\nIf not set a bell icon will be used or ic_stat_onesignal_default if you have set this resource name.\nSee: How to create small icons\n", "writeOnly": true, "nullable": true }, "adm_large_icon": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Amazon\nIf blank the small_icon is used. Can be a drawable resource name or a URL.\nSee: How to create large icons\n", "writeOnly": true, "nullable": true }, "chrome_web_icon": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Chrome\nSets the web push notification's icon. An image URL linking to a valid image. Common image types are supported; GIF will not animate. We recommend 256x256 (at least 80x80) to display well on high DPI devices. Firefox will also use this icon, unless you specify firefox_icon.\n", "nullable": true }, "chrome_web_badge": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Chrome\nSets the web push notification icon for Android devices in the notification shade. Please see Web Push Notification Badge.\n", "writeOnly": true, "nullable": true }, "firefox_icon": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Firefox\nNot recommended Few people need to set Firefox-specific icons. We recommend setting chrome_web_icon instead, which Firefox will also use.\nSets the web push notification's icon for Firefox. An image URL linking to a valid image. Common image types are supported; GIF will not animate. We recommend 256x256 (at least 80x80) to display well on high DPI devices.\n", "writeOnly": true, "nullable": true }, "chrome_icon": { "type": "string", "description": "Channel: Push Notifications\nPlatform: ChromeApp\nThis flag is not used for web push For web push, please see chrome_web_icon instead.\nThe local URL to an icon to use. If blank, the app icon will be used.\n", "writeOnly": true, "nullable": true }, "ios_sound": { "type": "string", "description": "Channel: Push Notifications\nPlatform: iOS\nSound file that is included in your app to play instead of the default device notification sound. Pass nil to disable vibration and sound for the notification.\nExample: \"notification.wav\"\n", "writeOnly": true, "nullable": true }, "android_sound": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Android\n⚠️Deprecated, this field doesn't work on Android 8 (Oreo) and newer devices!\nPlease use Notification Categories / Channels noted above instead to support ALL versions of Android.\nSound file that is included in your app to play instead of the default device notification sound. Pass nil to disable sound for the notification.\nNOTE: Leave off file extension for Android.\nExample: \"notification\"\n", "writeOnly": true, "nullable": true }, "huawei_sound": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Huawei\n⚠️Deprecated, this field ONLY works on EMUI 5 (Android 7 based) and older devices.\nPlease also set Notification Categories / Channels noted above to support EMUI 8 (Android 8 based) devices.\nSound file that is included in your app to play instead of the default device notification sound. NOTE: Leave off file extension for and include the full path.\n\nExample: \"/res/raw/notification\"\n", "writeOnly": true, "nullable": true }, "adm_sound": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Amazon\n⚠️Deprecated, this field doesn't work on Android 8 (Oreo) and newer devices!\nPlease use Notification Categories / Channels noted above instead to support ALL versions of Android.\nSound file that is included in your app to play instead of the default device notification sound. Pass nil to disable sound for the notification.\nNOTE: Leave off file extension for Android.\nExample: \"notification\"\n", "writeOnly": true, "nullable": true }, "wp_wns_sound": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Windows\nSound file that is included in your app to play instead of the default device notification sound.\nExample: \"notification.wav\"\n", "writeOnly": true, "nullable": true }, "android_led_color": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Android\n⚠️Deprecated, this field doesn't work on Android 8 (Oreo) and newer devices!\nPlease use Notification Categories / Channels noted above instead to support ALL versions of Android.\nSets the devices LED notification light if the device has one. ARGB Hex format.\nExample(Blue): \"FF0000FF\"\n", "writeOnly": true, "nullable": true }, "huawei_led_color": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Huawei\n⚠️Deprecated, this field ONLY works on EMUI 5 (Android 7 based) and older devices.\nPlease also set Notification Categories / Channels noted above to support EMUI 8 (Android 8 based) devices.\nSets the devices LED notification light if the device has one. RGB Hex format.\nExample(Blue): \"0000FF\"\n", "writeOnly": true, "nullable": true }, "android_accent_color": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Android\nSets the background color of the notification circle to the left of the notification text. Only applies to apps targeting Android API level 21+ on Android 5.0+ devices.\nExample(Red): \"FFFF0000\"\n", "writeOnly": true, "nullable": true }, "huawei_accent_color": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Huawei\nAccent Color used on Action Buttons and Group overflow count.\nUses RGB Hex value (E.g. #9900FF).\nDefaults to device's theme color if not set.\n", "writeOnly": true, "nullable": true }, "android_visibility": { "type": "integer", "description": "Channel: Push Notifications\nPlatform: Android 5.0_\n⚠️Deprecated, this field doesn't work on Android 8 (Oreo) and newer devices!\nPlease use Notification Categories / Channels noted above instead to support ALL versions of Android.\n1 = Public (default) (Shows the full message on the lock screen unless the user has disabled all notifications from showing on the lock screen. Please consider the user and mark private if the contents are.)\n0 = Private (Hides message contents on lock screen if the user set \"Hide sensitive notification content\" in the system settings)\n-1 = Secret (Notification does not show on the lock screen at all)\n", "writeOnly": true, "nullable": true }, "huawei_visibility": { "type": "integer", "nullable": true, "description": "Channel: Push Notifications\nPlatform: Huawei\n⚠️Deprecated, this field ONLY works on EMUI 5 (Android 7 based) and older devices.\nPlease also set Notification Categories / Channels noted above to support EMUI 8 (Android 8 based) devices.\n1 = Public (default) (Shows the full message on the lock screen unless the user has disabled all notifications from showing on the lock screen. Please consider the user and mark private if the contents are.)\n0 = Private (Hides message contents on lock screen if the user set \"Hide sensitive notification content\" in the system settings)\n-1 = Secret (Notification does not show on the lock screen at all)\n", "writeOnly": true }, "ios_badgeType": { "type": "string", "description": "Channel: Push Notifications\nPlatform: iOS\nDescribes whether to set or increase/decrease your app's iOS badge count by the ios_badgeCount specified count. Can specify None, SetTo, or Increase.\n`None` leaves the count unaffected.\n`SetTo` directly sets the badge count to the number specified in ios_badgeCount.\n`Increase` adds the number specified in ios_badgeCount to the total. Use a negative number to decrease the badge count.\n", "writeOnly": true, "nullable": true }, "ios_badgeCount": { "type": "integer", "nullable": true, "description": "Channel: Push Notifications\nPlatform: iOS\nUsed with ios_badgeType, describes the value to set or amount to increase/decrease your app's iOS badge count by.\nYou can use a negative number to decrease the badge count when used with an ios_badgeType of Increase.\n", "writeOnly": true }, "collapse_id": { "type": "string", "description": "Channel: Push Notifications\nPlatform: iOS 10+, Android\nOnly one notification with the same id will be shown on the device. Use the same id to update an existing notification instead of showing a new one. Limit of 64 characters.\n", "writeOnly": true }, "web_push_topic": { "type": "string", "description": "Channel: Push Notifications\nPlatform: All Browsers\nDisplay multiple notifications at once with different topics.\n", "nullable": true }, "apns_alert": { "type": "object", "description": "Channel: Push Notifications\nPlatform: iOS 10+\niOS can localize push notification messages on the client using special parameters such as loc-key. When using the Create Notification endpoint, you must include these parameters inside of a field called apns_alert. Please see Apple's guide on localizing push notifications to learn more.\n", "writeOnly": true, "nullable": true }, "delayed_option": { "type": "string", "description": "Channel: All\nPossible values are:\ntimezone (Deliver at a specific time-of-day in each users own timezone)\nlast-active Same as Intelligent Delivery . (Deliver at the same time of day as each user last used your app).\nIf send_after is used, this takes effect after the send_after time has elapsed.\n", "writeOnly": true, "nullable": true }, "delivery_time_of_day": { "type": "string", "description": "Channel: All\nUse with delayed_option=timezone.\nExamples: \"9:00AM\"\n\"21:45\"\n\"9:45:30\"\n", "writeOnly": true, "nullable": true }, "ttl": { "type": "integer", "nullable": true, "description": "Channel: Push Notifications\nPlatform: iOS, Android, Chrome, Firefox, Safari, ChromeWeb\nTime To Live - In seconds. The notification will be expired if the device does not come back online within this time. The default is 259,200 seconds (3 days).\nMax value to set is 2419200 seconds (28 days).\n", "writeOnly": true }, "priority": { "type": "integer", "nullable": true, "description": "Channel: Push Notifications\nPlatform: Android, Chrome, ChromeWeb\nDelivery priority through the push server (example GCM/FCM). Pass 10 for high priority or any other integer for normal priority. Defaults to normal priority for Android and high for iOS. For Android 6.0+ devices setting priority to high will wake the device out of doze mode.\n", "writeOnly": true }, "apns_push_type_override": { "type": "string", "description": "Channel: Push Notifications\nPlatform: iOS\nvalid values: voip\nSet the value to voip for sending VoIP Notifications\nThis field maps to the APNS header apns-push-type.\nNote: alert and background are automatically set by OneSignal\n", "writeOnly": true }, "throttle_rate_per_minute": { "type": "string", "description": "Channel: All\nApps with throttling enabled:\n - the parameter value will be used to override the default application throttling value set from the dashboard settings.\n - parameter value 0 indicates not to apply throttling to the notification.\n - if the parameter is not passed then the default app throttling value will be applied to the notification.\nApps with throttling disabled:\n - this parameter can be used to throttle delivery for the notification even though throttling is not enabled at the application level.\nRefer to throttling for more details.\n", "writeOnly": true, "nullable": true }, "android_group": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Android\nNotifications with the same group will be stacked together using Android's Notification Grouping feature.\n", "writeOnly": true, "nullable": true }, "android_group_message": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Android\nNote: This only works for Android 6 and older. Android 7+ allows full expansion of all message.\nSummary message to display when 2+ notifications are stacked together. Default is \"# new messages\". Include $[notif_count] in your message and it will be replaced with the current number.\nLanguages - The value of each key is the message that will be sent to users for that language. \"en\" (English) is required. The key of each hash is either a a 2 character language code or one of zh-Hans/zh-Hant for Simplified or Traditional Chinese. Read more: supported languages.\nExample: {\"en\": \"You have $[notif_count] new messages\"}\n", "writeOnly": true, "nullable": true }, "adm_group": { "type": "string", "description": "Channel: Push Notifications\nPlatform: Amazon\nNotifications with the same group will be stacked together using Android's Notification Grouping feature.\n", "writeOnly": true, "nullable": true }, "adm_group_message": { "type": "object", "description": "Channel: Push Notifications\nPlatform: Amazon\nSummary message to display when 2+ notifications are stacked together. Default is \"# new messages\". Include $[notif_count] in your message and it will be replaced with the current number. \"en\" (English) is required. The key of each hash is either a a 2 character language code or one of zh-Hans/zh-Hant for Simplified or Traditional Chinese. The value of each key is the message that will be sent to users for that language.\nExample: {\"en\": \"You have $[notif_count] new messages\"}\n", "writeOnly": true, "nullable": true }, "thread_id": { "type": "string", "description": "Channel: Push Notifications\nPlatform: iOS 12+\nThis parameter is supported in iOS 12 and above. It allows you to group related notifications together.\nIf two notifications have the same thread-id, they will both be added to the same group.\n", "writeOnly": true, "nullable": true }, "summary_arg": { "type": "string", "description": "Channel: Push Notifications\nPlatform: iOS 12+\nWhen using thread_id to create grouped notifications in iOS 12+, you can also control the summary. For example, a grouped notification can say \"12 more notifications from John Doe\".\nThe summary_arg lets you set the name of the person/thing the notifications are coming from, and will show up as \"X more notifications from summary_arg\"\n", "writeOnly": true }, "summary_arg_count": { "type": "integer", "description": "Channel: Push Notifications\nPlatform: iOS 12+\nWhen using thread_id, you can also control the count of the number of notifications in the group. For example, if the group already has 12 notifications, and you send a new notification with summary_arg_count = 2, the new total will be 14 and the summary will be \"14 more notifications from summary_arg\"\n", "writeOnly": true }, "email_subject": { "type": "string", "description": "Channel: Email\nRequired. The subject of the email.\n", "writeOnly": true, "nullable": true }, "email_body": { "type": "string", "description": "Channel: Email\nRequired unless template_id is set.\nHTML suported\nThe body of the email you wish to send. Typically, customers include their own HTML templates here. Must include [unsubscribe_url] in an tag somewhere in the email.\nNote: any malformed HTML content will be sent to users. Please double-check your HTML is valid.\n", "writeOnly": true }, "email_from_name": { "type": "string", "description": "Channel: Email\nThe name the email is from. If not specified, will default to \"from name\" set in the OneSignal Dashboard Email Settings.\n", "writeOnly": true, "nullable": true }, "email_from_address": { "type": "string", "description": "Channel: Email\nThe email address the email is from. If not specified, will default to \"from email\" set in the OneSignal Dashboard Email Settings.\n", "writeOnly": true, "nullable": true }, "email_preheader": { "type": "string", "description": "Channel: Email\nThe preheader text of the email.\nPreheader is the preview text displayed immediately after an email subject that provides additional context about the email content.\nIf not specified, will default to null.\n", "writeOnly": true, "nullable": true }, "include_unsubscribed": { "type": "boolean", "description": "Channel: Email\nDefault is `false`. This field is used to send transactional notifications. If set to `true`, this notification will also be sent to unsubscribed emails. If a `template_id` is provided, the `include_unsubscribed` value from the template will be inherited. If you are using a third-party ESP, this field requires the ESP's list of unsubscribed emails to be cleared.", "writeOnly": true }, "sms_from": { "type": "string", "description": "Channel: SMS\nPhone Number used to send SMS. Should be a registered Twilio phone number in E.164 format.\n", "writeOnly": true, "nullable": true }, "sms_media_urls": { "type": "array", "items": { "type": "string" }, "description": "Channel: SMS\nURLs for the media files to be attached to the SMS content.\nLimit: 10 media urls with a total max. size of 5MBs.\n", "writeOnly": true, "nullable": true }, "filters": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Filter" } }, "custom_data": { "type": "object", "description": "Channel: All\nJSON object that can be used as a source of message personalization data for fields that support tag variable substitution.\nPush, SMS: Can accept up to 2048 bytes of valid JSON. Email: Can accept up to 10000 bytes of valid JSON.\nExample: {\"order_id\": 123, \"currency\": \"USD\", \"amount\": 25}\n", "writeOnly": true, "nullable": true } } }, { "required": [ "app_id" ] } ] }, "Notification": { "allOf": [ { "$ref": "#/components/schemas/BasicNotification" }, { "type": "object", "properties": { "send_after": { "type": "string", "format": "date-time", "description": "Channel: All\nSchedule notification for future delivery. API defaults to UTC -1100\nExamples: All examples are the exact same date & time.\n\"Thu Sep 24 2015 14:00:00 GMT-0700 (PDT)\"\n\"September 24th 2015, 2:00:00 pm UTC-07:00\"\n\"2015-09-24 14:00:00 GMT-0700\"\n\"Sept 24 2015 14:00:00 GMT-0700\"\n\"Thu Sep 24 2015 14:00:00 GMT-0700 (Pacific Daylight Time)\"\nNote: SMS currently only supports send_after parameter.\n", "writeOnly": true, "nullable": true } } } ] }, "NotificationWithMeta": { "allOf": [ { "$ref": "#/components/schemas/BasicNotification" }, { "$ref": "#/components/schemas/DeliveryData" }, { "$ref": "#/components/schemas/OutcomesData" }, { "type": "object", "properties": { "remaining": { "type": "integer", "description": "Number of notifications that have not been sent out yet. This can mean either our system is still processing the notification or you have delayed options set." }, "successful": { "type": "integer", "description": "Number of notifications that were successfully delivered." }, "failed": { "type": "integer", "description": "Number of notifications that could not be delivered due to those devices being unsubscribed." }, "errored": { "type": "integer", "description": "Number of notifications that could not be delivered due to an error. You can find more information by viewing the notification in the dashboard." }, "converted": { "type": "integer", "description": "Number of users who have clicked / tapped on your notification." }, "queued_at": { "type": "integer", "format": "int64", "description": "Unix timestamp indicating when the notification was created." }, "send_after": { "type": "integer", "format": "int64", "description": "Unix timestamp indicating when notification delivery should begin.", "nullable": true }, "completed_at": { "type": "integer", "format": "int64", "nullable": true, "description": "Unix timestamp indicating when notification delivery completed. The delivery duration from start to finish can be calculated with completed_at - send_after." }, "platform_delivery_stats": { "$ref": "#/components/schemas/PlatformDeliveryData" }, "received": { "type": "integer", "nullable": true, "description": "Confirmed Deliveries number of devices that received the push notification. Paid Feature Only. Free accounts will see 0." }, "throttle_rate_per_minute": { "type": "integer", "nullable": true, "description": "number of push notifications sent per minute. Paid Feature Only. If throttling is not enabled for the app or the notification, and for free accounts, null is returned. Refer to Throttling for more details." } } } ] }, "Button": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "icon": { "type": "string" } }, "required": [ "id" ] }, "Buttons": { "type": "array", "items": { "$ref": "#/components/schemas/Button" } }, "StringMap": { "type": "object", "properties": { "en": { "type": "string", "description": "Text in English. Will be used as a fallback" }, "ar": { "type": "string", "description": "Text in Arabic." }, "bs": { "type": "string", "description": "Text in Bosnian." }, "bg": { "type": "string", "description": "Text in Bulgarian." }, "ca": { "type": "string", "description": "Text in Catalan." }, "zh-Hans": { "type": "string", "description": "Text in Chinese (Simplified)." }, "zh-Hant": { "type": "string", "description": "Text in Chinese (Traditional)." }, "zh": { "type": "string", "description": "Alias for zh-Hans." }, "hr": { "type": "string", "description": "Text in Croatian." }, "cs": { "type": "string", "description": "Text in Czech." }, "da": { "type": "string", "description": "Text in Danish." }, "nl": { "type": "string", "description": "Text in Dutch." }, "et": { "type": "string", "description": "Text in Estonian." }, "fi": { "type": "string", "description": "Text in Finnish." }, "fr": { "type": "string", "description": "Text in French." }, "ka": { "type": "string", "description": "Text in Georgian." }, "de": { "type": "string", "description": "Text in German." }, "el": { "type": "string", "description": "Text in Greek." }, "hi": { "type": "string", "description": "Text in Hindi." }, "he": { "type": "string", "description": "Text in Hebrew." }, "hu": { "type": "string", "description": "Text in Hungarian." }, "id": { "type": "string", "description": "Text in Indonesian." }, "it": { "type": "string", "description": "Text in Italian." }, "ja": { "type": "string", "description": "Text in Japanese." }, "ko": { "type": "string", "description": "Text in Korean." }, "lv": { "type": "string", "description": "Text in Latvian." }, "lt": { "type": "string", "description": "Text in Lithuanian." }, "ms": { "type": "string", "description": "Text in Malay." }, "nb": { "type": "string", "description": "Text in Norwegian." }, "pl": { "type": "string", "description": "Text in Polish." }, "fa": { "type": "string", "description": "Text in Persian." }, "pt": { "type": "string", "description": "Text in Portugese." }, "pa": { "type": "string", "description": "Text in Punjabi." }, "ro": { "type": "string", "description": "Text in Romanian." }, "ru": { "type": "string", "description": "Text in Russian." }, "sr": { "type": "string", "description": "Text in Serbian." }, "sk": { "type": "string", "description": "Text in Slovak." }, "es": { "type": "string", "description": "Text in Spanish." }, "sv": { "type": "string", "description": "Text in Swedish." }, "th": { "type": "string", "description": "Text in Thai." }, "tr": { "type": "string", "description": "Text in Turkish." }, "uk": { "type": "string", "description": "Text in Ukrainian." }, "vi": { "type": "string", "description": "Text in Vietnamese." } } }, "NotificationSlice": { "type": "object", "properties": { "total_count": { "type": "integer" }, "offset": { "type": "integer" }, "limit": { "type": "integer" }, "notifications": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationWithMeta" } } } }, "PlatformDeliveryData": { "type": "object", "description": "Hash of delivery statistics broken out by target device platform.", "properties": { "edge_web_push": { "$ref": "#/components/schemas/DeliveryData" }, "chrome_web_push": { "$ref": "#/components/schemas/DeliveryData" }, "firefox_web_push": { "$ref": "#/components/schemas/DeliveryData" }, "safari_web_push": { "$ref": "#/components/schemas/DeliveryData" }, "android": { "$ref": "#/components/schemas/DeliveryData" }, "ios": { "$ref": "#/components/schemas/DeliveryData" }, "sms": { "allOf": [ { "$ref": "#/components/schemas/DeliveryData" }, { "properties": { "provider_successful": { "type": "integer", "description": "Number of messages reported as delivered successfully by the SMS service provider.", "nullable": true }, "provider_failed": { "type": "integer", "description": "Number of recipients who didn't receive your message as reported by the SMS service provider.", "nullable": true }, "provider_errored": { "type": "integer", "description": "Number of errors reported by the SMS service provider.", "nullable": true } } } ] }, "email": { "allOf": [ { "$ref": "#/components/schemas/DeliveryData" }, { "properties": { "opened": { "type": "integer", "description": "Number of times an email has been opened.", "nullable": true }, "unique_opens": { "type": "integer", "description": "Number of unique recipients who have opened your email.", "nullable": true }, "clicks": { "type": "integer", "description": "Number of clicked links from your email. This can include the recipient clicking email links multiple times.", "nullable": true }, "unique_clicks": { "type": "integer", "description": "Number of unique clicks that your recipients have made on links from your email.", "nullable": true }, "bounced": { "type": "integer", "description": "Number of recipients who registered as a hard or soft bounce and didn't receive your email.", "nullable": true }, "reported_spam": { "type": "integer", "description": "Number of recipients who reported this email as spam.", "nullable": true }, "unsubscribed": { "type": "integer", "description": "Number of recipients who opted out of your emails using the unsubscribe link in this email.", "nullable": true } } } ] } } }, "DeliveryData": { "type": "object", "properties": { "successful": { "type": "integer", "description": "Number of messages delivered to push servers, mobile carriers, or email service providers.", "nullable": true }, "failed": { "type": "integer", "description": "Number of messages sent to unsubscribed devices.", "nullable": true }, "errored": { "type": "integer", "description": "Number of errors reported.", "nullable": true }, "converted": { "type": "integer", "description": "Number of messages that were clicked.", "nullable": true }, "received": { "type": "integer", "description": "Number of devices that received the message.", "nullable": true } } }, "Purchase": { "type": "object", "properties": { "sku": { "type": "string", "description": "The unique identifier of the purchased item." }, "amount": { "type": "string", "description": "The amount, in USD, spent purchasing the item." }, "iso": { "type": "string", "description": "The 3-letter ISO 4217 currency code. Required for correct storage and conversion of amount." }, "count": { "type": "number" } }, "required": [ "sku", "amount", "iso" ] }, "OutcomeData": { "type": "object", "properties": { "id": { "type": "string" }, "value": { "type": "integer" }, "aggregation": { "type": "string", "enum": [ "sum", "count" ] } }, "required": [ "id", "value", "aggregation" ] }, "OutcomesData": { "type": "object", "properties": { "outcomes": { "type": "array", "items": { "$ref": "#/components/schemas/OutcomeData" } } } }, "Filter": { "type": "object", "properties": { "field": { "type": "string", "description": "Name of the field to use as the first operand in the filter expression." }, "key": { "type": "string", "description": "If `field` is `tag`, this field is *required* to specify `key` inside the tags." }, "value": { "type": "string", "description": "Constant value to use as the second operand in the filter expression. This value is *required* when the relation operator is a binary operator." }, "relation": { "type": "string", "description": "Operator of a filter expression.", "enum": [ ">", "<", "=", "!=", "exists", "not_exists", "time_elapsed_gt", "time_elapsed_lt" ] } }, "required": [ "field", "relation" ] }, "Operator": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "OR", "AND" ], "description": "Strictly, this must be either `\"OR\"`, or `\"AND\"`. It can be used to compose Filters as part of a Filters object." } } }, "FilterExpressions": { "anyOf": [ { "$ref": "#/components/schemas/Filter" }, { "$ref": "#/components/schemas/Operator" } ] }, "Segment": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID of the segment. If left empty, it will be assigned automaticaly." }, "name": { "type": "string", "description": "Name of the segment. You'll see this name on the Web UI." }, "filters": { "type": "array", "description": "Filter or operators the segment will have. For a list of available filters with details, please see Send to Users Based on Filters.", "items": { "$ref": "#/components/schemas/FilterExpressions" } } }, "required": [ "name", "filters" ] }, "Player": { "type": "object", "properties": { "id": { "type": "string", "description": "The device's OneSignal ID", "readOnly": true }, "invalid_identifier": { "type": "boolean", "description": "If true, this is the equivalent of a user being Unsubscribed", "readOnly": true }, "app_id": { "type": "string" }, "device_type": { "type": "integer", "description": "Required\nThe device's platform:\n 0 = iOS\n 1 = Android\n 2 = Amazon\n 3 = WindowsPhone (MPNS)\n 4 = Chrome Apps / Extensions\n 5 = Chrome Web Push\n 6 = Windows (WNS)\n 7 = Safari\n 8 = Firefox\n 9 = MacOS\n 10 = Alexa\n 11 = Email\n 13 = For Huawei App Gallery Builds SDK Setup. Not for Huawei Devices using FCM\n 14 = SMS\n" }, "external_user_id": { "type": "string", "description": "a custom user ID", "nullable": true }, "external_user_id_auth_hash": { "type": "string", "description": "Only required if you have enabled Identity Verification and device_type is NOT 11 email." }, "email_auth_hash": { "description": "Email - Only required if you have enabled Identity Verification and device_type is email (11).", "type": "string" }, "identifier": { "type": "string", "description": "Recommended: For Push Notifications, this is the Push Token Identifier from Google or Apple. For Apple Push identifiers, you must strip all non alphanumeric characters.\nExamples:\niOS: 7abcd558f29d0b1f048083e2834ad8ea4b3d87d8ad9c088b33c132706ff445f0\nAndroid: APA91bHbYHk7aq-Uam_2pyJ2qbZvqllyyh2wjfPRaw5gLEX2SUlQBRvOc6sck1sa7H7nGeLNlDco8lXj83HWWwzV...\nFor Email Addresses, set the full email address email@email.com and make sure to set device_type to 11.\n", "nullable": true }, "language": { "type": "string", "description": "Language code. Typically lower case two letters, except for Chinese where it must be one of zh-Hans or zh-Hant. Example: en\n" }, "timezone": { "type": "integer", "nullable": true, "description": "Number of seconds away from UTC. Example: -28800\n" }, "game_version": { "type": "string", "description": "Version of your app. Example: 1.1\n", "nullable": true }, "device_model": { "type": "string", "description": "Device make and model. Example: iPhone5,1\n", "nullable": true }, "device_os": { "type": "string", "description": "Device operating system version. Example: 7.0.4\n", "nullable": true }, "ad_id": { "type": "string", "description": "The ad id for the device's platform:\nAndroid = Advertising Id\niOS = identifierForVendor\nWP8.0 = DeviceUniqueId\nWP8.1 = AdvertisingId\n", "nullable": true }, "sdk": { "type": "string", "description": "Name and version of the sdk/plugin that's calling this API method (if any)", "nullable": true }, "session_count": { "type": "integer", "description": "Number of times the user has played the game, defaults to 1" }, "tags": { "type": "object", "description": "Custom tags for the player. Only support string and integer key value pairs. Does not support arrays or other nested objects. Setting a tag value to null or an empty string will remove the tag. Example: {\"foo\":\"bar\",\"this\":\"that\"}\nLimitations:\n- 100 tags per call\n- Android SDK users: tags cannot be removed or changed via API if set through SDK sendTag methods.\nRecommended to only tag devices with 1 kilobyte of data\nPlease consider using your own Database to save more than 1 kilobyte of data. See: Internal Database & CRM\n", "nullable": true }, "amount_spent": { "type": "number", "description": "Amount the user has spent in USD, up to two decimal places" }, "created_at": { "type": "integer", "format": "int64", "description": "Unixtime when the player joined the game" }, "playtime": { "type": "integer", "format": "int64", "description": "Seconds player was running your app." }, "badge_count": { "type": "integer", "description": "Current iOS badge count displayed on the app icon\nNOTE: Not supported for apps created after June 2018, since badge count for apps created after this date are handled on the client.\n" }, "last_active": { "type": "integer", "description": "Unixtime when the player was last active" }, "notification_types": { "type": "integer", "description": "1 = subscribed\n-2 = unsubscribed\niOS - These values are set each time the user opens the app from the SDK. Use the SDK function set Subscription instead.\nAndroid - You may set this but you can no longer use the SDK method setSubscription later in your app as it will create synchronization issues.\n" }, "test_type": { "type": "integer", "nullable": true, "description": "This is used in deciding whether to use your iOS Sandbox or Production push certificate when sending a push when both have been uploaded. Set to the iOS provisioning profile that was used to build your app.\n1 = Development\n2 = Ad-Hoc\nOmit this field for App Store builds.\n" }, "long": { "type": "number", "description": "Longitude of the device, used for geotagging to segment on." }, "lat": { "type": "number", "description": "Latitude of the device, used for geotagging to segment on." }, "country": { "type": "string", "description": "Country code in the ISO 3166-1 Alpha 2 format" } }, "required": [ "device_type" ] }, "Players": { "type": "array", "items": { "$ref": "#/components/schemas/Player" } }, "PlayerSlice": { "type": "object", "properties": { "total_count": { "type": "integer" }, "offset": { "type": "integer" }, "limit": { "type": "integer" }, "players": { "type": "array", "items": { "$ref": "#/components/schemas/Player" } } } }, "InvalidIdentifierError": { "type": "object", "properties": { "invalid_external_user_ids": { "type": "array", "items": { "type": "string" }, "description": "Returned if using include_external_user_ids" }, "invalid_player_ids": { "type": "array", "items": { "type": "string" }, "description": "Returned if using include_player_ids and some were valid and others were not." } } }, "NoSubscribersError": { "type": "array", "items": { "type": "string", "format": "string" }, "description": "Returned if no subscribed players.\n" }, "Notification200Errors": { "oneOf": [{ "$ref": "#/components/schemas/InvalidIdentifierError" }, { "$ref": "#/components/schemas/NoSubscribersError" }] }, "UpdateLiveActivityRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Type of live activity", "enum": [ "headings", "contents", "ios_sound", "priority_level" ] }, "event": { "type": "string", "enum": [ "update", "end" ] }, "event_updates": { "type": "object" }, "dismiss_at": { "type": "number", "description": "Timestamp; only allowed if event is \"end\"" } }, "required": [ "name", "event", "event_updates" ] }, "BeginLiveActivityRequest": { "type": "object", "properties": { "push_token": { "type": "string" }, "subscription_id": { "type": "string" } }, "required": [ "push_token", "subscription_id" ] }, "IdentityObject": { "type": "object", "additionalProperties": true }, "PropertiesObject": { "type": "object", "properties": { "tags": { "type": "object", "additionalProperties": true }, "language": { "type": "string" }, "timezone_id": { "type": "string" }, "lat": { "type": "number" }, "long": { "type": "number" }, "country": { "type": "string" }, "first_active": { "type": "number" }, "last_active": { "type": "number" }, "amount_spent": { "type": "number" }, "purchases": { "type": "array", "items": { "$ref": "#/components/schemas/Purchase" } }, "ip": { "type": "string" } } }, "PropertiesDeltas": { "type": "object", "properties": { "session_time": { "type": "number" }, "session_count": { "type": "number" }, "purchases": { "type": "array", "items": { "$ref": "#/components/schemas/Purchase" } } } }, "SubscriptionObject": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "iOSPush", "AndroidPush", "FireOSPush", "ChromeExtensionPush", "ChromePush", "WindowsPush", "SafariLegacyPush", "FirefoxPush", "macOSPush", "HuaweiPush", "SafariPush", "Email", "SMS" ] }, "token": { "type": "string" }, "enabled": { "type": "boolean" }, "notification_types": { "type": "number" }, "session_time": { "type": "number" }, "session_count": { "type": "number" }, "sdk": { "type": "string" }, "device_model": { "type": "string" }, "device_os": { "type": "string" }, "rooted": { "type": "boolean" }, "test_type": { "type": "number" }, "app_version": { "type": "string" }, "net_type": { "type": "number" }, "carrier": { "type": "string" }, "web_auth": { "type": "string" }, "web_p256": { "type": "string" } } }, "User": { "type": "object", "properties": { "properties": { "$ref": "#/components/schemas/PropertiesObject" }, "identity": { "$ref": "#/components/schemas/IdentityObject" }, "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionObject" } }, "subscription_options": { "type": "object", "properties": { "retain_previous_owner": { "type": "boolean" } } } } }, "UpdateUserRequest": { "type": "object", "properties": { "properties": { "$ref": "#/components/schemas/PropertiesObject" }, "refresh_device_metadata": { "type": "boolean", "default": false }, "deltas": { "$ref": "#/components/schemas/PropertiesDeltas" } } }, "CreateNotificationSuccessResponse": { "type": "object", "properties": { "id": { "type": "string" }, "recipients": { "type": "integer", "description": "Estimated number of subscribers targetted by notification." }, "external_id": { "type": "string", "nullable": true }, "errors": { "$ref": "#/components/schemas/Notification200Errors" } } }, "CancelNotificationSuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "NotificationHistorySuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "destination_url": { "type": "string" } } }, "UpdatePlayerTagsSuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "CreateSegmentSuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string", "description": "UUID of created segment" } } }, "CreateSegmentConflictResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } } } }, "DeleteSegmentSuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "DeleteSegmentNotFoundResponse": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "CreatePlayerSuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" } } }, "DeletePlayerSuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "DeletePlayerNotFoundResponse": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "UpdatePlayerSuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "ExportPlayersSuccessResponse": { "type": "object", "properties": { "csv_file_url": { "type": "string" } } }, "UpdateLiveActivitySuccessResponse": { "type": "object", "properties": { "notification_id": { "type": "string" }, "errors": { "$ref": "#/components/schemas/Notification200Errors" } } }, "CreateUserConflictResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "title": { "type": "string" }, "meta": { "type": "object", "properties": { "conflicting_aliases": { "type": "object" } } } } } } } }, "GenericError": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "title": { "type": "string" } } } } } }, "RateLimiterError": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "title": { "type": "string" } } } } } }, "CreateSubscriptionRequestBody": { "type": "object", "properties": { "subscription": { "$ref": "#/components/schemas/SubscriptionObject" }, "retain_previous_owner": { "type": "boolean" } } }, "UpdateSubscriptionRequestBody": { "type": "object", "properties": { "subscription": { "$ref": "#/components/schemas/SubscriptionObject" } } }, "TransferSubscriptionRequestBody": { "type": "object", "properties": { "identity": { "$ref": "#/components/schemas/IdentityObject" } } }, "UserIdentityRequestBody": { "type": "object", "properties": { "identity": { "$ref": "#/components/schemas/IdentityObject" } } }, "UserIdentityResponse": { "type": "object", "properties": { "identity": { "$ref": "#/components/schemas/IdentityObject" } } }, "ExportEventsSuccessResponse": { "type": "object", "properties": { "csv_file_url": { "type": "string" } } } } }, "paths": { "/notifications": { "get": { "operationId": "get_notifications", "summary": "View notifications", "description": "View the details of multiple notifications", "parameters": [ { "in": "query", "name": "app_id", "schema": { "type": "string" }, "required": true, "description": "The app ID that you want to view notifications from" }, { "in": "query", "name": "limit", "schema": { "type": "integer" }, "required": false, "description": "How many notifications to return. Max is 50. Default is 50." }, { "in": "query", "name": "offset", "schema": { "type": "integer" }, "required": false, "description": "Page offset. Default is 0. Results are sorted by queued_at in descending order. queued_at is a representation of the time that the notification was queued at." }, { "in": "query", "name": "kind", "schema": { "type": "integer", "enum": [ 0, 1, 3 ] }, "description": "Kind of notifications returned:\n * unset - All notification types (default)\n * `0` - Dashboard only\n * `1` - API only\n * `3` - Automated only\n", "required": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationSlice" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] }, "post": { "operationId": "create_notification", "summary": "Create notification", "description": "Sends notifications to your users\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } } }, "responses": { "200": { "description": "OK, invalid_player_ids, invalid_external_user_ids or No Subscribed Players\nIf a message was successfully created, you will get a 200 response and an id for the notification.\nIf the 200 response contains \"invalid_player_ids\" or \"invalid_external_user_ids\" this will mark devices that exist in the provided app_id but are no longer subscribed.\nIf no id is returned, then a message was not created and the targeted User IDs do not exist under the provided app_id.\nAny User IDs sent in the request that do not exist under the specified app_id will be ignored.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNotificationSuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] } }, "/notifications/{notification_id}": { "get": { "operationId": "get_notification", "summary": "View notification", "description": "View the details of a single notification and outcomes associated with it", "parameters": [ { "in": "query", "name": "app_id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "notification_id", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationWithMeta" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] }, "delete": { "operationId": "cancel_notification", "summary": "Stop a scheduled or currently outgoing notification", "description": "Used to stop a scheduled or currently outgoing notification", "parameters": [ { "in": "query", "name": "app_id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "notification_id", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelNotificationSuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] } }, "/notifications/{notification_id}/history": { "post": { "operationId": "get_notification_history", "summary": "Notification History", "description": "-> View the devices sent a message - OneSignal Paid Plan Required This method will return all devices that were sent the given notification_id of an Email or Push Notification if used within 7 days of the date sent. After 7 days of the sending date, the message history data will be unavailable. After a successful response is received, the destination url may be polled until the file becomes available. Most exports are done in ~1-3 minutes, so setting a poll interval of 10 seconds should be adequate. For use cases that are not meant to be consumed by a script, an email will be sent to the supplied email address. 🚧 Requirements A OneSignal Paid Plan. Turn on Send History via OneSignal API in Settings -> Analytics. Cannot get data before this was turned on. Must be called within 7 days after sending the message. Messages targeting under 1000 recipients will not have \"sent\" events recorded, but will show \"clicked\" events. Requires your OneSignal App's REST API Key, available in Keys & IDs.", "parameters": [ { "name": "notification_id", "in": "path", "required": true, "description": "The \"id\" of the message found in the Notification object", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "get_notification_request_body", "type": "object", "required": [ "id" ], "properties": { "events": { "type": "string", "description": "-> \"sent\" - All the devices by player_id that were sent the specified notification_id. Notifications targeting under 1000 recipients will not have \"sent\" events recorded, but will show \"clicked\" events. \"clicked\" - All the devices by `player_id` that clicked the specified notification_id.", "enum": [ "sent", "clicked" ] }, "email": { "type": "string", "description": "The email address you would like the report sent." }, "app_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationHistorySuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] } }, "/apps": { "get": { "operationId": "get_apps", "summary": "View apps", "description": "View the details of all of your current OneSignal apps", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Apps" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "user_key": [] } ] }, "post": { "operationId": "create_app", "summary": "Create an app", "description": "Creates a new OneSignal app", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "user_key": [] } ] } }, "/apps/{app_id}": { "get": { "operationId": "get_app", "summary": "View an app", "description": "View the details of a single OneSignal app", "parameters": [ { "name": "app_id", "in": "path", "required": true, "description": "An app id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "user_key": [] } ] }, "put": { "operationId": "update_app", "summary": "Update an app", "description": "Updates the name or configuration settings of an existing OneSignal app", "parameters": [ { "name": "app_id", "in": "path", "required": true, "description": "An app id", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "user_key": [] } ] } }, "/apps/{app_id}/segments": { "post": { "operationId": "create_segments", "summary": "Create Segments", "description": "Create segments visible and usable in the dashboard and API - Required: OneSignal Paid Plan\nThe Create Segment method is used when you want your server to programmatically create a segment instead of using the OneSignal Dashboard UI. Just like creating Segments from the dashboard you can pass in filters with multiple \"AND\" or \"OR\" operator's.\n🚧\nDoes Not Update Segments\nThis endpoint will only create segments, it does not edit or update currently created Segments. You will need to use the Delete Segments endpoint and re-create it with this endpoint to edit.\n", "parameters": [ { "name": "app_id", "in": "path", "required": true, "description": "The OneSignal App ID for your app. Available in Keys & IDs.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Segment" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSegmentSuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSegmentConflictResponse" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] } }, "/apps/{app_id}/segments/{segment_id}": { "delete": { "operationId": "delete_segments", "summary": "Delete Segments", "description": "Delete segments (not user devices) - Required: OneSignal Paid Plan\nYou can delete a segment under your app by calling this API. You must provide an API key in the Authorization header that has admin access on the app.\nThe segment_id can be found in the URL of the segment when viewing it in the dashboard.\n", "parameters": [ { "name": "app_id", "in": "path", "required": true, "description": "The OneSignal App ID for your app. Available in Keys & IDs.", "schema": { "type": "string" } }, { "name": "segment_id", "in": "path", "required": true, "description": "The segment_id can be found in the URL of the segment when viewing it in the dashboard.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSegmentSuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSegmentNotFoundResponse" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] } }, "/apps/{app_id}/outcomes": { "get": { "operationId": "get_outcomes", "summary": "View Outcomes", "description": "View the details of all the outcomes associated with your app\n\n🚧\nRequires Authentication Key\nRequires your OneSignal App's REST API Key, available in Keys & IDs.\n\n🚧\nOutcome Data Limitations\nOutcomes are only accessible for around 30 days before deleted from our servers. You will need to export this data every month if you want to keep it.\n", "parameters": [ { "name": "app_id", "in": "path", "required": true, "description": "The OneSignal App ID for your app. Available in Keys & IDs.", "schema": { "type": "string" } }, { "name": "outcome_names", "in": "query", "required": true, "description": "Required\nComma-separated list of names and the value (sum/count) for the returned outcome data.\nNote: Clicks only support count aggregation.\nFor out-of-the-box OneSignal outcomes such as click and session duration, please use the \"os\" prefix with two underscores. For other outcomes, please use the name specified by the user.\nExample:os__session_duration.count,os__click.count,CustomOutcomeName.sum\n", "schema": { "type": "string" } }, { "name": "outcome_names[]", "in": "query", "required": false, "description": "Optional\nIf outcome names contain any commas, then please specify only one value at a time.\nExample: outcome_names[]=os__click.count&outcome_names[]=Sales, Purchase.count\nwhere \"Sales, Purchase\" is the custom outcomes with a comma in the name.\n", "schema": { "type": "string" } }, { "name": "outcome_time_range", "in": "query", "required": false, "description": "Optional\nTime range for the returned data. The values can be 1h (for the last 1 hour data), 1d (for the last 1 day data), or 1mo (for the last 1 month data).\nDefault is 1h if the parameter is omitted.\n", "schema": { "type": "string" } }, { "name": "outcome_platforms", "in": "query", "required": false, "description": "Optional\nPlatform id. Refer device's platform ids for values.\nExample:\noutcome_platform=0 for iOS\noutcome_platform=7,8 for Safari and Firefox\nDefault is data from all platforms if the parameter is omitted.\n", "schema": { "type": "string" } }, { "name": "outcome_attribution", "in": "query", "required": false, "description": "Optional\nAttribution type for the outcomes. The values can be direct or influenced or unattributed.\nExample: outcome_attribution=direct\nDefault is total (returns direct+influenced+unattributed) if the parameter is omitted.\n", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutcomesData" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] } }, "/apps/{app_id}/live_activities/{activity_id}/notifications": { "post": { "operationId": "update_live_activity", "summary": "Update a Live Activity via Push", "description": "Updates a specified live activity.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "description": "The OneSignal App ID for your app. Available in Keys & IDs.", "schema": { "type": "string" } }, { "name": "activity_id", "in": "path", "required": true, "description": "Live Activity record ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLiveActivityRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLiveActivitySuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] } }, "/apps/{app_id}/live_activities/{activity_id}/token": { "post": { "operationId": "begin_live_activity", "summary": "Start Live Activity", "description": "Starts a Live Activity", "parameters": [ { "name": "app_id", "in": "path", "required": true, "description": "The OneSignal App ID for your app. Available in Keys & IDs.", "schema": { "type": "string" } }, { "name": "activity_id", "in": "path", "required": true, "description": "Live Activity record ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeginLiveActivityRequest" } } } }, "responses": { "204": { "description": "OK" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] } }, "/apps/{app_id}/live_activities/{activity_id}/token/{subscription_id}": { "delete": { "operationId": "end_live_activity", "summary": "Stop Live Activity", "description": "Stops a Live Activity", "parameters": [ { "name": "app_id", "in": "path", "required": true, "description": "The OneSignal App ID for your app. Available in Keys & IDs.", "schema": { "type": "string" } }, { "name": "activity_id", "in": "path", "required": true, "description": "Live Activity record ID", "schema": { "type": "string" } }, { "name": "subscription_id", "in": "path", "required": true, "description": "Subscription ID", "schema": { "type": "string" } } ], "responses": { "204": { "description": "OK" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] } }, "/apps/{app_id}/users": { "post": { "operationId": "create_user", "description": "Creates a User, optionally Subscriptions owned by the User as well as Aliases.\nAliases provided in the payload will be used to look up an existing User.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "responses": { "200": { "description": "CREATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "201": { "description": "CREATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "202": { "description": "ACCEPTED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "409": { "description": "Multiple User Identity Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserConflictResponse" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "parameters": [ { "in": "path", "name": "app_id", "required": true, "schema": { "type": "string" } } ], "security": [ { "app_key": [] } ] } }, "/apps/{app_id}/users/{external_user_id}": { "put": { "operationId": "update_player_tags", "summary": "Edit tags with external user id", "description": "Update an existing device's tags in one of your OneSignal apps using the External User ID.\nWarning - Android SDK Data Synchronization\nTags added through the Android SDK tagging methods may not update if using the API to change or update the same tag.\nFor example, if you use SDK method sendTag(\"key\", \"value1\") then update the tag value to \"value2\" with this API endpoint. You will not be able to set the value back to \"value1\" through the SDK, you will need to change it to something different through the SDK to be reset.\nRecommendations if using this Endpoint on Android Mobile Apps:\n1 - Do not use the same tag keys for SDK and API updates\n2 - If you want to use the same key for both SDK and API updates, call the SDK getTags method first to update the device's tags.\nThis is only applicable on the Android Mobile App SDKs.\n📘\nDeleting Tags\nTo delete a tag, include its key and set its value to blank. Omitting a key/value will not delete it.\nFor example, if I wanted to delete two existing tags rank and category while simultaneously adding a new tag class, the tags JSON would look like the following:\n\"tags\": {\n \"rank\": \"\",\n \"category\": \"\",\n \"class\": \"my_new_value\"\n}\n", "parameters": [ { "name": "app_id", "in": "path", "required": true, "description": "The OneSignal App ID the user record is found under.", "schema": { "type": "string" } }, { "name": "external_user_id", "in": "path", "required": true, "description": "The External User ID mapped to teh device record in OneSignal. Must be actively set on the device to be updated.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "update_player_tags_request_body", "type": "object", "properties": { "tags": { "type": "object", "description": "Custom tags for the device record. Only support string key value pairs. Does not support arrays or other nested objects. Example `{\"foo\":\"bar\",\"this\":\"that\"}`.\nLimitations:\n- 100 tags per call\n- Android SDK users: tags cannot be removed or changed via API if set through SDK sendTag methods.\nRecommended to only tag devices with 1 kilobyte of ata\nPlease consider using your own Database to save more than 1 kilobyte of data. See: Internal Database & CRM\n" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePlayerTagsSuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] } }, "/apps/{app_id}/users/by/{alias_label}/{alias_id}": { "get": { "operationId": "fetch_user", "description": "Returns the User’s properties, Aliases, and Subscriptions.", "parameters": [ { "in": "path", "name": "app_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "alias_label", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "alias_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] }, "patch": { "operationId": "update_user", "description": "Updates an existing User’s properties.", "parameters": [ { "in": "path", "name": "app_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "alias_label", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "alias_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRequest" } } } }, "responses": { "202": { "description": "ACCEPTED", "content": { "application/json": { "schema": { "type": "object", "properties": { "properties": { "$ref": "#/components/schemas/PropertiesObject" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] }, "delete": { "operationId": "delete_user", "description": "Removes the User identified by (:alias_label, :alias_id), and all Subscriptions and Aliases", "parameters": [ { "in": "path", "name": "app_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "alias_label", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "alias_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } } } }, "/apps/{app_id}/users/by/{alias_label}/{alias_id}/identity": { "patch": { "operationId": "identify_user_by_alias", "description": "Upserts one or more Aliases to an existing User identified by (:alias_label, :alias_id).", "parameters": [ { "in": "path", "name": "app_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "alias_label", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "alias_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserIdentityRequestBody" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "identity": { "$ref": "#/components/schemas/IdentityObject" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] }, "get": { "operationId": "fetch_user_identity", "description": "Lists all Aliases for the User identified by (:alias_label, :alias_id).", "parameters": [ { "in": "path", "name": "app_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "alias_label", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "alias_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "identity": { "$ref": "#/components/schemas/IdentityObject" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] } }, "/apps/{app_id}/users/by/{alias_label}/{alias_id}/identity/{alias_label_to_delete}": { "delete": { "operationId": "delete_alias", "description": "Deletes an alias by alias label", "parameters": [ { "in": "path", "name": "app_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "alias_label", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "alias_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "alias_label_to_delete", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "identity": { "$ref": "#/components/schemas/IdentityObject" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] } }, "/apps/{app_id}/users/by/{alias_label}/{alias_id}/subscriptions": { "post": { "operationId": "create_subscription", "description": "Creates a new Subscription under the User provided. Useful to add email addresses and SMS numbers to the User.", "parameters": [ { "in": "path", "name": "app_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "alias_label", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "alias_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionRequestBody" } } } }, "responses": { "201": { "description": "CREATED", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription": { "$ref": "#/components/schemas/SubscriptionObject" } } } } } }, "202": { "description": "ACCEPTED", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription": { "$ref": "#/components/schemas/SubscriptionObject" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "409": { "description": "Operation is not permitted due to user having the maximum number of subscriptions assigned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] } }, "/apps/{app_id}/subscriptions/{subscription_id}": { "patch": { "operationId": "update_subscription", "description": "Updates an existing Subscription’s properties.", "parameters": [ { "in": "path", "name": "app_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "subscription_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionRequestBody" } } } }, "responses": { "202": { "description": "ACCEPTED" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] }, "delete": { "operationId": "delete_subscription", "description": "Deletes the Subscription.", "parameters": [ { "in": "path", "name": "app_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "subscription_id", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "ACCEPTED" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] } }, "/apps/{app_id}/subscriptions/{subscription_id}/user/identity": { "get": { "operationId": "fetch_aliases", "description": "Lists all Aliases for the User identified by :subscription_id.", "parameters": [ { "in": "path", "name": "app_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "subscription_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserIdentityResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } } }, "security": [ { "app_key": [] } ] }, "patch": { "operationId": "identify_user_by_subscription_id", "description": "Upserts one or more Aliases for the User identified by :subscription_id.", "parameters": [ { "in": "path", "name": "app_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "subscription_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserIdentityRequestBody" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserIdentityResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] } }, "/apps/{app_id}/subscriptions/{subscription_id}/owner": { "patch": { "operationId": "transfer_subscription", "description": "Transfers this Subscription to the User identified by the identity in the payload.", "parameters": [ { "in": "path", "name": "app_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "subscription_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferSubscriptionRequestBody" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserIdentityResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] } }, "/apps/{app_id}/subscriptions/{subscription_id}/iams": { "get": { "operationId": "get_eligible_iams", "description": "Manifest of In-App Messages the Subscription is eligible to display by the SDK.", "parameters": [ { "in": "path", "name": "app_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "subscription_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "in_app_messages": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] } }, "/players": { "get": { "operationId": "get_players", "summary": "View devices", "description": "View the details of multiple devices in one of your OneSignal apps\nUnavailable for Apps Over 80,000 Users\nFor performance reasons, this method is not available for larger apps. Larger apps should use the CSV export API endpoint, which is much more performant.\n", "parameters": [ { "in": "query", "name": "app_id", "schema": { "type": "string" }, "required": true, "description": "The app ID that you want to view players from" }, { "in": "query", "name": "limit", "schema": { "type": "integer" }, "required": false, "description": "How many devices to return. Max is 300. Default is 300" }, { "in": "query", "name": "offset", "schema": { "type": "integer" }, "required": false, "description": "Result offset. Default is 0. Results are sorted by id;" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlayerSlice" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] }, "post": { "operationId": "create_player", "summary": "Add a device", "description": "Register a new device to one of your OneSignal apps\n🚧\nDon't use this\nThis API endpoint is designed to be used from our open source Mobile and Web Push SDKs. It is not designed for developers to use it directly, unless instructed to do so by OneSignal support.\nIf you use this method instead of our SDKs, many OneSignal features such as conversion tracking, timezone tracking, language detection, and rich-push won't work out of the box. It will also make it harder to identify possible setup issues.\nThis method is used to register a new device with OneSignal.\nIf a device is already registered with the specified identifier, then this will update the existing device record instead of creating a new one.\nThe returned player is a player / user ID. Use the returned ID to send push notifications to this specific user later, or to include this player when sending to a set of users.\n🚧\niOS\nMust set test_type to 1 when building your iOS app as development. Omit this field in your production app builds.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Player" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlayerSuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] } }, "/players/{player_id}": { "delete": { "operationId": "delete_player", "summary": "Delete a user record", "description": "Delete player - Required:\nUsed to delete a single, specific Player ID record from a specific OneSignal app.\n", "parameters": [ { "name": "app_id", "in": "query", "required": true, "description": "The OneSignal App ID for your app. Available in Keys & IDs.", "schema": { "type": "string" } }, { "name": "player_id", "in": "path", "required": true, "description": "The OneSignal player_id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletePlayerSuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletePlayerNotFoundResponse" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] }, "get": { "operationId": "get_player", "summary": "View device", "description": "View the details of an existing device in one of your OneSignal apps", "parameters": [ { "name": "app_id", "in": "query", "required": true, "description": "Your app_id for this device", "schema": { "type": "string" } }, { "name": "player_id", "in": "path", "required": true, "description": "Player's OneSignal ID", "schema": { "type": "string" } }, { "name": "email_auth_hash", "in": "query", "required": false, "description": "Email - Only required if you have enabled Identity Verification and device_type is email (11).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Player" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] }, "put": { "operationId": "update_player", "summary": "Edit device", "description": "Update an existing device in one of your OneSignal apps", "parameters": [ { "name": "player_id", "in": "path", "required": true, "description": "Player's OneSignal ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Player" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePlayerSuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] } }, "/players/csv_export?app_id={app_id}": { "post": { "operationId": "export_players", "summary": "Export CSV of Players", "description": "Generate a compressed CSV export of all of your current user data\nThis method can be used to generate a compressed CSV export of all of your current user data. It is a much faster alternative than retrieving this data using the /players API endpoint.\nThe file will be compressed using GZip.\nThe file may take several minutes to generate depending on the number of users in your app.\nThe URL generated will be available for 3 days and includes random v4 uuid as part of the resource name to be unguessable.\n🚧\n403 Error Responses You can test if it is complete by making a GET request to the csv_file_url value. This file may take time to generate depending on how many device records are being pulled. If the file is not ready, a 403 error will be returned. Otherwise the file itself will be returned.\n🚧\nRequires Authentication Key\nRequires your OneSignal App's REST API Key, available in Keys & IDs.\n🚧\nConcurrent Exports\nOnly one concurrent export is allowed per OneSignal account. Please ensure you have successfully downloaded the .csv.gz file before exporting another app.\nCSV File Format:\n- Default Columns:\n | Field | Details |\n | --- | --- |\n | id | OneSignal Player Id |\n | identifier | Push Token |\n | session_count | Number of times they visited the app or site\n | language | Device language code |\n | timezone | Number of seconds away from UTC. Example: -28800 |\n | game_version | Version of your mobile app gathered from Android Studio versionCode in your App/build.gradle and iOS uses kCFBundleVersionKey in Xcode. |\n | device_os | Device Operating System Version. Example: 80 = Chrome 80, 9 = Android 9 |\n | device_type | Device Operating System Type |\n | device_model | Device Hardware String Code. Example: Mobile Web Subscribers will have `Linux armv` |\n | ad_id | Based on the Google Advertising Id for Android, identifierForVendor for iOS. OptedOut means user turned off Advertising tracking on the device. |\n | tags | Current OneSignal Data Tags on the device. |\n | last_active | Date and time the user last opened the mobile app or visited the site. |\n | playtime | Total amount of time in seconds the user had the mobile app open. |\n | amount_spent | \tMobile only - amount spent in USD on In-App Purchases. | \n | created_at | Date and time the device record was created in OneSignal. Mobile - first time they opened the app with OneSignal SDK. Web - first time the user subscribed to the site. |\n | invalid_identifier | t = unsubscribed, f = subscibed |\n | badge_count | Current number of badges on the device |\n- Extra Columns:\n | Field | Details |\n | --- | --- |\n | external_user_id | Your User Id set on the device |\n | notification_types | Notification types |\n | location | Location points (Latitude and Longitude) set on the device. |\n | country | Country code |\n | rooted | Android device rooted or not |\n | ip | IP Address of the device if being tracked. See Handling Personal Data. |\n | web_auth | Web Only authorization key. |\n | web_p256 | Web Only p256 key. |\n", "parameters": [ { "name": "app_id", "in": "path", "required": true, "description": "The app ID that you want to export devices from", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "title": "export_players_request_body", "type": "object", "properties": { "extra_fields": { "type": "array", "items": { "type": "string" }, "description": "Additional fields that you wish to include. Currently supports location, country, rooted, notification_types, ip, external_user_id, web_auth, and web_p256." }, "last_active_since": { "type": "string", "description": "Export all devices with a last_active timestamp greater than this time. Unixtime in seconds." }, "segment_name": { "type": "string", "description": "Export all devices belonging to the segment." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportPlayersSuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] } }, "/notifications/{notification_id}/export_events?app_id={app_id}": { "post": { "operationId": "export_events", "summary": "Export CSV of Events", "description": "Generate a compressed CSV report of all of the events data for a notification.\nThis will return a URL immediately upon success but it may take several minutes for the CSV to become available at that URL depending on the volume of data. Only one export can be in-progress per OneSignal account at any given time.", "parameters": [ { "name": "notification_id", "in": "path", "required": true, "description": "The ID of the notification to export events from.", "schema": { "type": "string" } }, { "name": "app_id", "in": "query", "required": true, "description": "The ID of the app that the notification belongs to.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportEventsSuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericError" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimiterError" } } } } }, "security": [ { "app_key": [] } ] } } } }