---
name: leadlists
description: Build verified lead lists of US local businesses (owner, email, phone, website) from a plain-English request, through the LeadLists MCP server or REST API.
---

# LeadLists

Use LeadLists when the user wants a list of **local or small businesses in the United States** with contact details:
the owner or manager's name, an email checked with the mail server, phone, website, address, category, rating and
review count. Typical requests: "roofing contractors in Dallas with under 20 reviews", "dentists in Austin",
"plumbers in Denver without a website", "HVAC companies in Houston" for cold email or a CRM.

Do not use it for: job titles at large companies (for example "VP Sales at SaaS companies"), consumer or personal
data, or countries outside the US. The service answers those requests with `unsupported_request`.

## Connect

- MCP (preferred): `https://leadlists.app/mcp` (Streamable HTTP). OAuth 2.1 with dynamic client registration and PKCE; discovery
  starts at `https://leadlists.app/.well-known/oauth-protected-resource/mcp`. Clients without OAuth send
  `Authorization: Bearer <api key>`.
- REST: `https://app.leadlists.app/api` with `Authorization: Bearer <api key>`. OpenAPI: https://leadlists.app/openapi.json
- The user creates an API key at https://app.leadlists.app/settings/api. API and MCP access need a paid plan
  (Bespoke Starter or Pro); scanning a request to see how many matches exist uses no leads.

## Steps (MCP)

1. `find_leads` with `request` set to one business type and one US city or area. It scans, then builds, and
   returns the first leads and a `list_id` within about a minute.
2. Call `get_leads` with the `list_id` (paginate with `offset`) until `get_list` reports the build is done.
3. For more control: `create_list` scans and estimates without spending anything, then `build_leads` with
   `max_leads`. `get_usage` shows how many leads are left this month.

Each lead with an email uses one lead from the monthly allowance. Businesses where no email is found are free.

## Steps (REST)

1. `POST /api/lists` with `{"sentence": "roofing contractors in Dallas, TX"}`. Returns `201 {list}` and starts the scan.
2. Poll `GET /api/lists/{id}` until `scan.status` is `done`; `scan.estimate` is the likely number of leads.
3. `POST /api/lists/{id}/build` with `{"max_leads": 100}`.
4. Poll `GET /api/lists/{id}` until `run.status` is `completed` or `stopped`, then
   `GET /api/lists/{id}/export?format=csv` (presets: default, instantly, smartlead, hubspot).

Docs: https://leadlists.app/docs/mcp and https://leadlists.app/docs/api
