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>",
  "description": "YOUR_SEGMENT_DESCRIPTION"
}
'
{
  "success": true,
  "id": "7ed2887d-bd24-4a81-8220-4b256a08ab19"
}

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.

​
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.
To modify an existing segment, use the Update segment API.

​
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.

​
Describe the segment

Optionally include a description (max 255 characters) to record the segment’s purpose. The description is returned by the View segments and View segment APIs. 
{
  "name": "YOUR_SEGMENT_NAME",
  "description": "YOUR_SEGMENT_DESCRIPTION",
  "filters": [
    {"field": "session_count", "relation": ">", "value": "10"}
  ]
}

​
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 Target based on custom user Tags.
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)
    • 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 Time since the Subscription last used the app (in hours_ago).
  • 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 Time since the User first used the app or was created within OneSignal (in hours_ago).
  • 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 Total number of sessions by the Subscription.
  • relation = ">", "<", "=" or "!="
  • value = number of sessions. Example: "1" 
    "filters": [
  {"field": "session_count", "relation": ">","value": "5"}
]

​
session_time

Description Total time the Subscription has spent in the app, in seconds.
  • 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 User’s language code (e.g., “en”). See Multi-Language Messaging for details and supported language codes.
  • relation = "=", "!=", "in_array", or "not_in_array"
  • value = 2 character language code. Example: "en". For "in_array" and "not_in_array", the value should be a comma-separated list of values. 
    "filters": [
  {"field": "language", "relation": "=","value": "en"},
  {"operator": "OR"},
  {"field": "language", "relation": "in_array","value": "es,fr,de"}
]

​
app_version

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

​
location

Description Target by GPS coordinates and radius. Location tracking must be turned on and accepted by the user. See Location-Triggered Notifications for details.
  • radius = in meters
  • lat = latitude
  • long = longitude 
    "filters": [
  {"field": "location", "radius": "1000","lat": "37.77", "long":"-122.43"}
]

​
country

Description Country code of your Users. Uses ISO 3166-1 Alpha-2 format (two-letter country code).
  • relation = "=", "!=", "in_array", or "not_in_array"
  • value = Two-letter country code in uppercase. Example: "US", "GB", "CA". For "in_array" and "not_in_array", the value should be a comma-separated list of values. 
    "filters": [
  {"field": "country", "relation": "=", "value": "US"},
  {"operator": "OR"},
  {"field": "country", "relation": "in_array", "value": "MA,GB,LK"}
]

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.

​
id
string

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

​
description
string
default:YOUR_SEGMENT_DESCRIPTION

Optional human-readable description for the segment. Maximum 255 characters.

Maximum string length: 255

Response

201

​
success
boolean
default:true

true if the segment was created successfully, false otherwise.

​
id
string

The UUID of the created segment.