> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Accounts API: Look Up Companies and Manage Account Lists

> Upsert accounts by domain, list them by domain or name, reassign owners, manage account custom variables, and manage account lists with domain-keyed entries and CRM correlation.

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`.

<Note>
  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`.
</Note>

## 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`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.topo.io/v1/accounts \
  -H "Authorization: Bearer topo_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Analytical Engines",
    "domain": "analytical.io"
  }'
```

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](/api-reference/pagination-filtering).

| Parameter | Description                                            |
| --------- | ------------------------------------------------------ |
| `domain`  | Case-insensitive exact match on primary company domain |
| `name`    | Case-insensitive substring match on company name       |

`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](/api-reference/contacts#custom-variables): 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](/api-reference/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.

<Tip>
  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.
</Tip>