Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spotzee.com/llms.txt

Use this file to discover all available pages before exploring further.

Most segments are best authored in the Spotzee UI — operators iterate quickly, preview membership, and version their work. Use the API when the rules themselves are derived from your code or config: a generated cohort per pricing plan, a per-region segment driven by a feature-flag rollout, or a backfill that needs to recreate dozens of segments at once.
Today the API exposes segments as dynamic lists. There is no separate /segments endpoint — a segment is a list with type: "dynamic" and a rule tree. Static lists (explicit member add/remove) use the same endpoints with type: "static".

​
What you’ll build

A script that creates a dynamic list with a rule tree, then walks its members.

​
Prerequisites

You’ll need a sk_ project key with write access. See Authentication.

​
Walkthrough

1

Decide what membership means

A segment is a boolean rule that yields true or false for any contact. Common shapes:
  • Attribute filter — data.plan = "professional"
  • Behavioural filter — contacts who triggered order_placed in the last 30 days
  • Combined — plan = "professional" AND triggered order_placed in the last 30 days
Sketch the rule as plain language first; the JSON shape follows from there.
2

Build the rule tree

Spotzee rules are nested groups. The top level is a group with an operator (and / or) and a list of children. Each child is either another group or a leaf comparing a field to a value.
{
  "type": "group",
  "operator": "and",
  "children": [
    {
      "type": "user",
      "path": "data.plan",
      "operator": "=",
      "value": "professional"
    },
    {
      "type": "event",
      "name": "order_placed",
      "operator": "count",
      "frequency": { "period": "days", "amount": 30, "value": 1 }
    }
  ]
}
Leaf shapes:
typeWhat it does
userCompares a field on the contact (email, external_id, data.<key>) to a value
eventFilters by an event name with optional frequency window
3

Create the list

POST /lists with type: "dynamic":
POST /lists HTTP/1.1
Host: apix.spotzee.com
Authorization: Bearer sk_…
Idempotency-Key: segment-pro-monthly
Spotzee-Version: 2026-04-28
Content-Type: application/json

{
  "name": "Pro plan, active in last 30 days",
  "type": "dynamic",
  "rule": { /* the tree from step 2 */ }
}
The response includes the list id. Save it — that’s how you’ll reference the segment from journeys, campaigns, and member-listing endpoints.
4

Walk the members

Members are computed asynchronously — give Spotzee a moment after creation, then page the list:
GET /lists/{listId}/users?limit=100&cursor=…
See Pagination for the cursor pattern.
5

Update the rule

PATCH /lists/{listId} with a new rule block. Spotzee re-computes membership in the background. Existing members are reconciled — those who still match stay, those who don’t drop out.

​
Pitfalls to avoid

Don’t build a hot loop that recreates the same segment every minute. Recomputation is cheap but not free. Update the rule in place with PATCH rather than deleting and recreating.
  • Don’t filter on fields you haven’t populated yet. A rule on data.plan returns zero members until at least one contact has that field. Sync your contacts first (Sync contacts), then build segments.
  • Don’t bury the rule in too many layers. Spotzee accepts deeply nested groups, but a rule that spans more than two and/or layers is hard for operators to read in the UI.

​
Reference