Skip to main content
Contact lists are staging areas where you queue individual leads before they are enrolled in a Topo sequence. You might create one list per campaign, import cohort, or audience segment — Topo’s enrichment pipeline resolves each entry to a verified contact, and your agents then process the approved entries.
Read endpoints require the contact_lists:read scope. Create and update endpoints require contact_lists:write.

​
The Contact List object

​
id
string (UUID)
required
Unique identifier for the contact list.
​
name
string | null
Human-readable name of the list.
​
default_sequence_template_id
string (UUID) | null
When set, new entries added to this list are automatically enrolled into the referenced sequence template.
​
entries_count
integer
Current number of entries in the list.
​
created_at
string (ISO 8601)
Timestamp when the list was created.
​
updated_at
string (ISO 8601)
Timestamp when the list was last modified.

​
The Contact List Entry object

​
id
string (UUID)
required
Unique identifier for the entry.
​
contact_list_id
string (UUID)
ID of the contact list this entry belongs to.
​
contact_id
string (UUID) | null
ID of the verified contact this entry resolved to, once Topo’s enrichment pipeline has matched it. null until resolution is complete.
​
email
string | null
Email address supplied at creation.
​
first_name
string | null
First name.
​
last_name
string | null
Last name.
​
linkedin_url
string | null
LinkedIn profile URL.
​
company_name
string | null
Employer name.
​
company_domain
string | null
Employer’s primary domain.
​
job_title
string | null
Job title.
​
phone
string | null
Phone number.
​
description
string | null
Free-form notes attached to the entry.
​
location
string | null
Person’s location string as supplied.
​
created_at
string (ISO 8601)
Timestamp when the entry was created.
​
updated_at
string (ISO 8601)
Timestamp when the entry was last modified.

​
List contact lists

GET /v1/contact-lists Returns a paginated list of all contact lists in your workspace.

​
Query parameters

​
name
string
Exact-match filter on the list name.
​
created_at_after
string (ISO 8601)
Returns lists created strictly after this timestamp.
​
created_at_before
string (ISO 8601)
Returns lists created strictly before this timestamp.
​
sort_by
string
Field to sort by. One of created_at, updated_at, or name.
​
page
integer
default:"1"
Page number (1-indexed).
​
size
integer
default:"10"
Results per page. Maximum 100.

​
Response

Returns a paginated envelope with items, total_count, total_pages, and has_more.

​
Create contact lists

POST /v1/contact-lists Creates one or more contact lists in a single request. The endpoint follows batch semantics — it either creates all items or fails entirely; no partial results are returned.

​
Request body

​
items
array
required
Array of contact list objects to create. Maximum 100 items per request.

​
Response

Returns a batch response envelope.
​
items
array
Per-item results in the same order as the request.
​
summary
object
curl -X POST https://api.topo.io/v1/contact-lists \
  -H "Authorization: Bearer topo_sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "name": "Q3 Enterprise Inbound",
        "default_sequence_template_id": "f7e6d5c4-b3a2-1098-fedc-ba9876543210"
      },
      {
        "name": "Conference Leads — SaaStr 2025"
      }
    ]
  }'

​
Get a contact list

GET /v1/contact-lists/{contact_list_id} Fetches a single contact list by its UUID.

​
Path parameters

​
contact_list_id
string (UUID)
required
The unique identifier of the contact list.

​
Update a contact list

PATCH /v1/contact-lists/{contact_list_id} Updates mutable fields on an existing contact list. Only fields included in the request body are changed.

​
Path parameters

​
contact_list_id
string (UUID)
required
The unique identifier of the contact list.

​
Request body

​
name
string
New name for the list. Must be at least 1 character.
​
default_sequence_template_id
string (UUID) | null
New default sequence template. Pass null explicitly to clear the association; omitting the field leaves it unchanged.

​
List entries in a contact list

GET /v1/contact-entries Returns a paginated list of entries belonging to the specified contact list.

​
Query parameters

​
contact_list_id
string (UUID)
required
The contact list to scope the query to.
​
email
string
Exact-match filter on entry email.
​
company_domain
string
Exact-match filter on the entry’s company domain.
​
enriched
boolean
When true, returns only entries that have been matched to a verified contact. When false, returns only unresolved entries.
​
created_at_after
string (ISO 8601)
Returns entries created strictly after this timestamp.
​
created_at_before
string (ISO 8601)
Returns entries created strictly before this timestamp.
​
sort_by
string
Field to sort by. One of created_at, updated_at, email, or last_name.
​
page
integer
default:"1"
Page number.
​
size
integer
default:"10"
Results per page. Maximum 100.

​
Add entries to a contact list

POST /v1/contact-entries Adds up to 100 people to one or more contact lists in a single request. Each entry requires at least one of email or linkedin_url for Topo to resolve the identity.
Topo’s enrichment pipeline processes entries asynchronously after creation. The contact_id field on each entry will be null immediately after creation and populated once the match is confirmed.

​
Request body

​
items
array
required
Array of contact entry objects. Maximum 100 items per request.
curl -X POST \
  "https://api.topo.io/v1/contact-entries" \
  -H "Authorization: Bearer topo_sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "contact_list_id": "c9d8e7f6-a5b4-3210-9876-fedcba012345",
        "email": "jane.doe@acme.com",
        "first_name": "Jane",
        "last_name": "Doe",
        "job_title": "VP of Engineering",
        "company_name": "Acme Corp",
        "company_domain": "acme.com"
      },
      {
        "contact_list_id": "c9d8e7f6-a5b4-3210-9876-fedcba012345",
        "linkedin_url": "https://www.linkedin.com/in/john-smith-12345",
        "first_name": "John",
        "last_name": "Smith",
        "company_domain": "globex.io"
      }
    ]
  }'
Providing both email and linkedin_url increases match accuracy. If Topo can cross-reference both signals, enrichment quality improves significantly.