Skip to main content
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.
Read endpoints require contact_lists:read. Creating lists, updating metadata, adding entries, and deleting lists or entries require contact_lists:write.

​
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.
For direct enrollment when you already have a contact_id, use POST /v1/sequences instead of going through a list.