Skip to main content
POST
Create a segment

Authorizations

Authorization
string
header
required

Organization API key, sent as Authorization: Bearer boom_org_....

Body

application/json
name
string
required

Display name.

Required string length: 1 - 120
slug
string
required

Permanent identifier, lowercase-kebab-case, unique in your organization. Cannot be changed after creation.

Required string length: 1 - 64
Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
filterExpression
object
required

The audience filter: a tree of predicates over person attributes, related data, and events. Discover valid attr tokens and operators with segments_catalog (GET /api/v1/segments/catalog).

description
string | null
Maximum string length: 1024
evaluationCadence
enum<string>
default:REACTIVE_ONLY

How often the segment re-evaluates. Defaults to REACTIVE_ONLY — evaluate on demand with segments_evaluate.

Available options:
REACTIVE_ONLY,
HOURLY,
DAILY
dailyEvaluationHour
integer | null

For DAILY cadence: the hour (0-23, in your organization timezone) the segment evaluates.

Required range: 0 <= x <= 23
skipWeekendEvaluation
boolean

When true, the segment is not evaluated on weekends.

outputColumns
object

Optional extra columns to project for each member when the segment feeds downstream automations.

includeBoomCreated
boolean

When true, people Boom created for contacts who messaged you first (externalId boom:…) can match this segment. Defaults to false, or to true when the filter asks for them (identityOrigin MINTED). Boom enforces no marketing opt-in for them, so filter on consent yourself before marketing to them.

Response

Success

id
string
required

Stable internal identifier. Pass this wherever a segment reference is stored — e.g. a journey trigger's segmentId.

slug
string
required

Unique identifier within your organization.

name
string
required
description
string | null
required
evaluationCadence
enum<string>
required

How often the segment is re-evaluated. REACTIVE_ONLY segments only change when evaluated explicitly.

Available options:
REACTIVE_ONLY,
HOURLY,
DAILY
memberCount
integer
required

Live count of currently active members.

Required range: -9007199254740991 <= x <= 9007199254740991
includeBoomCreated
boolean
required

Whether people Boom created for contacts who messaged you first can match. False by default.

lastEvaluatedAt
string | null
required

ISO 8601 timestamp; null if the segment has never evaluated.

createdAt
string
required

ISO 8601 timestamp.

warnings
string[]

Advice about the saved segment; the write succeeded.

newlyMatchingBoomCreated
integer

Set when this update turned includeBoomCreated on: the people created by Boom who now match. They enter on the next evaluation; every journey this segment triggers starts for them, and every scheduled campaign that sends to it includes them.

Required range: -9007199254740991 <= x <= 9007199254740991