POST
/
apps
/
{app_id}
/
segments
curl --request POST \
  --url https://api.onesignal.com/apps/{app_id}/segments \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '{
  "id": "<string>",
  "name": "YOUR_SEGMENT_NAME",
  "filters": [
    {
      "field": "tag",
      "relation": ">",
      "key": "<string>",
      "value": "<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

Response

201
application/json

201

The response is of type object.