OneSignal's RESTful API is based on the REST Architecture and provides robust features that can be used for the below operations. OneSignal also provides Backend SDKs in most languages to get started right away.

Requirements

Use HTTP/2 and TLS 1.2 connection or higher.

HTTPS: All traffic to OneSignal's REST API uses HTTPS 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.

IP Addresses: OneSignal uses GCP data centers located in Groningen, Netherlands. There are a wide range of IPs that can be used. You can copy-paste the following IP ranges to your whitelist (make sure to include your own IP Address if you have not!):

34.90.0.0/15,34.104.126.0/23,34.124.62.0/23,34.141.128.0/17,34.147.0.0/17,34.157.80.0/23,34.157.208.0/23,35.204.0.0/16,35.214.128.0/17,35.220.16.0/23,35.234.160.0/20,35.242.16.0/23,2600:1900:4060::/44

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.

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:

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:

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.
If you scheduled a notification in the future and decide not to send anymore, you can also Cancel notification with the notification id available in the response after sending.

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.

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 messages 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.

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:

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