General

name

Type string

Description

Serves as an internal identifier to help organize your notification campaigns. The name is not visible to the end-users and is used solely for your purposes within your campaign management workflow.

Guidance

Assign meaningful names that reflect your notification campaign's purpose, content, or target audience to facilitate easier tracking and management of multiple campaigns.

custom_data

Type object

Description

User-specific or context-specific information for Message Personalization.

Guidance

• The object must be in JSON format.
• The payload may include up to 2,048 bytes for Push and SMS notifications and up to 10 kilobytes for email messages.

Example

{
  "custom_data": {
    "cart_items": [
      {
        "item_name": "sweater",
        "img_url": "https://store.onesignal.com/assets/sweater.png"
      },
      {
        "item_name": "socks",
        "img_url": "https://store.onesignal.com/assets/socks.png"
      }
    ]
  }
}

💡

Leverage Custom Data to personalize your transactional messages.

external_id

Type string

Description

Acts as a correlation identifier and an idempotency key to prevent duplicate notification deliveries. This is not the User External ID. Idempotent Notification Requests enable you to send requests while ensuring users receive a message only once. Messages with the same external_id send only one notification, and subsequent responses return the same result.

Guidance

• Keys must be unique. We recommend using a universally unique identifier (UUID) for this.
• The key remains idempotent for 30 days, meaning any request with the same external_id will not result in additional messages sent within this period. After 30 days, a notification with the same external_id may be considered a new request and could result in a new message being sent.

Example

{
  "external_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

☝ Ensures users receive the message once, even if there are any retry attempts or duplicated requests within a 30-day window.

Targeting

included_segments

Type string[]

Description

The segments to target for sending the message to. Members of each segment will receive the notification unless they're also members of a segment specified in the optional excluded segments parameter.

Guidance

Provide an array of the Segment names.

Example

{
  "included_segments": [
    "Active Users",
    "Inactive Users"
  ]
}

excluded_segments

Type string[]

Description

Segments to exclude from receiving the message. Overrides membership in any segment specified in the included_segments parameter.

Guidance

Provide an array of the Segment names.

Example

Target a message for customers who've spent $5K or more while excluding those deemed inactive, even if they are included in the segment "CLTV 5K".

{
  "included_segments": [
    "CLTV 5K"
  ],
  "excluded_segments": [
    "Inactive Users"
  ]
}

filters

Type object[]

Description

Filters allow you to dynamically define your message's audience based on their properties. They can be combined with "AND" and "OR" operators for complex targeting logic, enabling precise audience segmentation.

For performance reasons, a maximum of 200 entries can be used. The 200 entries limit includes the "field" entry and "OR" entries - each would count towards the 200 limit.

Filter performance:

• Tag filters using an equality ("=") or "exists" operator are very fast.
• Negation (eg. "!=" and "not_exists") is inherently more expensive to compute because it depends on how many tags per user are set. Upon request, it is sometimes possible for us to create a specific index on your application to address problems with negation.
• Numeric ordering operators like "<" or ">" are slow by default. Note that upon special request, we can add a special index for specific tags to improve performance of these operators.
• Filters on the "last_session", "session_count", and "country" fields are fast on their own or together, but when used with other filters such as tags can make the segment take longer to compute.

Available filters:

• operator
• tag
• last_session
• first_session
• session_count
• session_time
• language
• app_version
• location
• amount_spent
• bought_sku

// Users must satisfy both filters to be included.
// Notice the AND operator is not required 

"filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"field": "amount_spent", "relation": ">","value": "0"}
]

// The same example using the AND operator. This is not required.
"filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"operator": "AND"},
  {"field": "amount_spent", "relation": ">","value": "0"}
]

// Users can satisfy either filter to be included.

"filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"}, 
  {"operator": "OR"}, 
  {"field": "tag", "key": "level", "relation": "=", "value": "20"}
]

