Deleted people are never matched. A person whose
status is REMOVED is a
soft-deleted record, and no segment returns them, so a deleted customer or a
removed team member cannot end up in an audience you message. People whose
status is INACTIVE are matched — filter on status explicitly if you
want only active people.Discover what you can filter on
You cannot guess your own attribute names, so start by reading the catalog instead of writing a filter blind:attr token to use and the operators valid for it:
personAttributes: typed columns on the person (email,status,createdAt,identityOrigin) plus every customattributes.<key>your org has ingested.identityOriginisSYNCEDfor people you sent us andMINTEDfor people Boom created for contacts who messaged you first, soidentityOrigineqMINTEDwithcreatedAtin_last_n7 days is “new contacts this week”. People Boom created only match a segment saved withincludeBoomCreated: true(off by default), and Boom does not check marketing consent for them before a WhatsApp or SMS send: add a consent condition before using such a segment for marketing. Marketing email skips people who opted out once Boom turns on its consent check for your organization (early access; see journeys).computedVariables: virtualcomputed.<key>values (an aggregate or expression over related data) resolved at filter time, with no stored value of their own.customObjectTypes: each type’s own filterable attributes, addressed asobject.attributes.<key>once you reach that type through a relationship.reachableObjects: the custom-object types reachable from a person, and every relationship path that gets you there, direct or through one or two intermediate objects.events: every event your organization has recorded, with the payload keys seen on it. These driveeventpredicates — “did this person do X”, optionally narrowed by the payload and by when it happened. Each key carries the token to use inpropertyFiltersand the operators valid for its type. An event with no payload keys recorded yet listsproperties: [].eventWindowOperators: what aneventpredicate’swindowaccepts. Past-oriented only — a future window over history means nothing.operatorReference: every operator’s expectedvalueshape (scalar,list,date,dateRange,relativeWindow,dateOffset,none), so you don’t have to guess whether an operator wants a string, a list, or a window.
Build a filter
A segment’s filter is aFilterExpression: a tree of predicates joined by
AND/OR. Each predicate is one of a few kinds:
A segment for premium customers who have gone quiet on payments. Note the
event predicate: events reach Boom through the API, not through the
database sync, which syncs people, custom objects and
relationships only. If your payment history arrives by database sync, filter on
a custom object’s date attribute with has_relationship instead.
Each predicate after the first can carry a
connector (AND or OR) that
joins it to the previous predicate; AND binds tighter than OR. The
conditions inside one predicate (filters, attributeFilters,
propertyFilters) are always joined with AND, whatever its connector. For
“either condition”, put each one in its own predicate and set
"connector": "OR" on the second:
contains and not_contains accept a single substring or a list. A list
means “any of these”: contains matches a row with any needle,
not_contains keeps a row with none of them. To exclude several values,
pass one not_contains with all of them, not a comma-joined string.Author a segment end to end
The catalog, validate, preview, create, evaluate, and members endpoints form one loop. An agent (or a script) can walk it without ever opening the dashboard.1
Read the catalog
GET /api/v1/segments/catalog (segments_catalog). See what’s
filterable before writing anything.2
Validate the filter
POST /api/v1/segments/validate (segments_validate) with a
filterExpression. This is a dry-run compile against your live catalog.
Nothing is saved; a bad attribute or operator fails here with the exact
field to fix.3
Preview the match count
POST /api/v1/segments/preview (segments_preview) runs the same
filter and returns { "count": N }, the number of people it currently
matches. No segment is created. Pass includeBoomCreated: true to count
people Boom created the way a segment with that setting would.4
Create the segment
POST /api/v1/segments (segments_create) with name, slug, and the
filterExpression. Creating a segment compiles and stores the filter,
it does not evaluate it: the response comes back with memberCount: 0
regardless of how many people actually match. includeBoomCreated
decides whether people Boom created can match. It defaults to false,
or to true when the filter asks for them (identityOrigin MINTED);
an explicit false is kept and the response includes a warning.
A PATCH that first adds such a filter turns it on the same way, except
on a segment that feeds a published journey or a scheduled campaign:
there it stays false, and a warning says how many people Boom created
would enter. Send includeBoomCreated: true to include them.
Turning it on later (PATCH) widens the segment like any filter change:
on the next evaluation every matching person Boom created enters,
journeys triggered by the segment start for them, and scheduled campaigns
that send to it include them. The response to that
update includes newlyMatchingBoomCreated, the number who now match.5
Evaluate it
POST /api/v1/segments/{slug}/evaluate (segments_evaluate) runs the
filter now and writes the membership rows, returning
{ "entrants", "leavers", "total" }. Nothing is a member until an
evaluation runs at least once.6
Read the members
GET /api/v1/segments/{slug}/members (segments_members_list) lists
the active members, newest first: name, phoneNumber, externalId,
email, enteredAt. Keyset-paginated with next_cursor, same pattern
as every other list endpoint.PATCH /api/v1/segments/{slug} (segments_update) updates any field except
the slug, which is permanent. Changing filterExpression recompiles the
filter but does not re-evaluate it, so the member set stays exactly as it
was until the next evaluate call.
Keeping a segment fresh
A segment’s membership is a set of rows, not a live query, so it only changes when an evaluation runs. How often that happens isevaluationCadence:
REACTIVE_ONLY(the default). The segment re-evaluates the specific people a CDP write touches, usually within seconds of that write, plus a daily backstop sweep to catch anything a reactive update missed. Nothing else triggers it, so an explicitsegments_evaluatecall is how you force a full refresh.HOURLYorDAILY. A scheduled sweep evaluates the whole segment on that cadence, independent of any particular write. Useful for filters that depend on the passage of time itself, like “hasn’t paid in 30 days,” which can flip with no new data at all.
How a segment reaches outreach
A segment does not attach to an initiative directly. It becomes the trigger on the journey behind that initiative: the journey’s entry node is configured withtriggerType: segment and a segmentId. Once that journey is
published, every evaluation that adds someone to the segment enrolls them,
carrying along whatever data the segment projects for that person.
Wiring that trigger is an app job today. It needs the segment’s internal id,
and this API identifies segments by
slug, so set a segment trigger in the
Boom app rather than over the API.Limits and gotchas
- Create and update never evaluate.
memberCountis0right aftersegments_create, and a filter change fromsegments_updateleaves the existing member set untouched until you callsegments_evaluate. - Weekend freeze. A segment with
skipWeekendEvaluationset rejects an explicit evaluate on Saturday or Sunday (in your organization’s timezone) with400 weekend_evaluation_skipped. - Deleting over MCP requires a role that can delete segments (Owner,
Admin or Member).
segments_deleteis a soft delete: it disappears from every list immediately, and its journey triggers are removed so no journey keeps enrolling from it. It is idempotent,{ "removed": false }on a segment that is already gone. - Pagination.
segments_listandsegments_members_listare keyset-paginated, defaulting to 100 rows and capped at 1000; loop onnext_cursoruntil it comes backnull. - Preview returns a count only. It does not return a sample of matching people over the API or MCP, only the total.
- Slugs are permanent. Pick one deliberately;
segments_updatecannot rename it. - Every date, number and true/false comparison needs a value. An empty
value("", a list holding"", or abetweenwith an emptyfromorto) on a DATE, NUMBER or BOOLEAN comparison is rejected with422 INVALID_VALUEby validate, preview, create and update. Text comparisons are not checked this way. - Specific-date operators take a day, not a timestamp.
on,before,afterandbetweencompare calendar days in your organization’s timezone. Send"YYYY-MM-DD"; a value with a time of day ("2026-11-13T01:00:00Z") is rejected with422 INVALID_VALUEby validate, preview, create and update, because the time would be dropped.beforeandafterexclude the day itself;betweenincludes both ends. Segments saved earlier with a timestamp keep evaluating as they did (on the date part of the value), and an update may re-send that same value; any new timestamp is rejected. - Conditions that can never hold together are rejected. Inside one
predicate, or across person predicates joined with
AND,is_nullon an attribute together with another condition on the same attribute (other thanneq,not_inornot_contains) matches no one. Validate, preview, create and update return422 CONTRADICTORY_CONDITIONS, with the attribute infield. It usually means the conditions were meant as alternatives; see theconnectorexample above. - Hidden fields can’t be filtered over MCP. If your organization marked a
field sensitive, an AI tool connected over MCP gets
400 sensitive_fieldfromsegments_validate,segments_preview,segments_create,segments_updateandsegments_evaluatewhen the filter uses that field: a count over a hidden value would let it guess the value. Build those segments in the dashboard’s segment builder; the REST API is not affected.
Related
Customer Data Platform
The people, objects, and events a segment’s filter reads.
Events
How the events an
event predicate matches against get recorded.Journeys
Set a segment as a journey’s trigger to turn membership into outreach.
Use MCP
Author segments conversationally with the same tools documented here.