Segments

A segment is a saved question about your contacts — “on the pro plan and based in Lagos” — answered fresh every time you ask it.

The rule is written in the same language an automation condition uses. That is deliberate: “plan is pro and seats over ten” is one question, and it should mean the same thing whether it is deciding a branch mid-sequence or deciding an audience. Two rule languages would be two sets of edge cases, and they diverge the first time somebody fixes a bug in only one of them.

Creating one

curl -X POST https://api.quolle.com/v1/segments \\
  -H "Authorization: Bearer qle_your_api_key" \\
  -H "Content-Type: application/json" \\
  -d '{
    "name": "Pro plan, Lagos",
    "rule": {
      "type": "and",
      "rules": [
        { "field": "contact.metadata.plan", "operator": "eq", "value": "pro" },
        { "field": "contact.metadata.city", "operator": "eq", "value": "Lagos" }
      ]
    }
  }'Copy

{
  "id": "7aa6bb3e-d6be-488d-88a4-c86393868542",
  "customerId": "8fd34fb3-5f07-456a-b6ee-0c5b71228f44",
  "name": "Pro plan, Lagos",
  "rule": { "type": "and", "rules": [ ... ] },
  "createdAt": "2026-08-23T11:34:34.172Z",
  "updatedAt": "2026-08-23T11:34:34.172Z",
  "contacts": 42
}Copy

contacts is the size right now, computed as part of the response. “How many people is this?” is the only question anybody has about a segment, and a name without it is a guess.

Trying a rule before you save it

Writing a rule blind, naming it, pointing a campaign at it and only then discovering it matches nobody is the failure this prevents. /preview creates nothing.

curl -X POST https://api.quolle.com/v1/segments/preview \\
  -H "Authorization: Bearer qle_your_api_key" \\
  -H "Content-Type: application/json" \\
  -d '{ "rule": { "field": "contact.metadata.plan", "operator": "eq", "value": "pro" } }'Copy

{
  "total": 42,
  "sample": [
    "ada@example.com",
    "chidi@example.com"
  ]
}Copy

sample is the first five addresses — enough to recognise whether the rule caught the people you meant.

What a segment rule can read

Operators

eq, neq, gt, gte, lt, lte, contains, starts_with, ends_with, exists, is_empty, is_true, is_false. Rules combine with and and or, nesting up to five deep — the same as a condition step.

contact.unsubscribed is refused too, for a quieter reason: a segment never contains unsubscribed contacts in the first place, so testing it would always give the same answer. The filter is already applied.

Who is in it

curl https://api.quolle.com/v1/segments/<id>/contacts?limit=100 \\
  -H "Authorization: Bearer qle_your_api_key"Copy

{
  "total": 42,
  "contacts": [
    {
      "id": "7516c1e4-3182-4b95-ab5c-23e9c072a3b4",
      "email": "ada@example.com",
      "firstName": "Ada",
      "lastName": null
    }
  ]
}Copy

total is the whole segment; contacts is capped by limit, which defaults to 100 and maxes at 500. The honest answer for a broad rule is “most of your contacts”, and returning fifty thousand rows to prove it helps nobody.

Segments and automations

There is no add_to_segment step, because there is nothing to add anybody to. Membership is worked out from the contact’s own fields every time it is asked, so the way to put somebody in a segment is to make the rule true of them:

{
  "key": "mark_engaged",
  "type": "contact_update",
  "config": { "metadata": { "engaged": "yes" } }
}Copy

A segment testing contact.metadata.engaged now includes them. Sending add_to_segment returns a 422 saying this, rather than succeeding and doing nothing.

Endpoints

Errors