Getting started
Exclusions, lists and exports
Keeping your customers out of every result, uploading a list from a file, and getting the full list out.
Keep companies out — for good
An exclusion list holds companies you never want back: your existing customers, your whole CRM, a competitor’s clients you already worked. Switch on Always exclude and the list applies to every search, count, lookalike, segmentation and export of your organization — from every agent, every key and the API — without anyone having to mention it.
It matches on the company, not on the exact text you uploaded: https://www.acme.de/kontakt,
acme.de and [email protected] all exclude acme.de.
An excluded company never comes back, whichever tool asked. We check this twice — once in the search itself and again on the way out — and alert ourselves if the second check ever catches anything.
Agencies: exclusions per client
If you work for several clients, each has its own customers to keep out — and client A’s customers are
fair game for client B. Give a list a client (a name you choose, e.g. acme):
- An always exclude list with a client applies only when you search for that client — your
agent passes
client: "acme", or you use an API key bound to Acme (set when you create the key). - An always exclude list without a client applies to everything you do — your own do-not-contact list, for example.
- A key bound to one client can only act for that client and only change that client’s lists, so an agent set up for Acme cannot touch another client’s data by mistake.
Every response says which client and which lists were applied (applied_exclusions).
Getting a list in
Four ways, the same result:
Upload a file on the dashboard
Lists → New list, pick a CSV or TXT file, tick Always exclude. The website/domain/URL/e-mail column is found by its header; comma, semicolon (European Excel) and tab separated files all work.
Give your agent a link
“Exclude every company in this sheet: https://docs.google.com/spreadsheets/d/… ” — the agent passes the link
as source_url and the file is imported in the background. A Google Sheet has to be shared as anyone with
the link; Dropbox links, signed S3/Google Cloud Storage links and any public CSV link work too. Best for
large files: 100,000 rows never pass through the conversation.
Paste or attach it in the conversation
An agent that can read your file passes its content as csv, or a list of domains (up to 5,000 per call).
Fine for a few thousand rows; for more, use a link or the dashboard.
Send it over the API
POST /v1/lists/:list_id/items with the raw file as the body (Content-Type: text/csv) — see the
REST reference.
Every import reports what it could not read, row by row, with the reason — nothing is dropped silently. Duplicates are ignored. An import that would take a list over your plan’s size is refused as a whole, so a list is never left half-updated.
Other kinds of list
- Seed lists are input for lookalikes: “find more companies like the 40 on my best-customers list”.
- Accounts lists are companies you want to keep together.
Search inside a list. Any list — seed, accounts, even an exclusion list — can also be the place you
search in: within_lists keeps only companies on it. Handy for narrowing an earlier export or your
CRM accounts.
Limits depend on the plan — 20 lists of up to 100,000 companies on Starter, more on higher plans (tested live with a 100,000-company list: uploaded in under 3 seconds, nothing leaked into 500 results); see records & rate limits. Deleting a list is done on the dashboard or over REST; agents can add and remove companies but deliberately cannot delete a list.
Exports
A search shows the top 100. An export gives you every company that matches — the same search or lookalike, run to the end — as a CSV or JSONL file.
- It runs in the background. Your agent gets a job id, checks on it, and hands you a download link when it is done.
- Each exported company costs a record. The export is capped at what you have left in your allowance, so it can never overdraw — see how the allowance works.
- Exclusion lists apply; the file is checked again before it is released.
- Retrying is safe: the same request with the same idempotency key returns the same export, never a second charge.
Download links are valid for 24 hours and can be re-issued as long as the file is kept (30 days). Treat a link like a password — anyone holding it can download the file.