Skip to main content
An account is the org-scoped company record Topo uses for account-based workflows — the employer linked to contacts, the target of account lists, and the resolution target for first-party events keyed on company_domain.
Reading accounts and their variables requires accounts:read. Upserting accounts, reassigning owners, and managing variables require accounts:write. Account lists and entries use account_lists:read and account_lists:write.

​
Upsert an account

POST /v1/accounts creates an account or returns the matching one if it already exists. Topo matches inside your organization on domain (normalized), so re-sending the same company is safe and always returns the same id. name is only used when the account does not exist yet. Both create and match return 201.
Upserting a contact with company_domain (POST /v1/contacts) creates the account implicitly — use this endpoint when you want to push companies before knowing which people to pursue.

​
List and look up accounts

GET /v1/accounts returns accounts in your workspace with the standard pagination envelope. GET /v1/accounts/{account_id} fetches a single account.

​
Reassign owner

PATCH /v1/accounts/{account_id}/owner with { "owner_user_id": "<uuid>" } reassigns the account owner to a workspace user.

​
Custom variables

Accounts carry the same kind of key-value variables as contacts. An account holds a maximum of 200 variables. Setting a key’s value to null clears the value but does not free its slot toward the limit — use DELETE /v1/accounts/{account_id}/variables/{key} to fully remove a key.
  • GET /v1/accounts/{account_id}/variables — read the account’s variables
  • PATCH /v1/accounts/{account_id}/variables — merge variables into the account
  • DELETE /v1/accounts/{account_id}/variables/{key} — remove one key
These are the same variables exposed as account_variables on the Contact variables endpoints: writing through either surface updates the same account-level store, shared by every contact linked to the account.

​
Account lists and entries

Account lists are curated company collections for account-first outreach. The Account lists guide covers list CRUD; entries are the rows you add to a list. POST /v1/account-entries accepts up to 100 items per batch. Each item needs account_list_id, name, and domain. List entries expose account_id once Topo matches the row to a workspace account — use it to correlate list imports with GET /v1/accounts without re-querying by domain. GET /v1/account-entries requires account_list_id and supports domain and name filters. DELETE /v1/account-entries/{account_entry_id} removes one entry. DELETE /v1/account-lists/{account_list_id} deletes a list and its entries.
When upserting contacts, company_domain on POST /v1/contacts links the person to an account (and creates the account when needed). Account lists are for staging companies before you know which people to pursue.