Create segment
Programmatically create segments in your OneSignal app using flexible filters and targeting rules.
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.
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.
- The
key
= Tag key to compare.value
= Tag value to compare. Not required for"exists"
or"not_exists"
.
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"
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"
session_count
Description
Maps to the amount of sessions for the Subscriptions.
relation
=">"
,"<"
,"="
or"!="
value
= number sessions. Example:"1"
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
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"
.
app_version
Description
Maps to your app version set on Subscriptions.
relation
=">"
,"<"
,"="
or"!="
value
= app version. Example:"1.0.0"
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 meterslat
= latitudelong
= longitude
Path Parameters
Your OneSignal App ID in UUID v4 format. See Keys & IDs.
Body
Response
201
The response is of type object
.