Database search

Start a CSV export

Optional body field: unmask: true fills missing contact details up to your monthly unmask budget. The default exports rows as stored. Status includes rows_unmasked and rows_masked_by_budget. Send the same option to POST /api/v1/contacts/search/count for unmask_preview: { rows, cached, new_unmasks, budget_remaining } without spending budget. MCP export_contacts and count_contacts accept this option too.

POST/api/v1/contacts/search/export

Start an async export of search matches to CSV on S3. Same filters as POST /api/v1/contacts/search (no offset). Returns immediately with export_id (HTTP 202); poll GET /api/v1/contacts/search/export/{export_id} until job_status is completed, then use export_url. Free plan: capped at min(creditsRemaining, total_available). Unlimited: subject to daily (500k) and monthly (6M) export caps. Optional max_rows (1-50,000) caps how many rows this export writes; omit to export all matches up to plan/credit/50k limits. 1 credit per row exported.

Authorization

Header	Type	Required	Description
`X-API-Key`	string	required	Your API key, for example `lb_live_YOUR_API_KEY`. You can send the same key as `Authorization: Bearer` instead.

Body parameters

Name	Type	Required
`filters`	object	optional
`max_per_company`	number	optional
`max_rows`	number	optional
`confirmed`	boolean	optional

Response

ok boolean: True when the request succeeded.
export_id string: The identifier of the export job.
job_status string: One of queued, running, completed or failed.
rows_available number: The number of rows that matched the filters.
export_row_cap number: The row cap applied to this export.
rows_capped_by_credits boolean: True when the credit balance limited the export.
message string: A plain sentence that explains the result.

curl -sS -X POST "https://leadmcp.ai/api/v1/contacts/search/export" \
  -H "X-API-Key: lb_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "filters": {
    "job_titles": ["Software Engineer"],
    "cities": ["San Francisco"]
  },
  "max_per_company": 3,
  "max_rows": 5000,
  "confirmed": true
}'

Response202

{
  "ok": true,
  "export_id": "01KV8DNW282Y2V5YAQ51C2XWN1",
  "job_status": "queued",
  "rows_available": 46169,
  "export_row_cap": 5000,
  "rows_capped_by_credits": true,
  "message": "Export started. Poll GET /api/v1/contacts/search/export/{export_id} until job_status is completed."
}