Development — entry 064 of 100

OneSignal

Verified Jul 2026

OneSignal's REST API (api.onesignal.com) sends and manages push, email, SMS, and in-app messages plus user, segment, and app data, authenticated with an App or Organization API key rather than OAuth. The free plan covers unlimited mobile push and up to 10,000 web-push subscribers per send with core segmentation, while the paid Growth plan (from $19/month) adds per-MAU push billing and higher email/SMS limits. The API host returns no Access-Control-Allow-Origin header, so it isn't meant to be called directly from browser JavaScript.

push-notificationsmessagingemailsms

Visit onesignal.com ↗Read the docs ↗More Development

AuthenticationAPI KeySign up with the provider to obtain credentials.

HTTPSSupportedTraffic is encrypted in transit.

CORSDisabledBrowser calls need a server-side proxy.

PricingFreemiumA usable free tier exists, with paid plans for more volume.

FormatsJSONResponses can be requested as JSON.

GreatAPIs Score

Score81out of 100

Authentication15/25API key required

Pricing17/20Freemium tier available

Docs20/20Machine-readable spec file bundled

Formats9/15Single response format

Freshness20/20Verified within 6 months

Embed this badge

<a href="https://greatapis.com/api/onesignal/"><img src="https://greatapis.com/badge/onesignal.svg" alt="Scored 81 on greatapis.com"></a>

Auth quickstart

Sign up with the provider to get an API key.
Send it on every request as a headerAuthorization: <key>
The exact header isn't documented — Authorization is a common default; confirm in the provider's docs.

Stored keyNo key stored

Your key is stored only in this browser (localStorage) and sent directly to the API — never to greatapis.

Endpoints

Servers

https://onesignal.com/api/v1

Auth

app_keyuser_key

apps25

GET/appsView apps

Responses

Status	Description	Schema
`200`	OK	`Apps`
`400`	Bad Request	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

POST/appsCreate an app

Request body

application/json — App (required)

Responses

Status	Description	Schema
`200`	OK	`App`
`400`	Bad Request	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

GET/apps/{app_id}View an app

Parameters

Name	In	Required	Type
`app_id`	path	yes	string

Responses

Status	Description	Schema
`200`	OK	`App`
`400`	Bad Request	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

PUT/apps/{app_id}Update an app

Parameters

Name	In	Required	Type
`app_id`	path	yes	string

Request body

application/json — App (required)

Responses

Status	Description	Schema
`200`	OK	`App`
`400`	Bad Request	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

POST/apps/{app_id}/live_activities/{activity_id}/notificationsUpdate a Live Activity via Push

Parameters

Name	In	Required	Type
`app_id`	path	yes	string
`activity_id`	path	yes	string

Request body

application/json — UpdateLiveActivityRequest (required)

Responses

Status	Description	Schema
`200`	OK	`UpdateLiveActivitySuccessResponse`
`400`	Bad Request	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

POST/apps/{app_id}/live_activities/{activity_id}/tokenStart Live Activity

Parameters

Name	In	Required	Type
`app_id`	path	yes	string
`activity_id`	path	yes	string

Request body

application/json — BeginLiveActivityRequest (required)

Responses

Status	Description	Schema
`204`	OK	—
`400`	Bad Request	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

DELETE/apps/{app_id}/live_activities/{activity_id}/token/{subscription_id}Stop Live Activity

Parameters

Name	In	Required	Type
`app_id`	path	yes	string
`activity_id`	path	yes	string
`subscription_id`	path	yes	string

Responses

Status	Description	Schema
`204`	OK	—
`400`	Bad Request	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

GET/apps/{app_id}/outcomesView Outcomes

Parameters

Name	In	Required	Type
`app_id`	path	yes	string
`outcome_names`	query	yes	string
`outcome_names[]`	query	no	string
`outcome_time_range`	query	no	string
`outcome_platforms`	query	no	string
`outcome_attribution`	query	no	string

Responses

Status	Description	Schema
`200`	OK	`OutcomesData`
`400`	Bad Request	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

POST/apps/{app_id}/segmentsCreate Segments

Parameters

Name	In	Required	Type
`app_id`	path	yes	string

Request body

application/json — Segment

Responses

Status	Description	Schema
`201`	Created	`CreateSegmentSuccessResponse`
`400`	Bad Request	`GenericError`
`409`	Conflict	`CreateSegmentConflictResponse`
`429`	Rate Limit Exceeded	`RateLimiterError`

DELETE/apps/{app_id}/segments/{segment_id}Delete Segments

Parameters

Name	In	Required	Type
`app_id`	path	yes	string
`segment_id`	path	yes	string

Responses

Status	Description	Schema
`200`	OK	`DeleteSegmentSuccessResponse`
`400`	Bad Request	`GenericError`
`404`	Not Found	`DeleteSegmentNotFoundResponse`
`429`	Rate Limit Exceeded	`RateLimiterError`

