REST API Overview
Learn about OneSignal’s REST API capabilities, security requirements, rate limits, retries, and how to send notifications, manage users, apps, and segments programmatically.
Our REST API follows the REST Architecture and provides programmatic access to core messaging and user features. Use the API to send push notifications, emails, and SMS, manage users, subscriptions, and segments, export data, and configure apps.
Requirements
General
- HTTPS Required: All API requests must use HTTPS with TLS 1.2 or higher, on port
443
. - Network Access: Firewalls or proxies must allow outbound traffic to
https://api.onesignal.com
on port443
. - DNS TTL: Clients must respect OneSignal’s DNS TTL of 300 seconds to avoid stale IP resolution.
Incoming Traffic to OneSignal (API & SDK Requests)
All incoming API traffic—whether from your backend, our SDKs, or the dashboard—passes through Cloudflare, which serves as our global edge network.
- You may see Cloudflare IP addresses in logs.
- These IPs are managed by Cloudflare and may change over time.
- If you maintain a strict firewall and need to allow outbound traffic to OneSignal, use Cloudflare’s official IP ranges:
https://www.cloudflare.com/ips/
We do not recommend whitelisting specific Cloudflare IPs, as they may change without notice.
Outgoing Traffic from OneSignal (Webhooks & Event Streams)
For features where OneSignal sends HTTP requests to your servers (e.g., webhooks or event streams), these originate from our infrastructure on Google Cloud Platform (GCP) in the europe-west4
region (Groningen, Netherlands).
- To allow inbound traffic from OneSignal, consult GCP’s maintained list of IP ranges:
https://www.gstatic.com/ipranges/cloud.json
(You can filter by theeurope-west4
region.)
Platform-specific network requirements
FCM (Google Android and Chrome push)
- Required ports:
5228
,443
,5229
, and5230
- No IP allow-listing needed
- More info: Firebase Cloud Messaging (FCM)
APNs (Apple iOS, iPadOS, Safari push)
- Required ports:
5223
,443
, and2197
- Recommended servers:
- Sandbox:
api.sandbox.push.apple.com:443
- Production:
api.push.apple.com:443
- IP range:
17.0.0.0/8
- Sandbox:
- More info:
Core API capabilities
Send messages
See our Create Message guide to get started. Programmatically send:
Push Notifications
Send push notifications to apps and websites.
Send transactional and promotional emails.
SMS
Send SMS or MMS messages globally.
Live Activities
Send Live Activity updates to iOS devices.
Supported features
Below are common supported features for each platform. See our overview docs for each platform’s supported features:
Message Personalization
Add dynamic content to personalize messages for each user.
Multi-Language Messaging
Send push notifications in multiple languages.
Throttling
Control push notification delivery speed.
Frequency Capping
Limit the number of push notifications per user.
Data & background notifications
Send data-only notifications for background tasks.
Manage templates
Templates are reusable push, email, and SMS messages that simplify development and improve consistency.
Create template
Create a reusable template.
Update template
Update a template.
View templates
View all templates.
Delete template
Delete a template.
Manage users and subscriptions
See our Users and Subscriptions guides for more details.
Create user
Create a user with optional aliases and subscriptions.
View user
View user details.
Update user
Update a user.
Delete user
Delete a user.
Manage segments
Segments help group users by filters.
You can also target users dynamically using filters without creating persistent segments.
Export data
For analytics breakdowns, see Analytics overview.
Export CSV of subscriptions
Export all user and subscription data.
Export CSV of events
Export events like sent, received, and clicked.
View messages
View message details and analytics.
View message
View individual message details.
Manage apps & keys
OneSignal allows you to group platforms (mobile apps, websites) under a single App ID. See Apps, orgs, & accounts.
Create an app
Create an app.
Update an app
Update an app.
View single app
View a single app.
View multiple apps
View all apps.
API key management
See Keys & IDs for more details.
Create API key
Create an API key.
View API keys
View all API keys.
Delete API key
Delete an API key.
Update API key
Update an API key.
Reliability and delivery
Rate limits
All API endpoints are subject to rate limits. Limits vary by endpoint and request type.
Refer to the Rate Limits reference for full details.
Retry-After
.Retries
If a request fails due to a transient error (HTTP 5xx or rate limit), retry the request using an exponential backoff strategy based on the Retry-After
header. Avoid retrying 4xx errors, which typically indicate invalid requests.
- Retry
429
errors after waiting the duration specified in theRetry-After
header. - Do not retry
400
,401
, or403
errors without fixing the underlying issue.
Idempotent requests
Use the idempotency_key
header to prevent duplicate messages when retrying failed requests.
- Available for: Create Message
- Format: Up to 64 alphanumeric characters
- Duration: Idempotency keys are cached for 24 hours
See the Idempotent Notification Requests guide for implementation tips.
FAQ
What is the timeout for API responses?
- Default: 100 seconds
- If you’re unsure whether a request completed, use an
idempotency_key
to safely retry.
Does the API require client certificates?
No, certificates are not required. If needed for your security posture:
Option 1: Download the Cloudflare cert
Option 2. Loosen your TLS restrictions
See Cloudflare’s guides on managing certs