Understanding Segment Criteria

A segment's criteria is the logic that decides who's in it. Drive's criteria model is recursive: a criteria is either a single condition - a flag, or a dependency on another segment - or a logical combination of other criteria, joined with AND, OR, or NOT (for exclusions, including excluding everyone in a whole other segment). All of these can be mixed freely within one segment, so you can go from "renters" to "renters who are parents with stable income" to arbitrarily deep nested logic, using the same building blocks throughout.

The building blocks

A criteria is one of:

• A flag - a pre-built characteristic from the Flags catalogue: { "criteria": "flag", "name": "renter" }
• A segment dependency - "customers who are also in this other segment": { "criteria": "segment_dependency", "segment_id": "7e8aedf9-..." }
• A logical combination - logical_and, logical_or, or logical_not, each taking a list of nested operands (which can themselves be flags, segment dependencies, or further combinations)

For example, renters who are parents with stable income:

{
  "operator": "logical_and",
  "operands": [
    { "criteria": "flag", "name": "renter" },
    { "criteria": "flag", "name": "parent" },
    { "criteria": "flag", "name": "stable_income" }
  ]
}

And a more layered example - excluding anyone in a given segment, requiring a spending flag, and requiring at least one of two bill-payment flags:

{
  "operator": "logical_and",
  "operands": [
    { "operator": "logical_not", "operands": [{ "criteria": "segment_dependency", "segment_id": "65324d52-..." }] },
    { "criteria": "flag", "name": "top_25pct_spenders_on_mortgage" },
    {
      "operator": "logical_or",
      "operands": [
        { "criteria": "flag", "name": "pays_tv_phone_or_broadband_bill" },
        { "criteria": "flag", "name": "pays_energy_bill" }
      ]
    }
  ]
}

Discovering what's available

Before building a criteria, see what you can build it from:

GET /drive-api/v2/criteria/options

This lists every flag, segment you can depend on, and custom criteria available to your organisation, each with a _template you can use as a starting point. Pass ?filter=flags (or segments, custom_criteria) to narrow it down.

Draft, run, save

Criteria are built as drafts, so you can iterate before committing to a segment:

1. POST /drive-api/v2/criteria/drafts - creates an empty draft, returning its criteria_id.
2. PUT /drive-api/v2/criteria/drafts/{criteria_id} - define (or redefine) the draft's logic, using the shapes above. Updating a draft re-runs it immediately and returns the resulting customer count, so you get instant feedback as you refine.
3. POST /drive-api/v2/criteria/drafts/{criteria_id}/run - re-check the count on demand, without changing the definition.
4. PUT /drive-api/v2/segments/{segment_id}/criteria/{criteria_id} - attach the finished draft to a segment (see Creating your first Segment).

If you already know the shape you want and don't need to save a draft first, POST /drive-api/v2/criteria/run accepts the same criteria definition directly and returns the count - useful for a quick "how big is this audience" check.

Reading a segment still uses a V1 endpoint. Segment metadata (name, status, tags) is read via GET /drive-api/v1/segments/{segment_id} - there's no V2 equivalent yet, so this one V1 endpoint stays in the loop even for segments built entirely on V2 criteria.