Docs
LeadLists API
Everything the LeadLists app does, over HTTPS: describe the businesses you want in a sentence, build the leads, and download them in the columns your outreach tool expects.
Base URL and authentication
https://app.leadlists.app/api
Create an API key in the app under Settings, then API and send it on every request as Authorization: Bearer ll_…. A key is shown once; you can hold up to 10. The API is included on the Bespoke Starter and Bespoke Pro plans (pricing). The same key also works with the MCP server.
Build a list in four calls
# 1. Create a list and start the scan
curl -s https://app.leadlists.app/api/lists \
-H "Authorization: Bearer $LEADLISTS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"sentence": "roofing contractors in Dallas, TX with under 20 reviews"}'
# 2. Poll until scan.status is "done"; scan.estimate is the likely number of leads
curl -s https://app.leadlists.app/api/lists/lst_… -H "Authorization: Bearer $LEADLISTS_API_KEY"
# 3. Build up to 100 leads
curl -s https://app.leadlists.app/api/lists/lst_…/build \
-H "Authorization: Bearer $LEADLISTS_API_KEY" \
-H "Content-Type: application/json" -d '{"max_leads": 100}'
# 4. When run.status is "completed", download the leads
curl -s -o leads.csv "https://app.leadlists.app/api/lists/lst_…/export?format=csv&preset=instantly" \
-H "Authorization: Bearer $LEADLISTS_API_KEY"Each lead with an email uses one lead from your monthly allowance. Businesses where no email is found are free, and so is scanning.
Endpoints
| Endpoint | What it does |
|---|---|
GET /api/me | The signed-in user, the plan and how many leads are left this month. |
POST /api/lists | Create a list from { "sentence": "…" } and start the scan. Scanning is free. |
GET /api/lists | Your lists, newest first. |
GET /api/lists/{id} | A list with its latest scan (matches, estimate) and build (progress). |
PATCH /api/lists/{id} | Rename it or change the spec. Changing filters re-filters at once; changing who or where rescans. |
POST /api/lists/{id}/build | Build leads from the matches: { "max_leads": 100 }. Only businesses with an email are charged. |
POST /api/lists/{id}/stop | Stop a scan or build. Delivered leads are kept. |
POST /api/lists/{id}/continue | Resume a stopped build. |
GET /api/lists/{id}/rows | Every row: matches, leads and businesses without an email. Use after_rev for changes only. |
GET /api/rows/{id} | One row, with the page and sentence its email and owner came from. |
GET /api/lists/{id}/export | Download as format=csv|xlsx, preset=default|instantly|smartlead|hubspot, scope=leads|all. |
DELETE /api/lists/{id} | Delete a list. |
The full request and response shapes are in the OpenAPI 3.1 spec, and every API is listed in the API catalog. Service health: https://app.leadlists.app/healthz.
Errors
Errors are JSON: {"error": "<code>", "message": "<human text>"}.
| Status and code | Meaning |
|---|---|
401 unauthorized | The key is missing, mistyped or revoked. |
403 plan_required | API access needs Bespoke Starter or Bespoke Pro. |
400 unsupported_request | The sentence can't be served from local-business data (for example job titles at large companies). The response may include a suggestion. |
402 quota_exceeded | Not enough leads left this month; the body includes leads_left. |
409 conflict | A build is already running on that list. |
429 rate_limited | Too many requests. Wait and retry. |
Questions about the API? Contact us.