Search options#

Every search takes the same shape: say who you want (a natural-language query or structured filters), then optionally set how many and how strictly. These options work identically on the REST API and through the MCP tools, and any option the engine cannot honour is reported back in relaxed rather than silently ignored.

How many#

count · 1 to 25,000#

The one door for "give me N". Pass it once and the server handles pagination, deduplication, junk filtering and stopping.

Never page manually to build a list. One call is faster, has no duplicates, and tells you honestly when the pool ran out before your target.

{ "query": "founders in Australia with emails", "count": 200 }

columns#

Which fields each row carries.

Almost-right names just work: asking for about_us or revenue on a people search delivers the employer's company_about_us / company_revenue (the data arrives under its canonical name). A genuinely misspelled column is rejected with the full list of valid names, so you never receive a CSV with a silently empty column.

Rich payload columns on people (in full-width and by name): about_me, education, job_description, certifications, languages, email_last_verified_at, email_status, and the employer's company_about_us. They are export/enrich payload, present when the data source knows them.

How strictly#

quality_bar · strict | balanced | broad#

Used with count. Every returned row is tagged with the tier it qualified under (match_tier), so a mixed list is never presented as though it were uniform.

• strict , only high-confidence matches. Will under-fill rather than pad.
• balanced (default) , strict matches first, then clearly-labelled backfill.
• broad , ranked results, fill the target.

filters.strict · boolean#

Keywords normally rank results, they push good matches up but do not remove anything. Set strict and they must genuinely match, which narrows the set.

Requires keywords. If the signal needed to judge a match is unavailable, the response says so (strict_unavailable) instead of quietly returning a ranked list that looks narrowed.

filters.top_per_company · boolean#

One person per company, the most senior. Useful for account-based outreach where you want a single contact at each business rather than six people at one.

filters.expand · boolean#

"Include similar" , widen matching beyond the exact classification.

Currently unavailable. Semantic expansion is switched off, so a request with expand returns the exact filter and the response says so. Your results still benefit from concept matching (searching "insolvency" finds firms that only write "corporate recovery") and from label widening, which happen automatically.

Reading the response#

Three fields make every answer auditable:

• total , how many records match. Keyword searches also return strong_matches: the subset that genuinely matches the words rather than merely ranking for them. Quote that one when someone asks "how many".
• relaxed , plain-English notes for anything the engine changed: a value it did not recognise, a filter that does not apply, an employer it could not resolve. An empty relaxed means your query ran exactly as written.
• interpreted_text , how your query was understood, in a sentence.

Exports#

Anything above 500 rows becomes a job you pull a CSV from.

# Start (or just pass count > 500 to a search)
curl -X POST https://api.disburse.dev/v1/exports \
  -H "Authorization: Bearer $DISBURSE_API_KEY" \
  -d '{"query":"founders in Australia","target":5000}'
# -> { "id": "exp_...", "estimated_total": 9200, "estimated_bytes": 1150000 }
 
# Poll until it returns text/csv (202 means still rendering, with progress)
curl -L https://api.disburse.dev/v1/exports/exp_.../file \
  -H "Authorization: Bearer $DISBURSE_API_KEY" -o leads.csv

The estimate arrives before any work happens, so you know the real pool size and file size up front. Files carry a UTF-8 byte-order mark and CRLF line endings so Excel reads them correctly, and cells that a spreadsheet would otherwise execute as formulas are neutralised.

Exports expire 24 hours after they are created. Re-fetching a chunk returns identical bytes, so a dropped connection can never corrupt a file.