PATCH/apps/{app_id}/subscriptions/{subscription_id}

Parameters

Name	In	Required	Type
`app_id`	path	yes	string
`subscription_id`	path	yes	string

Request body

application/json — UpdateSubscriptionRequestBody (required)

Responses

Status	Description	Schema
`202`	ACCEPTED	—
`400`	Bad Request	`GenericError`
`409`	Conflict	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

DELETE/apps/{app_id}/subscriptions/{subscription_id}

Parameters

Name	In	Required	Type
`app_id`	path	yes	string
`subscription_id`	path	yes	string

Responses

Status	Description	Schema
`202`	ACCEPTED	—
`400`	Bad Request	`GenericError`
`409`	Conflict	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

GET/apps/{app_id}/subscriptions/{subscription_id}/iams

Parameters

Name	In	Required	Type
`app_id`	path	yes	string
`subscription_id`	path	yes	string

Responses

Status	Description	Schema
`200`	OK	—
`400`	Bad Request	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

PATCH/apps/{app_id}/subscriptions/{subscription_id}/owner

Parameters

Name	In	Required	Type
`app_id`	path	yes	string
`subscription_id`	path	yes	string

Request body

application/json — TransferSubscriptionRequestBody (required)

Responses

Status	Description	Schema
`200`	OK	`UserIdentityResponse`
`400`	Bad Request	`GenericError`
`409`	Conflict	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

GET/apps/{app_id}/subscriptions/{subscription_id}/user/identity

Parameters

Name	In	Required	Type
`app_id`	path	yes	string
`subscription_id`	path	yes	string

Responses

Status	Description	Schema
`200`	OK	`UserIdentityResponse`
`400`	Bad Request	`GenericError`

PATCH/apps/{app_id}/subscriptions/{subscription_id}/user/identity

Parameters

Name	In	Required	Type
`app_id`	path	yes	string
`subscription_id`	path	yes	string

Request body

application/json — UserIdentityRequestBody (required)

Responses

Status	Description	Schema
`200`	OK	`UserIdentityResponse`
`400`	Bad Request	`GenericError`
`409`	Conflict	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

POST/apps/{app_id}/users

Parameters

Name	In	Required	Type
`app_id`	path	yes	string

Request body

application/json — User (required)

Responses

Status	Description	Schema
`200`	CREATED	`User`
`201`	CREATED	`User`
`202`	ACCEPTED	`User`
`400`	Bad Request	`GenericError`
`409`	Multiple User Identity Conflict	`CreateUserConflictResponse`
`429`	Rate Limit Exceeded	`RateLimiterError`

GET/apps/{app_id}/users/by/{alias_label}/{alias_id}

Parameters

Name	In	Required	Type
`app_id`	path	yes	string
`alias_label`	path	yes	string
`alias_id`	path	yes	string

Responses

Status	Description	Schema
`200`	OK	`User`
`400`	Bad Request	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

PATCH/apps/{app_id}/users/by/{alias_label}/{alias_id}

Parameters

Name	In	Required	Type
`app_id`	path	yes	string
`alias_label`	path	yes	string
`alias_id`	path	yes	string

Request body

application/json — UpdateUserRequest (required)

Responses

Status	Description	Schema
`202`	ACCEPTED	—
`400`	Bad Request	`GenericError`
`409`	Conflict	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

DELETE/apps/{app_id}/users/by/{alias_label}/{alias_id}

Parameters

Name	In	Required	Type
`app_id`	path	yes	string
`alias_label`	path	yes	string
`alias_id`	path	yes	string

Responses

Status	Description	Schema
`200`	OK	—
`400`	Bad Request	`GenericError`
`409`	Conflict	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

GET/apps/{app_id}/users/by/{alias_label}/{alias_id}/identity

Parameters

Name	In	Required	Type
`app_id`	path	yes	string
`alias_label`	path	yes	string
`alias_id`	path	yes	string

Responses

Status	Description	Schema
`200`	OK	—
`400`	Bad Request	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

PATCH/apps/{app_id}/users/by/{alias_label}/{alias_id}/identity

Parameters

Name	In	Required	Type
`app_id`	path	yes	string
`alias_label`	path	yes	string
`alias_id`	path	yes	string

Request body

application/json — UserIdentityRequestBody (required)

Responses

Status	Description	Schema
`200`	OK	—
`400`	Bad Request	`GenericError`
`409`	Conflict	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

DELETE/apps/{app_id}/users/by/{alias_label}/{alias_id}/identity/{alias_label_to_delete}

Parameters

Name	In	Required	Type
`app_id`	path	yes	string
`alias_label`	path	yes	string
`alias_id`	path	yes	string
`alias_label_to_delete`	path	yes	string

Responses

Status	Description	Schema
`200`	OK	—
`400`	Bad Request	`GenericError`
`409`	Conflict	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

POST/apps/{app_id}/users/by/{alias_label}/{alias_id}/subscriptions

Parameters

