Segments

Segments are named groups of contacts that you target when creating campaigns or wiring up contact_added_to_segment automations. Membership is explicit: you add and remove the contacts yourself through the membership endpoints.

Audiences are a parallel kind of named contact group in the API; both are manual lists rather than rule-evaluated ones. The practical differences are that segments can be populated by email address as well as contact ID, and segments expose their size as contact_count (audiences use member_count).

---

Create segment

POST /v1/segments

Requires full_access scope.

Request body

Field	Type	Required	Description
name	string	Yes	Segment name (1-200 chars).
description	string	No	Segment description (max 1000 chars).

Response

{
  "id": "seg_abc123",
  "name": "High-Value Users",
  "description": "Contacts who spent over $500",
  "contact_count": 0,
  "created_at": "2026-05-30T14:00:00Z",
  "updated_at": "2026-05-30T14:00:00Z"
}

---

List segments

GET /v1/segments

Requires read_only scope. Cursor-paginated by created_at, newest first.

Query parameters

Parameter	Type	Default	Description
limit	number	50	Results per page (1-100).
cursor	string		next_cursor from a previous response.

Response

{
  "data": [
    {
      "id": "seg_abc123",
      "name": "High-Value Users",
      "description": "Contacts who spent over $500",
      "contact_count": 128,
      "created_at": "2026-05-30T14:00:00Z",
      "updated_at": "2026-05-30T14:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

---

Get segment

GET /v1/segments/:id

Requires read_only scope. Returns 404 with code not_found if the segment does not belong to your organization.

Response

{
  "id": "seg_abc123",
  "name": "High-Value Users",
  "description": "Contacts who spent over $500",
  "contact_count": 128,
  "created_at": "2026-05-30T14:00:00Z",
  "updated_at": "2026-05-30T14:00:00Z"
}

---

Update segment

PATCH /v1/segments/:id

Requires full_access scope. Omitted fields are left unchanged.

Request body

Field	Type	Required	Description
name	string	No	Updated segment name (1-200 chars).
description	string | null	No	Updated description (max 1000 chars).

Response

{
  "id": "seg_abc123",
  "name": "VIP Customers",
  "description": null,
  "contact_count": 128,
  "created_at": "2026-05-30T14:00:00Z",
  "updated_at": "2026-06-01T09:30:00Z"
}

---

Delete segment

DELETE /v1/segments/:id

Requires full_access scope. Deletes the segment and all of its memberships; the contacts themselves are not deleted.

Response

{
  "deleted": true
}

---

Add contacts to segment

POST /v1/segments/:id/contacts

Requires sending_access scope. Provide contact_ids, emails, or both. Each array accepts up to 100 entries, and at least one must be non-empty or the request fails with 422 missing_contacts.

Request body

Field	Type	Required	Description
contact_ids	string[]	No	Contact IDs to add (max 100).
emails	string[]	No	Contact emails to add (max 100).

Example request

{
  "contact_ids": ["ct_abc123"],
  "emails": ["stanley@example.com"]
}

Response

{
  "added": 2
}

Returns 404 with code contacts_not_found when none of the supplied IDs or emails match a contact in your organization.

---

List contacts in segment

GET /v1/segments/:id/contacts

Requires read_only scope. Cursor-paginated by membership creation time, newest first.

Query parameters

Parameter	Type	Default	Description
limit	number	50	Results per page (1-100).
cursor	string		next_cursor from a previous response.

Response

{
  "data": [
    {
      "id": "ct_abc123",
      "email": "stanley@example.com",
      "first_name": "Stanley",
      "last_name": "Hudson",
      "metadata": { "plan": "pro" },
      "unsubscribed": false,
      "properties": {},
      "created_at": "2026-04-11T08:15:00Z",
      "updated_at": "2026-05-02T12:00:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "2026-04-11T08:15:00Z"
}

---

Remove contact from segment

DELETE /v1/segments/:id/contacts/:contactId

Requires sending_access scope. Removes a single contact from the segment. Returns 404 with code not_found if the contact is not a member.

Response

{
  "deleted": true
}