Skip to Content
API & MCPPOSTAdd companies to a list

Lists & exclusions

Add companies to a list

Add companies to one of your lists.

POST/v1/lists/:list_id/items
MCP tool add_to_listscope lists:writeNo record cost

Parameters

list_idstringrequired
From create_list or get_lists.
domainsstring[]optional
Domains, URLs or e-mail addresses — the company is taken from each. (up to 5000 items)
csvstringoptional
The content of a CSV/TSV/TXT file, as-is (≤4 MB). The domain/website/URL/e-mail column is found by its header, or pass column.
source_urlstringoptional
An https link to a CSV file (a Google Sheet shared as ‘anyone with the link’, Dropbox, a signed S3/GCS URL, any public CSV). Imported in the background: returns an import job; poll get_job.
columnstringoptional
Header of the column holding the domains, when the file has several candidates.
idempotency_keystringoptional
With source_url: a retry returns the same import job.

What your agent reads

The tool description exactly as an MCP client receives it in tools/list — it doubles as the full behaviour of the endpoint.

Add companies to one of your lists. Duplicates are ignored; unreadable rows are reported back with the reason. The change applies to the very next search. Companies go in one of three ways: `domains` (up to 5000 domains/URLs/e-mails per call), `csv` (the content of a CSV file as-is — the website/domain/e-mail column is found by its header; ; and tab separated files work), or `source_url` (an https link to a CSV: a Google Sheet shared as 'anyone with the link', Dropbox, a signed S3/GCS URL). Prefer source_url for large files (10k+ rows) — it is imported in the background and never passes through the conversation; poll get_job with the returned job_id. If the user only has a file on their computer and you cannot read it, point them to https://app.breaknorm.co/lists (upload with 'Always exclude').

Errors follow one format.

POSTCreate a company listDELRemove companies from a list