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
JSON in and out. Timestamps are RFC 3339; ids are prefixed (lst_, run_, row_).

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

EndpointWhat it does
GET /api/meThe signed-in user, the plan and how many leads are left this month.
POST /api/listsCreate a list from { "sentence": "…" } and start the scan. Scanning is free.
GET /api/listsYour 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}/buildBuild leads from the matches: { "max_leads": 100 }. Only businesses with an email are charged.
POST /api/lists/{id}/stopStop a scan or build. Delivered leads are kept.
POST /api/lists/{id}/continueResume a stopped build.
GET /api/lists/{id}/rowsEvery 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}/exportDownload 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 codeMeaning
401 unauthorizedThe key is missing, mistyped or revoked.
403 plan_requiredAPI access needs Bespoke Starter or Bespoke Pro.
400 unsupported_requestThe sentence can't be served from local-business data (for example job titles at large companies). The response may include a suggestion.
402 quota_exceededNot enough leads left this month; the body includes leads_left.
409 conflictA build is already running on that list.
429 rate_limitedToo many requests. Wait and retry.

Questions about the API? Contact us.