Segments

Define static, dynamic, and predictive audiences and use them across campaigns, widgets, and recommendations.

Audience: Lifecycle, CRM, and personalization teams managing audience targeting logic.

Critical: Static member management endpoints are available only for static segments; dynamic and predictive segments are computed from rules.

Campaigns Widgets Predictive Thresholds

Who This Page Is For

Use this page when you need to create and evaluate target audiences, estimate size impact, and maintain static segment member lists.

Quick Start (2-5 Minutes)

Create segment

Create static, dynamic, or predictive segment at site level.

POST /api/v1/segments

Reuse template

Bootstrap from predefined segment templates.

GET /api/v1/segments/templates
POST /api/v1/segments/templates/:templateId

Estimate audience size

Compute expected size before activation.

POST /api/v1/segments/:id/compute-size
POST /api/v1/segments/preview-size

Evaluate targeting logic

Run evaluation on one or multiple segments.

POST /api/v1/segments/:id/evaluate
POST /api/v1/public/segments/evaluate

Manage static members

Add/remove/list static segment members in bulk or individually.

GET /api/v1/segments/:id/members
POST /api/v1/segments/:id/members
POST /api/v1/segments/:id/members/bulk
DELETE /api/v1/segments/:id/members/:visitorId

Segment endpoints

POST   /api/v1/segments
GET    /api/v1/segments
GET    /api/v1/segments/templates
POST   /api/v1/segments/templates/:templateId
GET    /api/v1/segments/:id
PATCH  /api/v1/segments/:id
DELETE /api/v1/segments/:id
POST   /api/v1/segments/:id/evaluate
POST   /api/v1/segments/:id/compute-size
POST   /api/v1/segments/preview-size
POST   /api/v1/public/segments/evaluate
GET    /api/v1/segments/:id/members
POST   /api/v1/segments/:id/members
POST   /api/v1/segments/:id/members/bulk
DELETE /api/v1/segments/:id/members/:visitorId
POST   /api/v1/public/segments/evaluate

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`siteId`	Required	`uuid`	Create segment	Site-level ownership and access boundary.
`name`	Required	`string`	Create/update segment	Audience label used in targeting selectors.
`type`	Optional	`static \| dynamic \| predictive`	Create/update segment	Controls evaluation mode and member maintenance pattern.
`rules`	Optional	`object`	Dynamic/predictive segments	Rule definition for computed segment membership.
`visitorId`	Conditional	`string`	Static member add/remove	Required for individual static member operations.

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Need curated manual audience	type=static + member endpoints	Full manual control of segment membership.
Need behavior-driven audience	type=dynamic + rules + evaluate endpoints	Automatically computed from events/traits.
Need ML-style audience scoring	type=predictive + predictive thresholds setup	Ties to predictive score buckets for targeting.
Need impact estimate before launch	compute-size or preview-size endpoints	Avoids activating segments with near-zero reach.
Need storefront-side evaluation	POST /api/v1/public/segments/evaluate	Public runtime eligibility checks without admin auth.

Common Errors and Fixes

Cannot add member to segment

Cause: Segment type is dynamic/predictive, not static.

Fix: Use static segments for manual member operations.

Size estimate differs from expected

Cause: Rules include narrow conditions or stale assumptions about recent traffic.

Fix: Review rule logic and validate with evaluate endpoint output.

Permission denied on member listing

Cause: Role lacks segment member view permission.

Fix: Grant segment member permission to operator role.

Public evaluation returns no matches

Cause: Segment not active or runtime context missing required traits/events.

Fix: Check segment status and ensure runtime event/trait data completeness.

Production Checklist

Segment taxonomy (static/dynamic/predictive) is documented for stakeholders.Required
Every active segment has clear business owner and purpose.Required
Size estimation is performed before segment is used in live targeting.Required
Static member operations are restricted to static segment types only.Required
Public segment evaluation is validated for storefront use cases.Required