> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brilo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List

# Lists

A list is a named group of contacts, such as "Recall due" or "New patients October". Lists are
how you pick who a campaign calls and how you narrow the contacts page. A contact can be on any
number of lists.

Errors share one shape, `{ "status", "error_code", "message", "details" }`. Branch on `error_code`.

## List Your Lists

```http theme={null}
GET /lists
```

```json theme={null}
{
  "status": 200,
  "data": [
    {
      "id": "3f2b8c1e-5d4a-4b6f-9e2a-7c1d0b8a9f33",
      "name": "Recall due",
      "contact_count": 128,
      "created_at": "2026-10-01T10:00:00.000Z",
      "updated_at": "2026-10-01T10:00:00.000Z"
    }
  ]
}
```

Lists come A to Z. To read the contacts on one, use `GET /contact?list_id={id}` or
[Search Contacts](https://docs.brilo.ai/api-reference/endpoint/contact.md#search-contacts) with `list_id`.

## Create a List

```http theme={null}
POST /lists
```

```json theme={null}
{ "name": "Recall due" }
```

Returns `201` with the new, empty list. Two lists in a workspace cannot share a name, in any case:
a name that is taken returns `409` `name_taken` with the other list's id in
`details.existing_id`.

## Rename a List

```http theme={null}
PATCH /lists/{id}
```

```json theme={null}
{ "name": "Recall due, October" }
```

Same name rule as creating. A list from another workspace returns `404` `list_not_found`.

## Delete a List

```http theme={null}
DELETE /lists/{id}
```

Deletes the list and takes everyone off it. **Contacts are never deleted**; each one's history
shows it was removed from the list.

```json theme={null}
{
  "status": 200,
  "data": { "id": "3f2b8c1e-5d4a-4b6f-9e2a-7c1d0b8a9f33", "deleted": true, "removed_from_contacts": 128 }
}
```

## Add Many Contacts to a List

Use this for "put everyone over 50 with Delta Dental on Recall due": find them with
[Search Contacts](https://docs.brilo.ai/api-reference/endpoint/contact.md#search-contacts), then send their IDs here.

```http theme={null}
POST /lists/{id}/contacts
```

```json theme={null}
{ "contact_ids": ["8d2f1c9a-3b4e-4f6a-9c7d-2e1b0a9f8c7d", "1a7e5b20-9c3d-4e8f-b6a1-5d4c3b2a1f0e"] }
```

Up to 500 IDs per call; for more, send them in batches. Every contact gets its own result, in the
order you sent them, so one bad ID never blocks the rest:

```json theme={null}
{
  "status": 200,
  "data": {
    "list_id": "3f2b8c1e-5d4a-4b6f-9e2a-7c1d0b8a9f33",
    "added": 1,
    "already_on_list": 0,
    "failed": 1,
    "results": [
      { "contact_id": "8d2f1c9a-3b4e-4f6a-9c7d-2e1b0a9f8c7d", "status": "added" },
      {
        "contact_id": "1a7e5b20-9c3d-4e8f-b6a1-5d4c3b2a1f0e",
        "status": "error",
        "error_code": "contact_not_found",
        "message": "Contact not found in your workspace."
      }
    ]
  }
}
```

Safe to retry: a contact already on the list comes back as `already_on_list` and nothing changes.
An empty list, a non-string ID or more than 500 IDs returns `400` `validation_failed` with
`details.field` `contact_ids`. Each added contact's history shows it was added.

## Add or remove one contact

```http theme={null}
POST /contact/{id}/lists/{listId}
DELETE /contact/{id}/lists/{listId}
```

Adding a contact that is already on the list changes nothing. Both appear in the contact's history.

## Related

* [Contacts](https://docs.brilo.ai/api-reference/endpoint/contact.md) to search everyone on a list
* [Custom Fields](https://docs.brilo.ai/api-reference/endpoint/custom-field.md) for the details you keep on each contact


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.