POST/io/contacts/segments

Creates a segment. Dynamic segments are auto-evaluated against contacts on refresh; static segments hold an explicit membership list.

Request body

namestringbodyrequired

Segment name.

descriptionstringbody

Optional description.

segmentTypestringbody

dynamic (default) | static.

filterCriteriaobjectbodyrequired

Filter tree. Top-level must be a FilterGroup: { operator: "AND"|"OR", rules: [...] }. Each rule: { field, operator, value }.

{
  "name": "High-value subscribers",
  "segmentType": "dynamic",
  "filterCriteria": {
    "operator": "AND",
    "rules": [
      { "field": "status", "operator": "eq", "value": "subscribed" },
      { "field": "lead_score", "operator": "gte", "value": 50 }
    ]
  }
}

{
  "data": {
    "id": "seg_abc",
    "name": "High-value subscribers",
    "segment_type": "dynamic",
    "contact_count": 0,
    "created_at": "2026-06-11T12:00:00Z"
  }
}

Create Segment