Lists & exclusions
Create a company list
Create a list of companies (by domain).
POST
/v1/listsParameters
namestringrequiredUnique within your organization.
kind"exclusion" | "seed" | "accounts"requiredexclusion = never return these · seed = input for find_similar · accounts = a list to keep
auto_excludebooleanoptionalexclusion lists only: apply automatically without naming the list — to every call of your organization, or with
client only to calls for that clientclientstringoptionalAGENCIES: the client this list belongs to (e.g. ‘acme’). Its auto-exclusion then applies only to calls for that client.
domainsstring[]optionalDomains, URLs or e-mail addresses — the company is taken from each. (up to 5000 items)
csvstringoptionalThe 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_urlstringoptionalAn 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.
columnstringoptionalHeader of the column holding the domains, when the file has several candidates.
idempotency_keystringoptionalWith 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.
Create a list of companies (by domain). kind: 'exclusion' = never return these (e.g. your existing customers or
your whole CRM), 'seed' = input for find_similar, 'accounts' = a list you want to keep. With auto_exclude=true an
exclusion list applies to EVERY search, count, lookalike and export of your organization without naming it.
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.