Server REST API Reference
Log InSign Up

Create segment

post https://api.onesignal.com/apps//segments

Create segments visible and usable in the dashboard and API.

Overview

The Create Segment method is used when you want your server to programmatically create a segment instead of using the OneSignal Dashboard UI.

🚧

Does not update segments

This endpoint will only create segments, it does not edit or update currently created Segments.

How to use this API

Just like creating Segments from the dashboard, you can pass in filters with multiple "AND" or "OR" operator's.

This API only creates Segments, there is not an option to update segments at this time. Instead, you can use the Delete Segments endpoint and create a new segment to edit. However, if this segment is associated with a Journey or in-App message, you will need to login to the dashboard to update it.

Body parameters

name

Type string

Description

The name of the segment as it shows in the OneSignal dashboard and accessible via the included_segments and excluded_segments targeting parameters.


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:

Filter property definitions (click to expand)

operator

Description

Allows you to combine or separate properties. Filters combined with an "AND" have higher priority than "OR" filters.

  • "AND" = the 2+ connected filters must be satisfied for the recipient to be included. Filter entries use this by default and its not required to be included.
  • "OR" = the 2 filters separated by the "OR" operator are mutually exclusive. The recipients only need to satisfy the conditions on either side of the "OR" operator.
// Users must satisfy both filters to be included.
// Notice the AND operator is not required 

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

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

// 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"}
  ]
}

tag

Description

Maps to the Tags set on Users.

Do not use tags for targeting individual users like a "user id". Instead use External ID or custom Aliases and the include_aliases targeting property.

  • relation = ">", "<", "=", "!=", "exists", "not_exists", "time_elapsed_gt", (time elapsed greater than) and "time_elapsed_lt" (time elapsed less than)
    • The time_elapsed_gt/lt fields correspond to Time Operators and require a paid plan.
  • key = Tag key to compare.
  • value = Tag value to compare. Not required for "exists" or "not_exists". 
"filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"}
]

last_session

Description

Maps to the last active time the Subscriptions used the app.

  • relation = ">" or "<"
  • hours_ago = number of hours before or after the user's last session. Example: "1.1"
"filters": [
  {"field": "last_session", "relation": ">","hours_ago": "10"}
]

first_session

Description

Maps to the first date and time the Users were created within OneSignal.

  • relation = ">" or "<"
  • hours_ago = number of hours before or after the user's first session. Example: "1.1"
"filters": [
  {"field": "first_session", "relation": "<","hours_ago": "24"}
]

session_count

Description

Maps to the amount of sessions for the Subscriptions.

  • relation = ">", "<", "=" or "!="
  • value = number sessions. Example: "1"
"filters": [
  {"field": "session_count", "relation": ">","value": "5"}
]

session_time

Description

Maps to the usage duration of your Subscriptions which is the total number of seconds they had your app open.

  • relation = ">" or "<"
  • value = Time in seconds the user has been in your app. Example: 1 day is "86400" seconds
"filters": [
  {"field": "session_time", "relation": ">","value": "86400"}
]

language

Description

Maps to the language code of your Users. See Multi-Language Messaging for details and supported language codes.

  • relation = "=" or "!="
  • value = 2 character language code. Example: "en". 
"filters": [
  {"field": "language", "relation": "=","value": "en"},
  {"operator": "OR"},
  {"field": "language", "relation": "=","value": "es"}
]

app_version

Description

Maps to your app version set on Subscriptions.

  • relation = ">", "<", "=" or "!="
  • value = app version. Example: "1.0.0"
"filters": [
  {"field": "app_version", "relation": "=","value": "1.0.1"}
]

location

Description

Maps to the GPS coordinates of the device. Location tracking must be turned on and accepted by the user. See Location-Triggered Notifications for more details.

  • radius = in meters
  • lat = latitude
  • long = longitude
"filters": [
  {"field": "location", "radius": "1000","lat": "37.77", "long":"-122.43"}
]

amount_spent

Description

The amount of consumable in-app purchases made while our SDK was active on the mobile app.

If you have subscription-based purchases, a website, email-only, and/or SMS-only users, then you should consider using Tags instead.

  • relation = ">", "<", or "="
  • value = Amount in USD a user has spent on IAP (In App Purchases). Example: "0.99"
"filters": [
  {"field": "amount_spent", "relation": ">","value": "100"}
]

bought_sku

Description

Maps to the purchases property on Users. The stock-keeping unit (SKU) identifier for the purchased item.

  • relation = ">", "<" or "="
  • key = SKU purchased in your app as an IAP (In App Purchases). Example: "com.domain.100coinpack"
  • value = value of SKU to compare to. Example: "0.99"
"filters": [
  {"field": "bought_sku", "relation": ">","key":"com.domain.100coinpack","value": "10"}
]
Language