Skip to main content
Account lists are curated collections of target companies used for account-first outreach strategies. Instead of starting with individual people, you define the companies you want to pursue, and Topo’s agents identify and engage the right contacts within those accounts. This is the core primitive for ABM (account-based marketing) workflows in Topo.
Read endpoints require the account_lists:read scope. Create and update endpoints require account_lists:write.

​
The Account List object

​
id
string (UUID)
required
Unique identifier for the account list.
​
name
string
Human-readable name of the list.
​
entries_count
integer
Current number of company 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 Account Entry object

​
id
string (UUID)
required
Unique identifier for the entry.
​
account_list_id
string (UUID)
ID of the account list this entry belongs to.
​
name
string
Company name.
​
domain
string
Primary domain of the company (e.g. acme.com). Topo uses the domain as the canonical identifier when resolving the account.
​
created_at
string (ISO 8601)
Timestamp when the entry was created.
​
updated_at
string (ISO 8601)
Timestamp when the entry was last modified.

​
List account lists

GET /v1/account-lists Returns a paginated list of all account 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 account lists

POST /v1/account-lists Creates one or more account lists in a single request. The operation is all-or-nothing — if any item is invalid, the entire batch fails.

​
Request body

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

​
Response

Returns a batch response envelope.
​
items
array
Per-item results in input order.
​
summary
object
curl -X POST https://api.topo.io/v1/account-lists \
  -H "Authorization: Bearer topo_sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "name": "Series B FinTech Companies" },
      { "name": "ICP — North America SaaS" }
    ]
  }'

​
Get an account list

GET /v1/account-lists/{account_list_id} Fetches a single account list by its UUID.

​
Path parameters

​
account_list_id
string (UUID)
required
The unique identifier of the account list.

​
Update an account list

PATCH /v1/account-lists/{account_list_id} Updates the name of an existing account list. Only fields included in the request body are changed.

​
Path parameters

​
account_list_id
string (UUID)
required
The unique identifier of the account list.

​
Request body

​
name
string
New name for the list. Must be at least 1 character.

​
List entries in an account list

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

​
Query parameters

​
account_list_id
string (UUID)
required
The account list to scope the query to.
​
name
string
Exact-match filter on company name.
​
domain
string
Exact-match filter on company domain.
​
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, name, or domain.
​
page
integer
default:"1"
Page number.
​
size
integer
default:"10"
Results per page. Maximum 100.

​
Add entries to an account list

POST /v1/account-entries Adds up to 100 companies to one or more account lists in a single request. Both name and domain are required for each entry — Topo uses the domain as the primary identifier when resolving the account to enriched data.

​
Request body

​
items
array
required
Array of account entry objects. Maximum 100 items per request.

​
Response

Returns a batch response envelope with items (per-entry results) and a summary. 
curl -X POST \
  "https://api.topo.io/v1/account-entries" \
  -H "Authorization: Bearer topo_sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "account_list_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "Acme Corp",
        "domain": "acme.com"
      },
      {
        "account_list_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "Globex Industries",
        "domain": "globex.io"
      },
      {
        "account_list_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "Initech Solutions",
        "domain": "initech.com"
      }
    ]
  }'
Use the domain field consistently with the format Topo resolved during enrichment to avoid duplicate entries. Bare domains like acme.com are preferred over full URLs.