OneSignal Notifications API
The Notifications API from OneSignal — 4 operation(s) for notifications.
OpenAPI Specification
openapi: 3.0.0
info:
contact:
email: devrel@onesignal.com
name: OneSignal DevRel
url: https://onesignal.com
description: A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
termsOfService: https://onesignal.com/tos
title: OneSignal Notifications API
version: 5.5.0
servers:
- url: https://api.onesignal.com
tags:
- name: Notifications
paths:
/notifications:
get:
description: View the details of multiple notifications
operationId: get_notifications
parameters:
- description: The app ID that you want to view notifications from
explode: true
in: query
name: app_id
required: true
schema:
type: string
style: form
- description: How many notifications to return. Max is 50. Default is 50.
explode: true
in: query
name: limit
required: false
schema:
type: integer
style: form
- 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.
explode: true
in: query
name: offset
required: false
schema:
type: integer
style: form
- description: "Kind of notifications returned:\n * unset - All notification types (default)\n * `0` - Dashboard only\n * `1` - API only\n * `3` - Automated only\n"
explode: true
in: query
name: kind
required: false
schema:
enum:
- 0
- 1
- 3
type: integer
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationSlice'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
description: Bad Request
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
description: Rate Limit Exceeded
security:
- rest_api_key: []
summary: View notifications
tags:
- Notifications
post:
description: 'Sends notifications to your users.
**Target by External ID (push example):** set `include_aliases` to `{ "external_id": ["your-user-id"] }` and set `target_channel` to `push` (or `email` / `sms` for those channels). Alias object keys must match API labels exactly (for example `external_id`, not camelCase).
**Do not confuse** the notification-level `external_id` field with External ID targeting: top-level `external_id` / `idempotency_key` are for idempotent notification requests only, not for selecting recipients.
**Targeting compatibility:** `include_aliases` must not be combined with other targeting modes (segments, filters, subscription IDs, legacy player IDs, etc.). Clients should send only one targeting strategy per request.
'
operationId: create_notification
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Notification'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CreateNotificationSuccessResponse'
description: 'OK, invalid_aliases, or No Subscribed Players
If a message was successfully created, you will get a 200 response with a non-empty `id` for the notification.
If the 200 response contains `invalid_aliases`, that marks devices that exist in the provided app_id but are no longer subscribed.
If `id` is an empty string, no notification was created: check the `errors` array (for example messages such as "All included players are not subscribed") even though HTTP status is still 200. This can happen when alias keys are wrong, External IDs do not resolve to subscribed users, or other validation issues.
If no id is returned, then a message was not created and the targeted User IDs do not exist under the provided app_id.
Any User IDs sent in the request that do not exist under the specified app_id will be ignored.
'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
description: Bad Request
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
description: Rate Limit Exceeded
security:
- rest_api_key: []
summary: Create notification
x-onesignal-flat-notification-example: true
tags:
- Notifications
/notifications/{notification_id}:
delete:
description: Used to stop a scheduled or currently outgoing notification
operationId: cancel_notification
parameters:
- explode: true
in: query
name: app_id
required: true
schema:
type: string
style: form
- explode: false
in: path
name: notification_id
required: true
schema:
type: string
style: simple
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GenericSuccessBoolResponse'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
description: Bad Request
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
description: Not Found
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
description: Rate Limit Exceeded
security:
- rest_api_key: []
summary: Stop a scheduled or currently outgoing notification
tags:
- Notifications
get:
description: View the details of a single notification and outcomes associated with it
operationId: get_notification
parameters:
- explode: true
in: query
name: app_id
required: true
schema:
type: string
style: form
- explode: false
in: path
name: notification_id
required: true
schema:
type: string
style: simple
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationWithMeta'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
description: Bad Request
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
description: Not Found
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
description: Rate Limit Exceeded
security:
- rest_api_key: []
summary: View notification
tags:
- Notifications
/notifications/{notification_id}/history:
post:
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.
operationId: get_notification_history
parameters:
- description: The "id" of the message found in the Notification object
explode: false
in: path
name: notification_id
required: true
schema:
type: string
style: simple
requestBody:
$ref: '#/components/requestBodies/get_notification_history_request_body'
content:
application/json:
schema:
properties:
events:
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
type: string
email:
description: The email address you would like the report sent.
type: string
app_id:
type: string
required:
- id
title: get_notification_history_request_body
type: object
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationHistorySuccessResponse'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
description: Bad Request
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
description: Not Found
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
description: Rate Limit Exceeded
security:
- rest_api_key: []
summary: Notification History
tags:
- Notifications
/notifications/{notification_id}/export_events?app_id={app_id}:
post:
description: 'Generate a compressed CSV report of all of the events data for a notification.
This 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.'
operationId: export_events
parameters:
- description: The ID of the notification to export events from.
explode: false
in: path
name: notification_id
required: true
schema:
type: string
style: simple
- description: The ID of the app that the notification belongs to.
explode: true
in: query
name: app_id
required: true
schema:
type: string
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ExportEventsSuccessResponse'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
description: Bad Request
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
description: Not Found
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
description: Rate Limit Exceeded
security:
- rest_api_key: []
summary: Export CSV of Events
tags:
- Notifications
components:
schemas:
PlatformDeliveryData_sms_allOf:
properties:
provider_successful:
description: Number of messages reported as delivered successfully by the SMS service provider.
nullable: true
type: integer
provider_failed:
description: Number of recipients who didn't receive your message as reported by the SMS service provider.
nullable: true
type: integer
provider_errored:
description: Number of errors reported by the SMS service provider.
nullable: true
type: integer
NotificationSlice:
example:
offset: 6
total_count: 0
limit: 1
notifications:
- null
- null
properties:
total_count:
type: integer
offset:
type: integer
limit:
type: integer
notifications:
items:
$ref: '#/components/schemas/NotificationWithMeta'
type: array
type: object
NotificationTarget:
anyOf:
- $ref: '#/components/schemas/SegmentNotificationTarget'
- $ref: '#/components/schemas/SubscriptionNotificationTarget'
ExportEventsSuccessResponse:
example:
csv_file_url: csv_file_url
properties:
csv_file_url:
type: string
type: object
Button:
properties:
id:
type: string
text:
type: string
icon:
type: string
required:
- id
type: object
CreateNotificationSuccessResponse:
example:
external_id: external_id
id: id
errors: ''
properties:
id:
description: Notification identifier when the request created a notification. An empty string means no notification was created; read `errors` for details (HTTP may still be 200).
type: string
external_id:
description: Optional correlation / idempotency-related value from the API response. This is not the end-user External ID used for targeting recipients (that lives under `include_aliases.external_id`).
nullable: true
type: string
errors:
description: 'Polymorphic field: may be an array of human-readable strings and/or an object (for example with `invalid_aliases`, `invalid_external_user_ids`, or `invalid_player_ids`) depending on the API response; HTTP may still be 200 with partial success. Typed SDKs model this loosely so both shapes deserialize.'
type: object
SubscriptionNotificationTarget:
properties:
include_subscription_ids:
description: 'Specific subscription ids to send your notification to. _Does not require API Auth Key._
Not compatible with any other targeting parameters.
Example: ["1dd608f2-c6a1-11e3-851d-000c2940e62c"]
Limit of 2,000 entries per REST API call
'
items:
type: string
nullable: true
type: array
include_email_tokens:
description: 'Recommended for Sending Emails - Target specific email addresses.
If an email does not correspond to an existing user, a new user will be created.
Example: nick@catfac.ts
Limit of 2,000 entries per REST API call
'
items:
type: string
type: array
include_phone_numbers:
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.
Example phone number: +1999999999
Limit of 2,000 entries per REST API call
'
items:
type: string
type: array
include_ios_tokens:
description: 'Not Recommended: Please consider using include_subscription_ids or include_aliases instead.
Target using iOS device tokens.
Warning: Only works with Production tokens.
All 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.
Example: ce777617da7f548fe7a9ab6febb56cf39fba6d38203...
Limit of 2,000 entries per REST API call
'
items:
type: string
type: array
include_wp_wns_uris:
description: 'Not Recommended: Please consider using include_subscription_ids or include_aliases instead.
Target using Windows URIs. If a token does not correspond to an existing user, a new user will be created.
Example: http://s.notify.live.net/u/1/bn1/HmQAAACPaLDr-...
Limit of 2,000 entries per REST API call
'
items:
type: string
type: array
include_amazon_reg_ids:
description: 'Not Recommended: Please consider using include_subscription_ids or include_aliases instead.
Target using Amazon ADM registration IDs. If a token does not correspond to an existing user, a new user will be created.
Example: amzn1.adm-registration.v1.XpvSSUk0Rc3hTVVV...
Limit of 2,000 entries per REST API call
'
items:
type: string
type: array
include_chrome_reg_ids:
description: 'Not Recommended: Please consider using include_subscription_ids or include_aliases instead.
Target using Chrome App registration IDs. If a token does not correspond to an existing user, a new user will be created.
Example: APA91bEeiUeSukAAUdnw3O2RB45FWlSpgJ7Ji_...
Limit of 2,000 entries per REST API call
'
items:
type: string
type: array
include_chrome_web_reg_ids:
description: 'Not Recommended: Please consider using include_subscription_ids or include_aliases instead.
Target using Chrome Web Push registration IDs. If a token does not correspond to an existing user, a new user will be created.
Example: APA91bEeiUeSukAAUdnw3O2RB45FWlSpgJ7Ji_...
Limit of 2,000 entries per REST API call
'
items:
type: string
type: array
include_android_reg_ids:
description: 'Not Recommended: Please consider using include_subscription_ids or include_aliases instead.
Target using Android device registration IDs. If a token does not correspond to an existing user, a new user will be created.
Example: APA91bEeiUeSukAAUdnw3O2RB45FWlSpgJ7Ji_...
Limit of 2,000 entries per REST API call
'
items:
type: string
type: array
include_aliases:
additionalProperties:
items:
type: string
type: array
description: 'Target specific users by aliases assigned via API. An alias can be an external_id, onesignal_id, or a custom alias.
Accepts an object where keys are alias labels and values are arrays of alias IDs to include
Example usage: { "external_id": ["exId1", "extId2"], "internal_label": ["id1", "id2"] }
Keys must match API spellings exactly (for example the label for External ID is the string `external_id`; arbitrary keys such as camelCase variants are not aliases and may yield no recipients).
Not compatible with any other targeting parameters.
REQUIRED: REST API Key Authentication
Limit of 2,000 entries per REST API call
Note: If targeting push, email, or sms subscribers with same ids, use with target_channel to indicate you are sending a push or email or sms.'
nullable: true
type: object
target_channel:
enum:
- push
- email
- sms
type: string
type: object
PlatformDeliveryData:
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'
- $ref: '#/components/schemas/PlatformDeliveryData_sms_allOf'
email:
allOf:
- $ref: '#/components/schemas/DeliveryData'
- $ref: '#/components/schemas/PlatformDeliveryData_email_allOf'
type: object
Notification:
allOf:
- $ref: '#/components/schemas/BasicNotification'
- $ref: '#/components/schemas/Notification_allOf'
LanguageStringMap:
example:
de: de
hi: hi
fi: fi
ru: ru
pt: pt
bg: bg
lt: lt
hr: hr
lv: lv
fr: fr
hu: hu
bs: bs
zh-Hans: zh-Hans
zh-Hant: zh-Hant
ka: ka
uk: uk
sk: sk
id: id
ca: ca
sr: sr
sv: sv
ko: ko
ms: ms
el: el
en: en
it: it
zh: zh
es: es
et: et
cs: cs
ar: ar
pa: pa
vi: vi
nb: nb
th: th
ja: ja
fa: fa
pl: pl
da: da
he: he
ro: ro
nl: nl
tr: tr
properties:
en:
description: Text in English. Will be used as a fallback
type: string
ar:
description: Text in Arabic.
type: string
bs:
description: Text in Bosnian.
type: string
bg:
description: Text in Bulgarian.
type: string
ca:
description: Text in Catalan.
type: string
zh-Hans:
description: Text in Chinese (Simplified).
type: string
zh-Hant:
description: Text in Chinese (Traditional).
type: string
zh:
description: Alias for zh-Hans.
type: string
hr:
description: Text in Croatian.
type: string
cs:
description: Text in Czech.
type: string
da:
description: Text in Danish.
type: string
nl:
description: Text in Dutch.
type: string
et:
description: Text in Estonian.
type: string
fi:
description: Text in Finnish.
type: string
fr:
description: Text in French.
type: string
ka:
description: Text in Georgian.
type: string
de:
description: Text in German.
type: string
el:
description: Text in Greek.
type: string
hi:
description: Text in Hindi.
type: string
he:
description: Text in Hebrew.
type: string
hu:
description: Text in Hungarian.
type: string
id:
description: Text in Indonesian.
type: string
it:
description: Text in Italian.
type: string
ja:
description: Text in Japanese.
type: string
ko:
description: Text in Korean.
type: string
lv:
description: Text in Latvian.
type: string
lt:
description: Text in Lithuanian.
type: string
ms:
description: Text in Malay.
type: string
nb:
description: Text in Norwegian.
type: string
pl:
description: Text in Polish.
type: string
fa:
description: Text in Persian.
type: string
pt:
description: Text in Portugese.
type: string
pa:
description: Text in Punjabi.
type: string
ro:
description: Text in Romanian.
type: string
ru:
description: Text in Russian.
type: string
sr:
description: Text in Serbian.
type: string
sk:
description: Text in Slovak.
type: string
es:
description: Text in Spanish.
type: string
sv:
description: Text in Swedish.
type: string
th:
description: Text in Thai.
type: string
tr:
description: Text in Turkish.
type: string
uk:
description: Text in Ukrainian.
type: string
vi:
description: Text in Vietnamese.
type: string
type: object
SegmentNotificationTarget:
properties:
included_segments:
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.
Example: ["Active Users", "Inactive Users"]
'
items:
type: string
type: array
excluded_segments:
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.
Example: ["Active Users", "Inactive Users"]
'
items:
type: string
type: array
type: object
GenericError:
properties:
errors: {}
success:
type: boolean
reference: {}
type: object
NotificationWithMeta:
allOf:
- $ref: '#/components/schemas/BasicNotification'
- $ref: '#/components/schemas/DeliveryData'
- $ref: '#/components/schemas/OutcomesData'
- $ref: '#/components/schemas/NotificationWithMeta_allOf'
BasicNotification:
allOf:
- $ref: '#/components/schemas/NotificationTarget'
- $ref: '#/components/schemas/BasicNotification_allOf'
- required:
- app_id
NotificationWithMeta_allOf:
properties:
remaining:
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.
type: integer
successful:
description: Number of notifications that were successfully delivered.
type: integer
failed:
description: Number of notifications that could not be delivered due to those devices being unsubscribed.
type: integer
errored:
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.
type: integer
converted:
description: Number of users who have clicked / tapped on your notification.
type: integer
queued_at:
description: Unix timestamp indicating when the notification was created.
format: int64
type: integer
send_after:
description: Unix timestamp indicating when notification delivery should begin.
format: int64
nullable: true
type: integer
completed_at:
description: Unix timestamp indicating when notification delivery completed. The delivery duration from start to finish can be calculated with completed_at - send_after.
format: int64
nullable: true
type: integer
platform_delivery_stats:
$ref: '#/components/schemas/PlatformDeliveryData'
received:
description: Confirmed Deliveries number of devices that received the push notification. Paid Feature Only. Free accounts will see 0.
nullable: true
type: integer
throttle_rate_per_minute:
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.
nullable: true
type: integer
canceled:
description: Indicates whether the notification was canceled before it could be sent.
type: boolean
email_bcc:
description: BCC recipients that were set on this email notification.
items:
type: string
nullable: true
type: array
bcc_sent:
description: Number of BCC copies successfully sent for this notification.
nullable: true
type: integer
type: object
FilterExpression:
oneOf:
- $ref: '#/components/schemas/Filter'
- $ref: '#/components/schemas/Operator'
GenericSuccessBoolResponse:
example:
success: true
properties:
success:
type: boolean
type: object
Operator:
properties:
operator:
description: Strictly, this must be either `"OR"`, or `"AND"`. It can be used to compose Filters as part of a Filters object.
enum:
- OR
- AND
type: string
type: object
WebButton:
properties:
id:
type: string
text:
type: string
icon:
type: string
url:
type: string
required:
- id
type: object
Notification_allOf:
properties:
send_after:
description: 'Channel: All
Schedule notification for future delivery. API defaults to UTC -1100
Examples: All examples are the exact same date & time.
"Thu Sep 24 2015 14:00:00 GMT-0700 (PDT)"
"September 24th 2015, 2:00:00 pm UTC-07:00"
"2015-09-24 14:00:00 GMT-0700"
"Sept 24 2015 14:00:00 GMT-0700"
"Thu Sep 24 2015 14:00:00 GMT-0700 (Pacific Daylight Time)"
Note: SMS currently only supports send_after parameter.
'
format: date-time
nullable: true
type: string
writeOnly: true
type: object
NotificationHistorySuccessResponse:
example:
success: true
destination_url: destination_url
properties:
success:
type: boolean
destination_url:
type: string
type: object
OutcomeData:
example:
aggregation: sum
id: id
value: 0
properties:
id:
type: string
value:
type: integer
aggregation:
enum:
- sum
- count
type: string
required:
- aggregation
- id
- value
type: object
get_notification_history_request_body:
properties:
events:
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
type: string
email:
description: The email address you would like the report sent.
type: string
app_id:
type: string
required:
- id
title: get_notification_history_request_body
type: object
Filter:
properties:
# --- truncated at 32 KB (77 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/onesignal/refs/heads/main/openapi/onesignal-notifications-api-openapi.yml