Skip to main content
The OneSignal 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, Segments, export data, and configure apps.

​
Which API to use

GoalAPI
Send a push, email, or SMSCreate Message
Add or update user dataCreate User / Update User
Target a group of usersCreate Segments or use Filters inline
Export analytics or user dataCSV Export / CSV of Events
Manage app configurationCreate App / Update App

​
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, the OneSignal SDKs, or the dashboard—passes through Cloudflare, which serves as the 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
Avoid 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).
  • Allow inbound traffic from https://api.onesignal.com, or
  • Use GCP’s maintained IP range list and filter by europe-west4 region: GCP IP ranges
OneSignal supports 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 the 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.
For platform-specific features like personalization, throttling, and frequency capping, see the Push, Email, SMS, and Live Activities overview guides.

​
Manage templates

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

Create template

Save a reusable message layout for push, email, or SMS.

Update template

Modify an existing template’s content or settings.

View templates

List all templates in your app with their metadata.

Delete template

Permanently remove a template from your app.

​
Track custom events

Custom events record user actions like purchases, content views, or milestones. Use them to enter users into Journeys or trigger Wait Until nodes.

Create custom events

Record user events to trigger Journeys and track behavior.

​
Manage Users and Subscriptions

See the Users and Subscriptions guides for more details.

Create user

Create a user with optional aliases and subscriptions.

View user

View user details.

Update user

Modify a User’s properties, tags, or aliases.

Delete user

Permanently remove a User and all associated data.

​
Manage Segments

Segments group Users by filters for targeted messaging.

Create Segments

Define a new Segment with filters to group Users.

Update Segment

Modify a Segment’s name or replace its filters.

Delete Segments

Permanently remove a Segment from your app.
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 & API Keys

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

Create an app

Register a new app with platform credentials.

Update an app

Modify app settings or platform credentials.

View single app

Retrieve configuration and details for one app.

View multiple apps

List all apps in your account.

​
API key management

See Keys & IDs for more details.

Create API key

Generate a new API key with specific permissions.

View API keys

List all API keys and their permissions for your app.

Delete API key

Revoke an API key permanently.

Update API key

Modify an API key’s permissions or IP allowlist.

​
Error handling and retries

The OneSignal API may return temporary errors such as 429 (rate limited), 5xx (server errors), or timeouts. When this happens, the request may still be processing. If you retry failed requests, always use an idempotency_key and follow the recommended retry delays to avoid duplicate messages.

Rate limits and error handling

Retry strategies, error definitions, and recovery steps.

​
FAQ

​
What is the timeout for API responses?

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

No. The OneSignal API uses HTTPS with a publicly trusted TLS certificate managed by Cloudflare. These edge certificates renew automatically and are trusted by all major browsers, operating systems, and runtimes. If your network pins a specific leaf certificate, it will expire and rotate every few months — this is normal Cloudflare behavior. Trust the root and intermediate CAs in the chain instead of the leaf certificate to avoid disruption.
  • Best practice: Trust the root and intermediate CAs in the chain instead of the rotating leaf certificate.
  • 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.
  • Fetching the current certificate: If your process requires the active leaf certificate, retrieve it directly:
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 chain, add the -showcerts flag to openssl s_client.See Cloudflare SSL/TLS documentation and Cloudflare Edge Certificates documentation for more details.

​
Why am I getting a 403 Forbidden error?

A 403 response means the API key is valid but does not have permission for the requested operation. Check the following:
  • Wrong key type: App API keys work for app-level endpoints (sending messages, managing Users). Organization API keys are required for org-level endpoints (creating apps, managing API keys). See Keys & IDs for details.
  • IP allowlisting: If IP allowlisting is enabled on your API key, requests from IPs not on the list are denied. Verify your server’s IP is included.
  • Revoked or rotated key: If the key was recently rotated, the old key is no longer valid. Update your integration with the new key.

​
Why am I getting “UnknownHostException - Unable to resolve host api.onesignal.com”?

This error means your environment cannot resolve the DNS for api.onesignal.com. Common causes:
  • Firewall or proxy blocking DNS: Ensure your network allows outbound DNS queries and traffic to api.onesignal.com on port 443.
  • No internet connectivity: Verify the device or server has an active network connection.
  • DNS server misconfiguration: Try a public DNS resolver like 8.8.8.8 (Google) or 1.1.1.1 (Cloudflare) to rule out local DNS issues.
  • Stale DNS cache: Flush your local DNS cache and ensure your client respects the TTL of 300 seconds.