> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API overview

> Programmatic access to OneSignal messaging, user management, segments, Journeys, and data exports over HTTPS with rate limiting and retry support.

The OneSignal REST API follows the [REST architecture](https://en.wikipedia.org/wiki/Representational_state_transfer) and provides programmatic access to core messaging and user features. Use the API to send push notifications, emails, and SMS, manage Users, Subscriptions, Segments, and Journeys, export data, and configure apps.

## Which API to use

| Goal | API |
| - | - |
| Send a push, email, or SMS | [Create Message](/reference/create-message) |
| Add or update user data | [Create User](/reference/create-user) / [Update User](/reference/update-user) |
| Target a group of users | [Create Segments](/reference/create-segments) or use [Filters](/reference/create-message#filters) inline |
| Build or automate a Journey | [Create journey](/reference/create-journey), then [View journey](/reference/view-journey) / [Update journey](/reference/update-journey) |
| Export analytics or user data | [CSV Export](/reference/csv-export) / [CSV of Events](/reference/export-csv-of-events) |
| Manage app configuration | [Create App](/reference/create-an-app) / [Update App](/reference/update-an-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](https://www.cloudflare.com/ips/)

<Warning>
  Avoid allowlisting specific Cloudflare IPs, as they may change without notice.
</Warning>

**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](https://www.gstatic.com/ipranges/cloud.json)

<Note>
  OneSignal supports [IP allowlisting](/docs/en/keys-and-ids) with REST API keys.
</Note>

***

### Platform-specific network requirements

#### FCM (Google Android and Chrome push)

* Required ports: `5228`, `443`, `5229`, and `5230`
* No IP allowlisting needed
* More info: [Firebase Cloud Messaging (FCM)](https://firebase.google.com/docs/cloud-messaging/concept-options#messaging-ports-and-your-firewall)

#### 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:
  * [Apple Support](https://support.apple.com/en-us/102266)
  * [APNs Developer Docs](https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns?language=objc)

***

## Core API capabilities

### Send messages

See the [Create Message guide](/reference/create-message) to get started. Programmatically send:

<Columns cols={2}>
  <Card title="Push Notifications" icon="bell" href="/reference/push-notification">
    Send push notifications to apps and websites.
  </Card>

  <Card title="Email" icon="envelope" href="/reference/email">
    Send transactional and promotional emails.
  </Card>

  <Card title="SMS" icon="comment-sms" href="/reference/sms">
    Send SMS or MMS messages globally.
  </Card>

  <Card title="Live Activities" icon="tower-broadcast" href="/reference/start-live-activity">
    Send Live Activity updates to iOS devices.
  </Card>
</Columns>

<Note>
  For platform-specific features like personalization, throttling, and frequency capping, see the [Push](/docs/en/push), [Email](/docs/en/email-messaging), [SMS](/docs/en/sms-messaging), and [Live Activities](/docs/en/live-activities) overview guides.
</Note>

***

### Manage templates

[Templates](/docs/en/templates) are reusable push, email, and SMS messages that simplify development and improve consistency.

<Columns cols={2}>
  <Card title="Create template" icon="plus" href="/reference/create-template">
    Save a reusable message layout for push, email, or SMS.
  </Card>

  <Card title="Update template" icon="pen-to-square" href="/reference/update-template">
    Modify an existing template's content or settings.
  </Card>

  <Card title="View templates" icon="eye" href="/reference/view-templates">
    List all templates in your app with their metadata.
  </Card>

  <Card title="Delete template" icon="trash" href="/reference/delete-template">
    Permanently remove a template from your app.
  </Card>
</Columns>

***

### Track custom events

[Custom events](/docs/en/custom-events) record user actions like purchases, content views, or milestones. Use them to enter users into [Journeys](/docs/en/journeys-settings), trigger [Wait Until](/docs/en/journeys-actions) nodes, or [segment users by behavior](/docs/en/custom-events#segment-users-with-custom-events).

<Card title="Create custom events" icon="bolt" href="/reference/create-custom-events">
  Record user events to trigger Journeys, include in Segments, and track behavior.
</Card>

***

### Manage Journeys

Create, update, and view [Journeys](/docs/en/journeys-overview) programmatically to further automate multi-channel messages.

Journeys are always created in `draft`. [View journeys](/reference/view-journeys) to find an `id`, then [View journey](/reference/view-journey) for node ids and `concurrency_key`. Activate on [Update journey](/reference/update-journey) with `state: "active"` and poll until `state` is `active`. Patch one node with [Update journey node](/reference/update-journey-node) instead of replacing the graph. Archive to stop and keep data; [Delete journey](/reference/delete-journey) is permanent.

<Columns cols={2}>
  <Card title="Create journey" icon="plus" href="/reference/create-journey">
    Create a draft journey with an audience and node graph.
  </Card>

  <Card title="View journey" icon="eye" href="/reference/view-journey">
    Retrieve the full journey, including node ids and concurrency\_key.
  </Card>

  <Card title="Update journey" icon="pen-to-square" href="/reference/update-journey">
    Apply a partial update, or activate a draft.
  </Card>

  <Card title="View journey stats" icon="chart-simple" href="/reference/view-journey-stats">
    Retrieve journey, node, branch, and message delivery counts.
  </Card>
</Columns>

***

### Manage Users and Subscriptions

See the [Users](/docs/en/users) and [Subscriptions](/docs/en/subscriptions) guides for more details.

<Columns cols={2}>
  <Card title="Create user" icon="user-plus" href="/reference/create-user">
    Create a user with optional aliases and subscriptions.
  </Card>

  <Card title="View user" icon="eye" href="/reference/view-user">
    View user details.
  </Card>

  <Card title="Update user" icon="user-pen" href="/reference/update-user">
    Modify a User's properties, tags, or aliases.
  </Card>

  <Card title="Delete user" icon="user-minus" href="/reference/delete-user">
    Permanently remove a User and all associated data.
  </Card>
</Columns>

***

### Manage Segments

[Segments](/docs/en/segmentation) group Users by filters for targeted messaging.

<Columns cols={2}>
  <Card title="Create Segments" icon="plus" href="/reference/create-segments">
    Define a new Segment with filters to group Users.
  </Card>

  <Card title="Update Segment" icon="pen-to-square" href="/reference/update-segment">
    Modify a Segment's name or replace its filters.
  </Card>

  <Card title="Delete Segments" icon="trash" href="/reference/delete-segments">
    Permanently remove a Segment from your app.
  </Card>
</Columns>

<Note>
  You can also target users dynamically using [filters](/reference/create-message#filters) without creating persistent segments.
</Note>

***

### Export data

For analytics breakdowns, see [Analytics overview](/docs/en/analytics-overview).

<Columns cols={2}>
  <Card title="Export CSV of subscriptions" icon="file-export" href="/reference/csv-export">
    Export all user and subscription data.
  </Card>

  <Card title="Export CSV of events" icon="file-export" href="/reference/export-csv-of-events">
    Export events like sent, received, and clicked.
  </Card>

  <Card title="View messages" icon="eye" href="/reference/view-messages">
    View message details and analytics.
  </Card>

  <Card title="View message" icon="magnifying-glass" href="/reference/view-message">
    View individual message details.
  </Card>
</Columns>

***

### Manage Apps & API Keys

OneSignal allows you to group platforms (mobile apps, websites) under a single App ID. See [Apps, orgs, & accounts](/docs/en/apps-organizations).

<Columns cols={2}>
  <Card title="Create an app" icon="plus" href="/reference/create-an-app">
    Register a new app with platform credentials.
  </Card>

  <Card title="Update an app" icon="pen-to-square" href="/reference/update-an-app">
    Modify app settings or platform credentials.
  </Card>

  <Card title="View single app" icon="eye" href="/reference/view-an-app">
    Retrieve configuration and details for one app.
  </Card>

  <Card title="View multiple apps" icon="list" href="/reference/view-apps">
    List all apps in your account.
  </Card>
</Columns>

#### API key management

See [Keys & IDs](/docs/en/keys-and-ids) for more details.

<Columns cols={2}>
  <Card title="Create API key" icon="key" href="/reference/create-api-key">
    Generate a new API key with specific permissions.
  </Card>

  <Card title="View API keys" icon="eye" href="/reference/view-api-keys">
    List all API keys and their permissions for your app.
  </Card>

  <Card title="Delete API key" icon="trash" href="/reference/delete-api-key">
    Revoke an API key permanently.
  </Card>

  <Card title="Update API key" icon="pen-to-square" href="/reference/update-api-key">
    Modify an API key's permissions or IP allowlist.
  </Card>
</Columns>

***

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

<Card title="Rate limits and error handling" icon="triangle-exclamation" href="/reference/rate-limits">
  Retry strategies, error definitions, and recovery steps.
</Card>

***

## FAQ

### What is the timeout for API responses?

* Default: **100 seconds**
* If you're unsure whether a request completed, use an [`idempotency_key`](/reference/idempotent-notification-requests) to safely retry.
* See [Rate limits and error handling](/reference/rate-limits) for more details.

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

<Accordion title="Certificate pinning details and workarounds">
  * **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:

  ```bash theme={null}
  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](https://developers.cloudflare.com/ssl/get-started/) and [Cloudflare Edge Certificates documentation](https://developers.cloudflare.com/ssl/edge-certificates/) for more details.
</Accordion>

### 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](/docs/en/keys-and-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.
* **Journeys not enabled**: Journey endpoints return `403` with code `journey-not-entitled` when Journeys are not enabled for the app.
* **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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.