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) and is linked to a workspace contact when you add it. When the list has an ACTIVE default sequence template with steps, new 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. Each item in the response has one of these statuses:

​
Resolution and enrollment

Every entry is linked to a workspace contact in the request, so contact_id is always set in the response:
  • When the email or LinkedIn URL matches a contact Topo already knows, the entry uses that contact. If the list has an ACTIVE default template, enrollment starts immediately, and Topo sends the contact_entry.resolved webhook right away.
  • When the person is not yet in your workspace, Topo creates a new contact from the fields you sent and returns its contact_id. It then runs a lead-import workflow asynchronously to complete the profile and apply exclusions. Enrollment (when configured) runs after that import completes, and Topo sends the contact_entry.resolved webhook at that point.
Adding a contact that already sits in another list creates a new entry in this list for the same contact. 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.