Segments

Method	Path	Scope	SDK
GET	/api/v1/segments	any valid key	segments.list
POST	/api/v1/segments	contacts:write	segments.create
GET	/api/v1/segments/:id	any valid key	segments.get
PATCH	/api/v1/segments/:id	contacts:write	segments.update
DELETE	/api/v1/segments/:id	contacts:write	segments.delete

note

Segment writes use contacts:write — there is no segment-specific scope.

The filter

{ "status": "subscribed", "tags": ["beta", "vip"], "source": "signup-form" }

Field	Type	Matches
status	string | string[]	Contact status, one or several.
tags	string[]	Contacts carrying all listed tags.
source	string	Exact source value.

An empty filter ({}) matches every contact. Filters are evaluated when a campaign runs, so a segment always reflects current membership.

GET /api/v1/segments

{
  "ok": true,
  "segments": [
    {
      "id": "6b1e…",
      "label": "Engaged beta users",
      "brand_id": null,
      "filter": { "status": "subscribed", "tags": ["beta"] },
      "count": 412,
      "created_at": "2026-07-10T12:00:00.000Z",
      "updated_at": "2026-07-24T08:30:00.000Z"
    }
  ]
}

count is computed per request — a large list makes this call more expensive than a plain read.

POST /api/v1/segments

Field	Type	Notes
label	string	Required. Unique per project.
filter	object	Defaults to {} (everyone).
brand	string	Scope the segment to one brand.

201

{ "ok": true, "segment": { "id": "6b1e…", "label": "Engaged beta users", … } }

422 — invalid payload, or the label already exists in this project.

GET /api/v1/segments/:id

Returns { ok: true, segment } including a freshly computed count. 404 not_found if it is not in this project.

PATCH /api/v1/segments/:id

Body: { "label"?: "…", "filter"?: { … } }. A supplied filter replaces the old one — there is no per-key merge.

{ "ok": true, "segment": { "id": "6b1e…", … } }

DELETE /api/v1/segments/:id

{ "ok": true, "id": "6b1e…", "deleted": true }

Contacts are untouched. Campaigns that already resolved this segment keep running; scheduled ones pointing at it will fail to resolve an audience, so cancel or repoint them first.