Segments

Segments are dynamic groups of contacts that match a set of rules. Unlike static lists, segments update automatically as contacts change. Use segments to target the right audience for broadcasts without manually managing lists.

Create a segment

POST /audience/segments

Request body

{
  "name": "Luanda — Active Customers",
  "description": "Contacts in Luanda who placed an order in the last 30 days",
  "rulesOperator": "AND",
  "rules": "[{\"field\":\"city\",\"operator\":\"equals\",\"value\":\"Luanda\"},{\"field\":\"lastOrderDays\",\"operator\":\"lessThan\",\"value\":\"30\"}]"
}

Field	Type	Required	Description
`name`	`string`	Yes	Human-readable name
`description`	`string`	No	Optional description
`rulesOperator`	`string`	No	`AND` (all rules must match) or `OR` (any rule matches). Default: `AND`
`rules`	`string`	No	JSON array of rule objects (see below). Default: `[]` (matches all contacts)

Rule object structure

{
  "field": "city",
  "operator": "equals",
  "value": "Luanda"
}

Operator	Meaning
`equals`	Exact match
`notEquals`	Does not match
`contains`	Field contains the value
`startsWith`	Field starts with the value
`greaterThan`	Numeric field is greater than value
`lessThan`	Numeric field is less than value

Response `201`

Returns the new segment ID (UUID).

Code sample

curl -X POST https://api.castbrick.co/v1/audience/segments \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Luanda customers",
    "rulesOperator": "AND",
    "rules": "[{\"field\":\"city\",\"operator\":\"equals\",\"value\":\"Luanda\"}]"
  }'

List segments

GET /audience/segments

Query parameters

Parameter	Default	Description
`pageNumber`	`1`	Page number
`pageSize`	`50`	Results per page (max 100)
`search`	—	Filter by name

Response `200`

{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Luanda — Active Customers",
      "description": "Contacts in Luanda who ordered recently",
      "rulesOperator": "AND",
      "contactCount": 1482,
      "createdAt": "2026-02-01T10:00:00Z"
    }
  ],
  "totalCount": 6,
  "pageNumber": 1,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPreviousPage": false
}

Code sample

curl "https://api.castbrick.co/v1/audience/segments?pageNumber=1&pageSize=20" \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx"

Update a segment

PUT /audience/segments/{id}

Replaces the segment's name, description and rules. Same fields as the create request.

curl -X PUT https://api.castbrick.co/v1/audience/segments/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Luanda — VIP Customers",
    "rulesOperator": "AND",
    "rules": "[{\"field\":\"city\",\"operator\":\"equals\",\"value\":\"Luanda\"},{\"field\":\"tier\",\"operator\":\"equals\",\"value\":\"vip\"}]"
  }'

Delete a segment

DELETE /audience/segments/{id}

Permanently removes the segment. Returns 204 No Content.

curl -X DELETE https://api.castbrick.co/v1/audience/segments/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx"

Using segments with broadcasts

Segments integrate with the dashboard broadcast builder. When creating a broadcast, select a segment instead of a contact list to automatically target all matching contacts at send time.

Segment membership is evaluated at send time, not when the broadcast is created. A segment with 1,000 contacts today may have 1,050 at scheduled send time — credits are deducted based on the actual count when dispatching.

Segment vs. Contact List

	Contact List	Segment
Membership	Static (manually managed)	Dynamic (rule-based)
Updates	When you add/remove contacts	Automatically
Best for	Fixed groups (e.g. newsletter subscribers)	Filtered targeting (e.g. users in a city)
Supports broadcasts	✅	✅ (via dashboard)

Segments

On this page