Segment model properties

This guide describes the available options for conditions for the API create segment endpoint.

For more information on segments review our segmentation guide.

Conditions

Conditions have the following basic format:

{
    "title": "Test",
    "conditions":  {
        "operator": "AND",
        "0": {
            "operator": "AND",
            "0": [ condition1 ],
            "1": [ condition2 ], 
             .....
        } .....
    }
}

An operator is used between groups of conditions. Options are AND or OR. Groups of conditions are label from 0-n, ie. "operator": "AND", "0": {group 1}, "operator": "AND", "1": {group 2}, ......

An operator is also used for at the start of a group of conditions. All conditions are combined using this operator.

An individual condition is made up of a mix of possible components:

keyword
- comparator
- value
option
- comparator
- value
date modifier
- dates

All conditions must use a keyword to indicate what type of condition is to be used, and a comparator and value to describe a relationship that defines the condition such as "country equals Ireland". Some conditions have an option such as hits for location and tags that also takes a comparator and value, for example "tag Facebook sign-in hit more than 10 times". Some conditions also support date modifiers to link the condition to a time period. There are two options: date range, or a number of days ago. For example "tag Facebook sign-in hit more than 10 times from the 1st to the 30th of Feb".

Overall length of a segment cannot exceed 262,144 characters.

A full break down of condition options is given in the following table:

Keyword	Comparator	Option	Date Modifier
segment	equals a specific segment ID
tags	equals a specific tag ID/title	`hits` more than, less than or equal to a number of times	daterange or days ago, optional if not used defaults to all time
tags_flag	equals a specific flag ID/title	`status` on/off
tags_attribute	equals a specific tag ID/title that is an attribute with a specific value	`value` equals, not equals, more than, less than
tags_attribute_date	a specific tag ID/title that is a date attribute with a specific value	value relates to date with options - in the last, prior to, and in date range	integer number of days/hours/minutes,integer number of days/hours/minutes ago, and daterange
locations	equals a specific location ID	`hits` more than, less than or equal to a number of times	daterange or days ago, optional if not used defaults to all time
app_opened	more than, less than or equal to a number of times	daterange or days ago, optional if not used defaults to all time
app_last_opened	within time period set using date modifier		daterange or days ago
app_downloaded	within time period set using date modifier		daterange or days ago
country	Equal or not equal to a two character country code (ISO 3166-1 alpha-2), eg. `["country", "=", "IE"]`
language	Equal or not equal to a devices selected language (ISO 3166-1 alpha-2), eg. `[ "language", "=", "Spanish" ]`
carrier_name	Equal or not equal to a carrier or mobile network operator, eg. `[ "carrier_name", "!=", "T-Mobile" ]`
device_os	Equal or not equal to specific device OS, eg. `[ "device_os", "!=", "8.2" ]`
device_model	Equal or not equal to specific device model, e.g. `[ "device_model", "=", "iPhone 6" ]`
app_version	Equal or not equal to specific app version, eg. `[ "app_version", "=", "8.2" ]`
id	Xtremepush ID, or `in` or `not in` a list of IDs, eg. `[ "id", "in", [ID1, ID2, ...] ]`
token	Equal or not equal to a specific device token, or `in` or `not in` a list of tokens, eg. `[ "token", "=", "TOKEN" ]`
device_id	Equal or not equal to a specific device ID (IDFV on iOS or Android ID on Android, or `in` or `not in` a list of device IDs, eg. `[ "device_id", "=", "DEVICE_ID" ]`

Condition examples

Tags:

[
    "tags", 
    "=",
    "TAG_ID or TAG_TITLE",
    ["hits", "> / < / =", "number of hits"]
    daterange or days ago (optional) (see examples below)
]

Flags:

[
    "tags_flag",
    "=",
    "TAG_ID or TAG_TITLE",
    ["status", "=", "on / off"]
]

Attributes:

[
    "tags_attributes",
    "=",
    "TAG_ID or TAG_TITLE",
 ["value", "> / < / = / !=", "some value"]
]

Date Attributes:

[
    "tags_attributes",
    "=",
    "TAG_ID or TAG_TITLE",
    null, 
   ["date", "in_the_last", ["2","days/hours/minutes"]],
]

Locations:

[
    "locations", 
    "=",
    "LOCATION_ID",
    ["hits", "> / < / =", "number of hits"],
    daterange or days ago (optional) (see examples below)
]

App opened all time:

[
    "app_opened",
    "> / < / =",
    "10"
]

App opened with date range:

[
    "app_opened",
    "> / < / =",
    "10",
    null,
    daterange or days ago (see examples below)
]

App downloaded:

[
    "app_downloaded",
    null,
    null,
    daterange or days ago (see examples below)
]

Daterange format:

["daterange", "between", "2015-01-01 to 2015-01-30", "2015-01-01", "2015-01-30"]

Days ago format:

["days_ago", "> / < / =", null, null, null, "10"]

Example

A segment combining a tag, the number of days since the app was downloaded and a country:

curl --request POST \
  --url https://external-api.xtremepush.com/api/external/create/segment \
  --header 'content-type: application/json' \
  --data '{
    "apptoken": "YOUR_APPTOKEN",
    "title": "Test",
    "conditions":  {
      "operator": "AND",
      "0": {
        "operator": "AND",
        "0": [
          "tags",
          "=",
          "test",
          ["hits", ">", "5"],
          ["daterange", "between", "2015-01-01 to 2015-01-30", "2015-01-01", "2015-01-30"]            
        ],
        "1": [
          "app_downloaded",
          null,
          null,
          ["days_ago", ">", null, null, null, 10]
        ],
        "2": [
          "country",
          "=",
          "IE"
        ]
      }
    }
  }'