Name	In	Required	Type
`app_id`	path	yes	string
`alias_label`	path	yes	string
`alias_id`	path	yes	string

Request body

application/json — CreateSubscriptionRequestBody (required)

Responses

Status	Description	Schema
`201`	CREATED	—
`202`	ACCEPTED	—
`400`	Bad Request	`GenericError`
`409`	Operation is not permitted due to user having the maximum number of subscriptions assigned	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

PUT/apps/{app_id}/users/{external_user_id}Edit tags with external user id

Parameters

Name	In	Required	Type
`app_id`	path	yes	string
`external_user_id`	path	yes	string

Request body

application/json

Responses

Status	Description	Schema
`200`	OK	`UpdatePlayerTagsSuccessResponse`
`400`	Bad Request	`GenericError`
`409`	Conflict	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

notifications6

GET/notificationsView notifications

Parameters

Name	In	Required	Type
`app_id`	query	yes	string
`limit`	query	no	integer
`offset`	query	no	integer
`kind`	query	no	integer

Responses

Status	Description	Schema
`200`	OK	`NotificationSlice`
`400`	Bad Request	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

POST/notificationsCreate notification

Request body

application/json — Notification (required)

Responses

Status	Description	Schema
`200`	OK, invalid_player_ids, invalid_external_user_ids or No Subscribed Players If a message was successfully created, you will get a 200 response and an id for the notification. If 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. 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.	`CreateNotificationSuccessResponse`
`400`	Bad Request	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

GET/notifications/{notification_id}View notification

Parameters

Name	In	Required	Type
`app_id`	query	yes	string
`notification_id`	path	yes	string

Responses

Status	Description	Schema
`200`	OK	`NotificationWithMeta`
`400`	Bad Request	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

DELETE/notifications/{notification_id}Stop a scheduled or currently outgoing notification

Parameters

Name	In	Required	Type
`app_id`	query	yes	string
`notification_id`	path	yes	string

Responses

Status	Description	Schema
`200`	OK	`CancelNotificationSuccessResponse`
`400`	Bad Request	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

POST/notifications/{notification_id}/export_events?app_id={app_id}Export CSV of Events

Parameters

Name	In	Required	Type
`notification_id`	path	yes	string
`app_id`	query	yes	string

Responses

Status	Description	Schema
`200`	OK	`ExportEventsSuccessResponse`
`400`	Bad Request	`GenericError`
`404`	Not Found	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

POST/notifications/{notification_id}/historyNotification History

Parameters

Name	In	Required	Type
`notification_id`	path	yes	string

Request body

application/json (required)

Responses

Status	Description	Schema
`200`	OK	`NotificationHistorySuccessResponse`
`400`	Bad Request	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

players6

GET/playersView devices

Parameters

Name	In	Required	Type
`app_id`	query	yes	string
`limit`	query	no	integer
`offset`	query	no	integer

Responses

Status	Description	Schema
`200`	OK	`PlayerSlice`
`400`	Bad Request	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

POST/playersAdd a device

Request body

application/json — Player (required)

Responses

Status	Description	Schema
`200`	OK	`CreatePlayerSuccessResponse`
`400`	Bad Request	`GenericError`
`409`	Conflict	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

POST/players/csv_export?app_id={app_id}Export CSV of Players

Parameters

Name	In	Required	Type
`app_id`	path	yes	string

Request body

application/json

Responses

Status	Description	Schema
`200`	OK	`ExportPlayersSuccessResponse`
`400`	Bad Request	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

GET/players/{player_id}View device

Parameters

Name	In	Required	Type
`app_id`	query	yes	string
`player_id`	path	yes	string
`email_auth_hash`	query	no	string

Responses

Status	Description	Schema
`200`	OK	`Player`
`400`	Bad Request	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

PUT/players/{player_id}Edit device

Parameters

Name	In	Required	Type
`player_id`	path	yes	string

Request body

application/json — Player (required)

Responses

Status	Description	Schema
`200`	OK	`UpdatePlayerSuccessResponse`
`400`	Bad Request	`GenericError`
`409`	Conflict	`GenericError`
`429`	Rate Limit Exceeded	`RateLimiterError`

DELETE/players/{player_id}Delete a user record

Parameters

Name	In	Required	Type
`app_id`	query	yes	string
`player_id`	path	yes	string

Responses

Status	Description	Schema
`200`	OK	`DeletePlayerSuccessResponse`
`400`	Bad Request	`GenericError`
`404`	Not Found	`DeletePlayerNotFoundResponse`
`429`	Rate Limit Exceeded	`RateLimiterError`

Try it

Operation

API key

Developer reference

Base URLhttps://onesignal.com/api/v1

Key endpoints

POST/notifications
GET/notifications
GET/apps

GreatAPIs Score

Embed this badge

Auth quickstart

Endpoints

Try it

Developer reference

People comparing OneSignal also look at…

Kroki

QR code

Statically

Wandbox

APIs.guru

Beeceptor