Scribd
Upload
6 views

REST API overview

OneSignal's REST API enables programmatic delivery of push notifications, emails, and SMS, requiring HTTPS connections with specific port allowances for FCM and APNS. Users can manage templates, user data, segments, and export analytics through the API. The document also outlines API rate limits, response timeouts, and certificate management options.

Uploaded by

pedro.prevenirassistencial
Copyright
© © All Rights Reserved
Available Formats
Download as PDF, TXT or read online on Scribd
6 views

REST API overview

OneSignal's REST API enables programmatic delivery of push notifications, emails, and SMS, requiring HTTPS connections with specific port allowances for FCM and APNS. Users can manage templates, user data, segments, and export analytics through the API. The document also outlines API rate limits, response timeouts, and certificate management options.

Uploaded by

pedro.prevenirassistencial
Copyright
© © All Rights Reserved
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 4

06/03/2025, 15:09 REST API overview

  Server REST API Reference

REST API overview Search Ct rl +K

REST API overview


OneSignal's REST API requirements and capabilities.

OneSignal's RESTful API is based on the REST Architecture and provides robust features
that can be used for the below operations.

 Requirements
The OneSignal API is accessed using an HTTPS connection with TLS 1.2 support or higher
on standard port 443.

Firewalls and proxies must allow outbound HTTPS traffic on port 443 to connect to our
REST API. See below FCM and APNS requirements as well.

We recommend whitelisting HTTPS traffic to any public IP address or allow


api.onesignal.com . Be sure your DNS cache respects OneSignal's TTL of 300 seconds to
avoid making requests to stale IP addresses.

IP Addresses: OneSignal uses Google Cloud Platform (GCP) data centers located in
Groningen, Netherlands. There is a wide range of IPs that can be used and are subject to
change. For the most up-to-date list, you can check here for scope: europe-west4 .

FCM (Google Android and Chrome push notifications)


Google's Firebase Cloud Messaging (FCM) uses ports 5228, 443, 5229, and 5230. You
should allow devices to connect with FCM using these ports and no IP restrictions.

For more details, see FCM's documentation:

https://firebase.google.com/docs/cloud-messaging/concept-options#messaging-ports-
and-your-firewall

APNS (Apple iOS, iPadOS, Safari push notifications)


Apple's Push Notification Service (APNs) uses ports 5223, 443, and 2197. You should
allow devices to connect with APNs using these ports and no IP restrictions. If you need to
setup server and IP restrictions, then make sure to allow access to:
https://documentation.onesignal.com/reference/rest-api-overview 1/4
06/03/2025, 15:09 REST API overview

Development server: api.sandbox.push.apple.com:443


Production server: api.push.apple.com:443
Access to entire IP range: 17.0.0.0/8

For more details, see Apple's documentation:

https://support.apple.com/en-us/102266
https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notif
ication_server/sending_notification_requests_to_apns?language=objc

Send messages
Programmatically deliver push notifications, emails, and sms from your server.

Messages can be sent to segments, data filters (which are similar to segments but
without creating the reusable segment name), and specific devices by a User ID, email
address, or phone number depending on channel.
All available parameters are supported like Content & Language, custom data &
images, and scheduling options.
Plenty of Example Code in commonly used languages to get you started.

Create, update, view, & delete templates


Templates are reusable push, email, and SMS messages that can be created, updated,
viewed, and deleted through the dashboard or API.

For example, your marketing team can create the template in the dashboard and your
developers can pull the template_id to use with Create notification or pull stats with View
notifications.

Create, update, view, & delete users


See Users and Subscriptions for details. Each User will have their own OneSignal ID, but
you can also lookup by Aliases & External ID that you set.

Create user - create a new user with subscriptions and/or aliases.


View user - get the user's properties, aliases, and subscriptions.
Update user - update a user's properties, like tags. Add new or update current
subscriptions to a user with Create subscription or Update subscription.
Delete user - deletes the user and all subscriptions.

https://documentation.onesignal.com/reference/rest-api-overview 2/4
06/03/2025, 15:09 REST API overview

Create, view, & delete segments


OneSignal allows you to target devices directly by data filters if you don't want to create
segments or don't plan to send many notifications to these filter combinations.

If you are looking to create a lot of Segments and do not want to go through our Dashboard
GUI, you can use our Create Segments to do this quickly and later Delete Segments if you
don't need them anymore.

Export user and message data


Bulk export user and subscription data with Export CSV of Players.

Pull message data with View notifications or individually with View notification. The
response will contain the properties sent in each message request and the message's
current analytics. Analytics > Message Tracking for details.

Export CSV of Events - generates a CSV of event data (clicked, received, sent, etc) for a
specific message.

Create, update, & view Apps


OneSignal houses related Mobile Apps and Websites under a single OneSignal App. If you
have many apps and/or websites that are not related, you can use the Create an app
endpoint to generate OneSignal App Ids for each platform quickly.

You can later Update an app or View an app / View apps.

FAQ

What are the API rate limits?


See Rate Limits & Disabled Apps.

What is the response timeout for API endpoints?


Responses are usually generated within a couple seconds. However, in extreme cases, they
can take longer.

https://documentation.onesignal.com/reference/rest-api-overview 3/4
06/03/2025, 15:09 REST API overview

OneSignal will wait 30 seconds for a response before automatically canceling the request.
To verify no duplicate requests go through, you can add an Idempotent Key with the
external_id parameter.

How can I get OneSignal's certificates for my API?


Our API does not require any certs to be used, but if you require it, there are two options.
Note that Cloudflare hosts and manages our certs and so may rotate them periodically.

Option 1. Download the .pem file

For example:

Terminal

echo -n | openssl s_client -connect api.onesignal.com:443 \


| sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /tmp/$SERVERNAME.pem

If you get the full cert chain then the root cert will be the first one in the list. You would not
have to change that one or worry if Cloudflare changes it because those root certs have to
be copied into the root trust stores of billions of machines.

Option 2. Lower your restrictions

See Cloudflare's guides on managing certs: https://support.cloudflare.com/hc/en-


us/categories/200276247-SSL-TLS

 Updated 2 days ago

Quick start API guide 

Did this page help you?  Yes  No

https://documentation.onesignal.com/reference/rest-api-overview 4/4

You might also like