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

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:

Supported features

Below are common supported features for each platform. See our overview docs for each platform’s supported features:


Manage templates

Templates are reusable push, email, and SMS messages that simplify development and improve consistency.


Manage users and subscriptions

See our Users and Subscriptions guides for more details.

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.


Manage apps & keys

OneSignal allows you to group platforms (mobile apps, websites) under a single App ID. See Apps, orgs, & accounts.

API key management

See Keys & IDs for more details.


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.

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 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 the Retry-After header.
  • Do not retry 400, 401, or 403 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

echo -n | openssl s_client -connect api.onesignal.com:443 \
| sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /tmp/$SERVERNAME.pem
Cloudflare may rotate their certs periodically, so you’ll need to update the cert periodically.

Option 2. Loosen your TLS restrictions

See Cloudflare’s guides on managing certs


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

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:

Supported features

Below are common supported features for each platform. See our overview docs for each platform’s supported features:


Manage templates

Templates are reusable push, email, and SMS messages that simplify development and improve consistency.


Manage users and subscriptions

See our Users and Subscriptions guides for more details.

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.


Manage apps & keys

OneSignal allows you to group platforms (mobile apps, websites) under a single App ID. See Apps, orgs, & accounts.

API key management

See Keys & IDs for more details.


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.

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 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 the Retry-After header.
  • Do not retry 400, 401, or 403 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

echo -n | openssl s_client -connect api.onesignal.com:443 \
| sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /tmp/$SERVERNAME.pem
Cloudflare may rotate their certs periodically, so you’ll need to update the cert periodically.

Option 2. Loosen your TLS restrictions

See Cloudflare’s guides on managing certs