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

# Contact Lists API: Stage Prospects and Auto-Enroll

> Create contact lists, attach a default sequence template, add entries in batch, and let Topo resolve contacts and enroll them into outreach.

Contact lists are staging areas where you queue individual leads before they run through a Topo sequence. You might create one list per cohort, import source, or audience segment. Each entry carries prospect fields (email, LinkedIn URL, employer domain, external CRM id) that Topo resolves to a workspace contact. When the list has an `ACTIVE` default sequence template with steps, resolved entries are enrolled automatically.

<Note>
  Read endpoints require `contact_lists:read`. Creating lists, updating metadata, adding entries, and deleting lists or entries require `contact_lists:write`.
</Note>

## Default sequence template

A list's `default_sequence_template_id` controls auto-enrollment:

* When you **create** a list with a default template, new entries enrolled through that list use that template.
* When you **PATCH** a list to set `default_sequence_template_id`, Topo validates the template is `ACTIVE` and has at least one step, then enrolls every existing entry whose contact is already resolved.
* Pass `"default_sequence_template_id": null` to clear the default without deleting the list.

Inactive templates or templates without steps are rejected with `422 ValidationIssue` — the list's other fields are not changed.

## Add entries

`POST /v1/contact-entries` accepts up to 100 items per request and returns a per-item `BatchResponse`. Each item needs `contact_list_id` and at least one of `email` or `linkedin_url`. Optional fields include `external_contact_id` for CRM correlation.

### Resolution and enrollment

When an entry matches a contact Topo already knows, `contact_id` is set **synchronously** in the response. If the list has an `ACTIVE` default template, enrollment starts immediately.

When the person is **not** yet in your workspace, `contact_id` is `null` in the response and Topo starts a lead-import workflow asynchronously. Enrollment (when configured) runs after import completes. Subscribe to the `contact_entry.resolved` webhook or poll the entry until `contact_id` appears.

`GET /v1/contact-entries` requires `contact_list_id` and supports filters including `email`, `company_domain`, `external_contact_id`, and enrichment state.

## Delete lists and entries

* `DELETE /v1/contact-lists/{contact_list_id}` — deletes the list and all its entries.
* `DELETE /v1/contact-entries/{contact_entry_id}` — removes a single entry from its list.

Deleting an entry that enrolled the contact from that list **stops the sequence** sourced from that list (`stopped_reason: REMOVED_FROM_SOURCE_LIST`). Other sequences for the same contact are unaffected.

<Tip>
  For direct enrollment when you already have a `contact_id`, use [`POST /v1/sequences`](/api-reference/sequences) instead of going through a list.
</Tip>