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://api.eu.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"
        ]
      }
    }
  }'