Programmatic Notifications

Programmatic notifications are sent in response to events triggered from your server, such as a user's trial ending soon, or their order being ready for pickup. They're the backbone of transactional and behavioral messaging, and they're sent via the OneSignal REST API rather than the dashboard.

This guide covers when to use the API, how to target users by different methods, and a working example.

📘

OneSignal REST API Documentation

The full documentation is available at https://documentation.onesignal.com/reference/push-notification

When to use programmatic notifications

Use the REST API when a notification is triggered by something that happens in your system instead of manually hitting send.

Common use cases:

• Order and shipping updates: notify a user when their status changes
• Message alerts: let users know they have a new message waiting
• Account activity: password changes, login attempts, payment confirmations
• Re-engagement: reach users who haven't opened the app after a number of days
• Personalized reminders: based on a user's saved preferences or upcoming events

For one-off campaigns and broadcasts, sending from the OneSignal dashboard is usually faster.

Targeting by user

The most common use case is to send the notification to all devices belonging to a specific user. This requires associating the user with an identifier via median.onesignal.login(). See Identifying & targeting users for how to set that up.

User Identifiers

Targeting by segment

Segments let you broadcast to large groups of users defined by shared attributes such as data tags, subscription status, location, and more.

{
  "app_id": "{{YOUR_ONESIGNAL_APP_ID}}",
  "target_channel": "push",
  "included_segments": ["Active Users"],
  "excluded_segments": ["Already Purchased"],
  "contents": { "en": "Don't miss our weekend sale." }
}

You can include multiple segments and exclude others in the same request. Segments are created and managed in the OneSignal dashboard. See Identifying & targeting usersm for how to use data tags to build segments programmatically.

Targeting by specific device

To target one specific device, for example, the device a user is currently active on, use the subscription.id. Retrieve this from the oneSignalInfo object in your app and store it in your backend.

{
  "app_id": "{{YOUR_ONESIGNAL_APP_ID}}",
  "target_channel": "push",
  "include_subscription_ids": ["device-subscription-id-here"],
  "contents": { "en": "Your verification code is 482910." }
}

The subscription.id is linked to the app on the user's device. It only changes if the app is uninstalled and reinstalled. For most personalized notifications, targeting by external_id is more reliable.

Finding your App ID and API key

1. Log in to your OneSignal dashboard.
2. Select your app.
3. Go to Settings > Keys & IDs.

❗️

Your REST API Key is a server-side secret. Never include it in client-side JavaScript or mobile app code; it authorizes sending notifications on your behalf.

Full example: send to a user by external ID

Here's a complete request that sends a Order Shipped notification to a user targeted by their external ID. Replace the placeholder values with your own credentials from the OneSignal dashboard (Settings > Keys & IDs).

curl --location 'https://api.onesignal.com/notifications' \
--header 'Authorization: Key {{YOUR_ONESIGNAL_REST_API_KEY}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
  "app_id": "{{YOUR_ONESIGNAL_APP_ID}}",
  "target_channel": "push",
  "headings": {
    "en": "Your order has shipped",
    "es": "Tu pedido ha sido enviado"
  },
  "contents": {
    "en": "Order #1042 is on its way. Tap to track.",
    "es": "El pedido #1042 está en camino. Toca para rastrear."
  },
  "data": {
    "targetUrl": "https://yourapp.com/orders/1042"
  },
  "include_aliases": {
    "external_id": [EXTERNAL_ID]
  }
}'

Key fields: