Skip to main content
POST
/
apps
/
{app_id}
/
segments
Create segment
curl --request POST \
  --url https://api.onesignal.com/apps/{app_id}/segments \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "name": "YOUR_SEGMENT_NAME",
  "filters": [
    {
      "field": "tag",
      "relation": "=",
      "key": "<string>",
      "value": "<string>"
    }
  ],
  "id": "<string>"
}
'
"{\"success\": true, \"id\": \"7ed2887d-bd24-4a81-8220-4b256a08ab19\"}"

​
Overview

Use this API to create new Segments programmatically. These segments are then accessible in the OneSignal Dashboard and usable in messages, Journeys, and in-app messaging campaigns.
This endpoint creates segments only. It does not support editing existing segments. To make changes, delete the existing segment and create a new one.

​
How to use this API

This endpoint allows your backend to define audience segments by passing in a combination of filters and logical operators like "AND" and "OR", mirroring the segmentation capabilities of the OneSignal Dashboard.

​
Name the segment

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

​
Define the filters

Available filters:

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

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

Headers

​
Authorization
string
default:Key YOUR_APP_API_KEY
required

Your App API key with prefix Key. See Keys & IDs.

​
Content-Type
string
default:application/json; charset=utf-8
required

Path Parameters

​
app_id
string
default:YOUR_APP_ID
required

Your OneSignal App ID in UUID v4 format. See Keys & IDs.

Body

application/json
​
name
string
default:YOUR_SEGMENT_NAME
required

An internal name you set to help organize and track Segments. Maximum 128 characters.

​
filters
(Filter · object | Operator · object)[]
required

Filters define the segment based on user properties like tags, activity, or location using flexible AND/OR logic. Limited to 200 total entries, including fields and OR operators. See Sending messages with the OneSignal API.

Required array length: 1 - 200 elements

Required. The fitler object.

  • Filter
  • Operator
​
id
string

UUID of the segment. If left empty, it will be assigned automatically.

Response

201

​
success
boolean
default:true

true if the segment was created successfully, false otherwise.

​
id
string

The UUID of the created segment.