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

GET /lists

{
  "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 with list_id.

Create a List

POST /lists

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

PATCH /lists/{id}

{ "name": "Recall due, October" }

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

Delete a List

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.

{
  "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, then send their IDs here.

POST /lists/{id}/contacts

{ "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:

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

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.

Contacts to search everyone on a list
Custom Fields for the details you keep on each contact

Endpoints

Agents

MCP server

Agent pairing

Webhooks

List

Lists

List Your Lists

Create a List

Rename a List

Delete a List

Add Many Contacts to a List

Add or remove one contact

​Lists

​List Your Lists

​Create a List

​Rename a List

​Delete a List

​Add Many Contacts to a List

​Add or remove one contact

​Related

Lists

List Your Lists

Create a List

Rename a List

Delete a List

Add Many Contacts to a List

Add or remove one contact

Related