RESTful API

Our REST API is based on the REST Architecture but does not necessarily conform precisely to those principles.

Each endpoint manages a different object type, and a number of HTTP methods are supported for each:

Our API treats PUT as an update, supporting partial replacement. However, each key is managed independently, and some side effects may change other properties. The PATCH method, and full replacement, are not supported.

Requirements

• HTTPS. All traffic to the 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.

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

• TLS 1.2 connection or higher

For receiving notifications

FCM (Google Android and Chrome Push Notifications)

If your organization has a firewall that restricts the traffic to or from the Internet, you need to configure it to allow connectivity with FCM in order for your Firebase Cloud Messaging client apps to receive messages. The ports to open are: 5228, 5229, and 5230. FCM typically only uses 5228, but it sometimes uses 5229 and 5230. FCM doesn't provide specific IPs, so you should allow your firewall to accept outgoing connections to all IP addresses contained in the IP blocks listed in Google's ASN of 15169. From the "Firewall" note: https://firebase.google.com/docs/cloud-messaging/concept-options

---

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.

Tag Filter Target and Exclude By Topics

1. Figure out Tag categories

More details in our Add Data Tags, for example:

"breaking": 1
"sports": 1
"finance": 1
"politics": 1

The tag "key" will be the topic and the value can be whatever you like. In the example: "1" can indicate how many times the user visited the topic or you can use Time Operators to know how long since they last viewed the topic. Another common setup is to Tag based on Subscription page.

2. Target by filters

For news that crosses both "politics" and "breaking" you can use API filters to target these users without overlap.

For example:

filters: [
  {"field": "tag", "key": "politics", "relation": "exists"},
  {"operator": "OR"},
  {"field": "tag", "key": "breaking", "relation": "exists"}
]

In this example, all users with either the "politics" or "breaking" tags will get the message. Our system will automatically make sure no users with both tags will get it twice as long as they are targeted in the same API call.

3. Exclude Segments

If you later want to send this same article to "finance" users, you can make sure none of them get duplicates if you use the example:

filters: [
  {"field": "tag", "key": "politics", "relation": "not_exists"},
  {"field": "tag", "key": "breaking", "relation": "not_exists"},
  {"field": "tag", "key": "finance", "relation": "exists"}
]

This will make sure that only users with the "finance" tag will get the message.