Skip to main content
Our REST API follows the REST architecture and provides programmatic access to OneSignal’s core messaging and user features. Use the API to send push notifications, emails, and SMS, manage users, subscriptions, 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 port 443.
  • 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.
  • Cloudflare IPs may change over time.
  • If you maintain a strict firewall, use Cloudflare’s official IP ranges: https://www.cloudflare.com/ips/
We do not recommend allowlisting 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 (such as webhooks or event streams), traffic originates from OneSignal infrastructure running on Google Cloud Platform (GCP) in the europe-west4 region (Groningen, Netherlands).
We support IP allowlisting with REST API keys.

​
Platform-specific network requirements

​
FCM (Google Android and Chrome push)

​
APNs (Apple iOS, iPadOS, Safari push)

  • Required ports: 5223, 443, and 2197
  • Recommended servers:
    • Sandbox: api.sandbox.push.apple.com:443
    • Production: api.push.apple.com:443
    • IP range: 17.0.0.0/8
  • 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.

Email

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.

Create Segments

Create a segment.

Delete Segments

Delete a segment.
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 details.
Rate limits are returned via response headers. Be sure to implement exponential backoff retry logic based on Retry-After.

​
Retries

If a request fails due to a temporary server issue or rate limit, you should retry the request using a controlled retry strategy. Always use an idempotency_key when retrying requests that send messages to prevent duplicate deliveries.

​
Retryable errors

  • HTTP 429 (Too Many Requests)
    The request was rate-limited.
    • Wait for the duration specified in the Retry-After response header.
    • Do not retry before the Retry-After delay has elapsed.
    • Use an idempotency_key when retrying.
  • HTTP 5xx (Server Errors)
    The request failed due to a temporary server issue.
    • Retry using exponential backoff.
    • You may retry before 100 seconds if needed, but the original request may still be processing.
    • Always use an idempotency_key to ensure the request is processed only once.
    • If unsure, start with a 100-second delay, which aligns with the maximum API response timeout.
  • Network timeouts or no response
    If you do not receive a response from the OneSignal API:
    • The request may still be processing on our servers.
    • You may retry the request immediately or after a short delay.
    • Always include an idempotency_key to prevent duplicate message sends.
Using a 100-second delay is the safest default. Retrying sooner is supported for time-sensitive workflows, but idempotency is required to avoid duplicate deliveries.

​
Non-retryable errors

  • HTTP 4xx (Client Errors)
    Do not retry requests that return 4xx errors (such as 400, 401, or 403) unless you have corrected the underlying issue in your request. These errors indicate a problem with request formatting, authentication, or permissions, not a temporary server condition.

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

​
Do I need to download or renew certificates to call the OneSignal API?

No, you do not need to manually download or renew certificates to call the OneSignal API. Our API uses HTTPS with a publicly trusted TLS certificate managed by Cloudflare. These edge certificates are renewed automatically by Cloudflare and trusted by all major browsers, operating systems, and runtimes. No extra action is needed unless your environment has special trust or pinning rules. Why you might be seeing frequent certificate changes If your network or middleware is configured to pin a specific leaf certificate (the one shown during the TLS handshake), you will see it expire and rotate every few months. This is normal — Cloudflare rotates these certificates for security. Most clients trust the public root and intermediate Certificate Authorities (CAs) instead, which avoids any impact when the leaf cert changes. Recommended approach
  • Best practice: Trust the root and intermediate CAs in the chain instead of the rotating leaf certificate. This allows certificate rotation without breaking your connection.
  • If you must pin a certificate: Pin the public key (SPKI) of the CA or use a backup key set, not the exact leaf certificate.
Workaround: Fetching the current certificate If your process requires the active leaf certificate, you can retrieve it directly from our API endpoint: 
SERVERNAME=api.onesignal.com
echo -n | openssl s_client -connect $SERVERNAME:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /tmp/${SERVERNAME}_current.pem
To retrieve the full certificate chain, add the -showcerts flag to openssl s_client and capture all certificates printed. More information Cloudflare’s documentation explains how their SSL/TLS certificates work and why they rotate: