This page describes the fields for the segment create API endpoint

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"
        ]
      }
    }
  }'