📘

Server API Reference

Jump To OneSignal's Server API Reference

OneSignal's server API provides robust features that can be used to:

Sending Messages

Programmatically deliver notifications and emails 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.
• 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.

Export Data

User Data can be generated through a CSV export or individually with View device.

Notification Data can be generated in paginated groups of 50 using View notifications or individually with View notification and having the notification id available in the response after sending.

Our API also provides Notification History which shows which specific devices "clicked" or were "sent" a specific notification.

Create and 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.

Add and Edit Devices

OneSignal's API provides the Edit device method to update user records server side. Common parameters that can be updated are tags and external_user_id if needing to stay updated with an Internal Database, DMP, & CRM.

The Add a device endpoint to upload your subscriber data. It is important to note that importing devices may not be enough to start sending them push. Each device must have a valid "push token"/identifier that authenticates the device with FCM/APNs. Further Android Devices must have our SDK active in the app to process our Notification Payload Structure and Websites need our Service Workers downloaded on the subscriber's browser to get our notifications.

Create and 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?

When sending push through our API, it is always recommended to include as many devices as possible within each request.

If you are using the include_player_ids or include_external_user_ids you can make these requests to individual users at rates of 50 requests per second.

If you use segments or filters, we recommend no more than 20 requests per second.

Feel free to reach out to [email protected] with details and/or example code about how you plan to send messages, we would be happy to assist with best practices.

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 notification. 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 push.