Skip to main content
A segment is a named audience: a filter over your people, the custom objects related to them, and the events they generated, saved once and reused. Instead of re-describing “premium customers who haven’t paid in 30 days” every time you launch an initiative, you define it as a segment and point a journey’s trigger at it. Segments are how you decide who a conversation reaches. A win-back journey, an NPS follow-up, an onboarding nudge: each one starts from a segment, not from a hand-picked list of people.
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:
The response lists everything filterable in your organization, each with the exact attr token to use and the operators valid for it:
  • personAttributes: typed columns on the person (email, status, createdAt, identityOrigin) plus every custom attributes.<key> your org has ingested. identityOrigin is SYNCED for people you sent us and MINTED for people Boom created for contacts who messaged you first, so identityOrigin eq MINTED with createdAt in_last_n 7 days is “new contacts this week”. People Boom created only match a segment saved with includeBoomCreated: 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: virtual computed.<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 as object.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 drive event predicates — “did this person do X”, optionally narrowed by the payload and by when it happened. Each key carries the token to use in propertyFilters and the operators valid for its type. An event with no payload keys recorded yet lists properties: [].
  • eventWindowOperators: what an event predicate’s window accepts. Past-oriented only — a future window over history means nothing.
  • operatorReference: every operator’s expected value shape (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.
The catalog is generated from the same registry the compiler enforces at save time, so it never lists an attribute or operator combination that would actually be rejected.

Build a filter

A segment’s filter is a FilterExpression: 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.
Operators worth knowing: 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 is evaluationCadence:
  • 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 explicit segments_evaluate call is how you force a full refresh.
  • HOURLY or DAILY. 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.
Whichever cadence you choose, a freshly created or just-edited segment shows a stale or empty member set until the next evaluation actually runs.
Set the cadence explicitly when you create a segment over the API. The default for API-created segments is REACTIVE_ONLY, and this page’s own example is the case it handles worst: “no payment in 30 days” turns true from the passage of time, not from a write, so nothing reactive fires when a customer crosses the line. Ask for HOURLY or DAILY on any filter whose answer changes with the calendar, or evaluate on your own schedule.

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 with triggerType: 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

segments_evaluate runs synchronously over the API and MCP, unlike the dashboard’s “Evaluate now” button, which queues the evaluation in the background and returns immediately. On a large organization, a synchronous evaluate call can take a while and holds the request open the whole time. If you just need the segment defined and don’t need its membership refreshed right away, skip the evaluate call and let its cadence run it.
  • Create and update never evaluate. memberCount is 0 right after segments_create, and a filter change from segments_update leaves the existing member set untouched until you call segments_evaluate.
  • Weekend freeze. A segment with skipWeekendEvaluation set rejects an explicit evaluate on Saturday or Sunday (in your organization’s timezone) with 400 weekend_evaluation_skipped.
  • Deleting over MCP requires a role that can delete segments (Owner, Admin or Member). segments_delete is 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_list and segments_members_list are keyset-paginated, defaulting to 100 rows and capped at 1000; loop on next_cursor until it comes back null.
  • 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_update cannot rename it.
  • Every date, number and true/false comparison needs a value. An empty value ("", a list holding "", or a between with an empty from or to) on a DATE, NUMBER or BOOLEAN comparison is rejected with 422 INVALID_VALUE by validate, preview, create and update. Text comparisons are not checked this way.
  • Specific-date operators take a day, not a timestamp. on, before, after and between compare 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 with 422 INVALID_VALUE by validate, preview, create and update, because the time would be dropped. before and after exclude the day itself; between includes 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_null on an attribute together with another condition on the same attribute (other than neq, not_in or not_contains) matches no one. Validate, preview, create and update return 422 CONTRADICTORY_CONDITIONS, with the attribute in field. It usually means the conditions were meant as alternatives; see the connector example 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_field from segments_validate, segments_preview, segments_create, segments_update and segments_evaluate when 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.

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.