Segment filter reference

Contents

• Overview
• Version-specific information
• Segment structure
• Rule structure
• Field types
• Operators
• Time factors
• Join logic
• Examples

Overview

When creating export tasks, you can filter results using segment rules. A segment is a set of rules that define which records to include in the export. This page documents the available operators, field types, time factors, and rule structure.

Segments are used in the trigger.segment field of a task request. See Scheduling and triggers in the Tasks API reference for how segments fit into the task creation flow.

Version-specific information

Version	Change details
N/A	N/A

Segment structure

A segment is a JSON object with the following fields:

Field	Type	Description
entity	string	Always set to "people".
index	string	The data index to filter. One of: users, transactions, vouchers, wallet-ledger, products, product-variants.
join	string	How to combine multiple rules: "all" (AND — all rules must match) or "any" (OR — at least one rule must match).
chain_id	integer	Your chain ID.
rules	array	An array of rule objects (see below).

Rule structure

Each rule in the rules array is a JSON object. The required fields depend on the operator:

Field	Type	Used with	Description
field_name	string	All operators	The field to filter on (e.g. timestamp, country).
field_type	string	All operators	The type of the field (see Field types below).
operator	string	All operators	The comparison operator (see Operators below).
value	any	is, is_not, contains, does_not_contain, is_date	The value to compare against.
start_date	string	is_after_date, is_between_date	ISO 8601 datetime for the start of a range.
end_date	string	is_before_date, is_between_date	ISO 8601 datetime for the end of a range.
time_factor	string	relative_* operators	The time unit (see Time factors below).
time_amount	integer	relative_* operators	The number of time units.
min	number	is_between_number	Minimum value for a numeric range.
max	number	is_between_number	Maximum value for a numeric range.
nested	boolean	Nested fields	Set to true for nested document fields.
nesting_path	string	Nested fields	The path for nested fields (e.g. transaction, line_items).

Field types

Field type	Description	Example fields
date	Date/time field	timestamp, created_date, date_time_redeemed
keyword	Exact-match string field	country, status, retailer_basket_code
text	Text searchable string field	username, first_name
integer	Whole number field	id, chain_id
float	Decimal number field	amount, total_value
boolean	True/false field	opted_in, registered
geo_point	Geographic coordinate field	geo_location

Operators

Date operators

Use these operators with fields of type date.

Operator	Description	Required fields
is_date	Records on a specific day	value (ISO 8601 date)
not_is_date	Records NOT on a specific day	value (ISO 8601 date)
is_before_date	Records before a specific date	end_date
not_is_before_date	Records NOT before a specific date	end_date
is_after_date	Records after a specific date	start_date
not_is_after_date	Records NOT after a specific date	start_date
is_between_date	Records between two dates (inclusive)	start_date + end_date
not_is_between_date	Records NOT between two dates	start_date + end_date

Relative date operators

Use these for rolling time windows relative to the current time (e.g. "last 7 days").

Operator	Description	Required fields
relative_less_than	Within the last N time units (e.g. last 7 days)	time_factor + time_amount
not_relative_less_than	NOT within the last N time units	time_factor + time_amount
relative_more_than	More than N time units ago	time_factor + time_amount
not_relative_more_than	NOT more than N time units ago	time_factor + time_amount
relative_exactly	Exactly N time units ago (within that unit's window)	time_factor + time_amount
not_relative_exactly	NOT exactly N time units ago	time_factor + time_amount

String/keyword operators

Use these operators with fields of type keyword or text.

Operator	Description	Required fields
is	Exact match	value
is_not	Does not match	value
contains	Contains the value (substring match for text fields)	value
does_not_contain	Does not contain the value	value

Number operators

Use these operators with fields of type integer or float.

Operator	Description	Required fields
is_lte	Less than or equal to	value
not_is_lte	NOT less than or equal to	value
is_gte	Greater than or equal to	value
not_is_gte	NOT greater than or equal to	value
is_between_number	Between min and max (inclusive)	min + max
not_is_between_number	NOT between min and max	min + max

Boolean operators

Use these operators with fields of type boolean.

Operator	Description	Required fields
is_true	Field is true	None
is_false	Field is false	None

Existence operators

Use these to check whether a field has any value.

Operator	Description	Required fields
not_empty	Field has a value (exists)	None
is_empty	Field has no value (not set)	None

Geo operators

Use these operators with fields of type geo_point.

Operator	Description	Required fields
is_within_geo_distance	Within a radius of a point	geo_point_values, geo_distance_amount, geo_distance_factor
is_not_within_geo_distance	NOT within a radius of a point	geo_point_values, geo_distance_amount, geo_distance_factor
is_within_geo_bounding_box	Within a bounding box	geo_point_top_left, geo_point_bottom_right
is_not_within_geo_bounding_box	NOT within a bounding box	geo_point_top_left, geo_point_bottom_right

Time factors

Used with relative date operators to specify the time unit:

Time factor	Description
year	Years
month	Months
week	Weeks
day	Days
hour	Hours
minute	Minutes
second	Seconds

Join logic

The join field in the segment determines how multiple rules are combined:

Value	Logic	Description
all	AND	All rules must match for a record to be included.
any	OR	At least one rule must match for a record to be included.

Examples

Export transactions from a specific date range

{
  "entity": "people",
  "index": "transactions",
  "join": "all",
  "chain_id": YOUR_CHAIN_ID,
  "rules": [
    {
      "field_name": "timestamp",
      "field_type": "date",
      "operator": "is_between_date",
      "start_date": "2026-03-01T00:00:00Z",
      "end_date": "2026-03-31T23:59:59Z"
    }
  ]
}

Export users created in the last 30 days who are opted in

{
  "entity": "people",
  "index": "users",
  "join": "all",
  "chain_id": YOUR_CHAIN_ID,
  "rules": [
    {
      "field_name": "created_date",
      "field_type": "date",
      "operator": "relative_less_than",
      "time_factor": "day",
      "time_amount": 30
    },
    {
      "field_name": "opted_in",
      "field_type": "boolean",
      "operator": "is_true"
    }
  ]
}

Filter vouchers for a specific campaign

{
  "entity": "people",
  "index": "vouchers",
  "join": "all",
  "chain_id": YOUR_CHAIN_ID,
  "rules": [
    {
      "field_name": "campaign_title",
      "field_type": "text",
      "operator": "is",
      "value": "Summer Sale 2026"
    }
  ]
}