Lists API

A list is a named group of contacts that a campaign can be sent to. All routes need a bearer API key (see API Overview).

The list object

{
  "id": "clx...",
  "orgId": "clx...",
  "name": "Newsletter",
  "createdAt": "2026-10-04T12:00:00.000Z",
  "contactCount": 128
}

contactCount is the number of contacts on the list, whatever their status.

List your lists

GET /api/v1/lists

Query	Meaning
limit	Page size, default 20, maximum 100
after	Cursor from the previous page
q	Case-insensitive search in the list name

Create a list

POST /api/v1/lists

{ "name": "Newsletter" }

name is required. Returns 201 with id, name, createdAt and contactCount: 0.

Get, rename and delete a list

GET    /api/v1/lists/:id
PATCH  /api/v1/lists/:id
DELETE /api/v1/lists/:id

PATCH takes { "name": "New name" } and requires a non-empty name. DELETE returns 204 and removes the list. It does not delete the contacts on it. Any of these returns 404 if the list is not in your workspace.

List the contacts on a list

GET /api/v1/lists/:id/contacts

Query	Meaning
limit	Page size, default 20, maximum 100
after	Cursor from the previous page
status	One of PENDING, SUBSCRIBED, UNSUBSCRIBED, BOUNCED
q	Case-insensitive search in email, first name and last name

Items have the same shape as in the Contacts API.

Add contacts to a list

POST /api/v1/lists/:id/contacts

Send one contact or several:

{ "contactId": "clx..." }

{ "contactIds": ["clx...", "clx..."] }

• Every id must be a contact in your workspace. If any id is unknown the whole request returns 404 and lists the missing ids.
• Contacts already on the list are ignored.
• Contacts whose status is UNSUBSCRIBED or BOUNCED are never added. They are counted as skipped instead of causing an error.

{ "data": { "added": 2, "skipped": 1 } }

added counts contacts that were eligible, including any that were already on the list.

Remove a contact from a list

DELETE /api/v1/lists/:id/contacts/:contactId

Returns 204. The contact itself is not deleted. 404 if the list or the contact is not in your workspace.