> ## 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, 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, 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 |
| 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) or trigger [Wait Until](/docs/en/journeys-actions) nodes.

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

***

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