Skip to main content
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 verifies membership in the Spotzee app.

​
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 a tree of nodes. The root is a wrapper node that combines its children with and / or; leaves are typed comparisons against a contact field (group: "user") or event payload (group: "event").Every node carries:Example: contacts on the Professional plan who triggered order_placed at least once in the last 30 days.
Refer to the RuleNode, RuleType, RuleGroup, and RuleFrequency schemas in the API reference for the exact enum values.
3

Create the list

POST /lists with type: "dynamic":
The response includes the list id. Save it. That’s how you’ll reference the segment from journeys, campaigns, and member-listing endpoints.
4

Verify membership

A new dynamic list starts as a draft. Inspect its matching contacts in the Spotzee app, then publish the intended rule before using the segment. A contact search does not evaluate the list’s complete rule tree and is not a substitute for checking membership.
5

Update the rule

PATCH /lists/{listId} with a new rule block. The updated rule determines which contacts match when the segment is evaluated. For a draft list, include published: true when you are ready to publish it.

​
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