// In this example, users must either have:
// The specified session_count AND tag requirement
// Or it will be all records where last_session is satisfied
{
  "name": "2 filters or 1",
  "filters": [
    {"field": "session_count", "relation": ">", "value": "2"},
    {"operator": "AND"},
    {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
    {"operator": "OR"},
    {"field": "last_session", "relation": "<", "hours_ago": "30"}
  ]
}

// Similar to the first example, this shows how to require a specific field
// across other filters

{
  "name": "3 filters, 1 required across all",
  "filters": [
    {"field": "session_count", "relation": ">", "value": "2"},
    {"operator": "AND"},
    {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
    {"operator": "OR"},
    {"field": "last_session", "relation": "<", "hours_ago": "30"},
    {"operator": "AND"},
    {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"}
  ]
}

"filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"}
]

"filters": [
  {"field": "last_session", "relation": ">","hours_ago": "10"}
]

"filters": [
  {"field": "first_session", "relation": "<","hours_ago": "24"}
]

"filters": [
  {"field": "session_count", "relation": ">","value": "5"}
]

"filters": [
  {"field": "session_time", "relation": ">","value": "86400"}
]

"filters": [
  {"field": "language", "relation": "=","hours_ago": "en"},
  {"operator": "OR"},
  {"field": "language", "relation": "=","hours_ago": "es"}
]

"filters": [
  {"field": "app_version", "relation": "=","hours_ago": "1.0.1"}
]

"filters": [
  {"field": "location", "radius": "1000","lat": "37.77", "long":"-122.43"}
]

"filters": [
  {"field": "amount_spent", "relation": ">","value": "100"}
]

"filters": [
  {"field": "bought_sku", "relation": ">","key":"com.domain.100coinpack","value": "10"}
]

include_aliases

Type object

Description

Targets specific users based on their Aliases & External ID.

Guidance

• Provide an object of aliases to include.
  • User's External ID – external_id
  • OneSignal ID – onesignal_id
  • Custom alias name – some_custom_alias
• You may include up to 2,000 Alias IDs per API call.

Example

Send a message to the users identified by the EUIDs "one", "two", and "three" using the push channel.

{
  "include_aliases": {
    "external_id": [
      "one",
      "two",
      "three"
    ]
  }
}

💡

Use with the target_channel parameter to control the delivery channel.

include_subscription_ids

Type string[]

Description

Allows targeting users based on their Subscription ID.

Guidance

You may include up to 2,000 IDs per API call.

Example

{
  "include_subscription_ids": [
    "1dd608f2-c6a1-11e3-851d-000c2940e62c"
  ]
}

target_channel

Type string

Description

The channel in which to deliver a message. Use in conjunction with include_aliases.

Guidance

Choose from the following options:

• "push" – send the message as a push notification
• "email" - send the message as an email
• "sms" - send the message as a text message

Example

{
  "target_channel": "push"
}

Delivery

send_after

Type string

Description

Schedule notifications for future delivery; defaults to Coordinated Universal Time (UTC). Align delivery with your target users' time zones so they're more likely to see it.

Guidance

Specify the string according to the ISO 8601 calendar format. A heuristic you can use to determine whether we can parse your date-time string is whether Javascript's Date constructor can parse the string.

Example

All of the following are valid and equivalent formats for the same date and time:

• { "send_after": "Thu Sep 24 2015 14:00:00 GMT-0700 (PDT)" }
• { "send_after": "2015-09-24 14:00:00 GMT-0700" }
• { "send_after": "Sept 24 2015 14:00:00 GMT-0700" }

delayed_option

Type string

Description

Choose how deliveries should be scheduled.

Guidance

• timezone – simultaneous across time zones at the same local time.
• last-active – enable Intelligent Delivery, which schedules notifications based on the user's Last Active Session.

Example

Deliver the notification worldwide at 9 AM in each user's local time zone.

{
  "delayed_option": "timezone",
  "send_after": "2024-03-05T15:00:00.600Z"
}

🚧

Incompatible with Message Throttling

Set throttle_rate_per_minute to 0 to disable throttling.

delivery_time_of_day

Type string

Description

Specify when the message should be delivered when the delayed_option parameter is "timezone". It's ideal for time-sensitive daily digests, reminders, or promotions.

Guidance

• Format the time as a string, which can be in various formats such as:
  • 12-hour e.g., "9:00AM"
  • 24-hour e.g., "21:45"
  • HH:mm:ss format - e.g., "9:45:30"

Example

Schedule a notification for all users in the morning at 9:00 AM local time.

{
  "delayed_option": "timezone",
  "delivery_time_of_day": "9:00AM"
}

Path

notification_id

The identifier of the message of interest. Locating this value depends on how the message was created.

• Create Notification API - the response's id property.
• View Notifications API
• The URL of the Message Report page

Outcomes

Parameters for View Outcomes can be used with this View Notification API.

Search

app_id

Type string

Description

Identifies your application within our system.

Guidance

• The value must be a universally unique identifier (UUID).
• Refer to Keys & IDs to learn more.

limit

Type number

Description

Specifies the maximum number of notifications to return in a single query.

Guidance

This parameter helps control the volume of data retrieved during one operation, especially when navigating many notifications.

• The default value is 50.
• The maximum value that can be used is 50.

offset

Type number

Description

Controls the starting point for the notifications being returned.

Guidance

Results are returned and sorted in descending order by queued_at.

• The default value is 0 (Starts at the beginning of your notification list).

kind

Type number

Description

Specifies the type of notifications to return.

Guidance

Use this to segment notifications by their creation method, allowing for targeted analysis or management of notification types.

• All notification types are returned by default.
• 0 — Notifications created through the dashboard.
• 1 — Notifications sent via API calls.
• 3 — Notifications triggered through automated systems.

template_id

Type string

Description

Specifies the identifier of a pre-defined template used to configure a message.

Guidance

To obtain the template_id, navigate to the relevant template in your dashboard. It's typically found in the URL or designated section within the template settings.