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 . Below is the updated list as of April 10, 2024. You can copy-paste the following IP ranges to your allowlist (make sure to include your own IP Address if you have not!):
34.32.128.0/17,34.34.0.0/17,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.92.0/22,34.157.208.0/23,34.157.220.0/22,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
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:
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:
- https://support.apple.com/en-us/102266
- https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_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.
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.
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