# 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](/docs/api/overview)).

## The list object

```json
{
  "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

```text
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

```text
POST /api/v1/lists
```

```json
{ "name": "Newsletter" }
```

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

## Get, rename and delete a list

```text
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

```text
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](/docs/api/contacts).

## Add contacts to a list

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

Send one contact or several:

```json
{ "contactId": "clx..." }
```

```json
{ "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.

```json
{ "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

```text
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.