---
title: "LeadLists API Docs: Build Lead Lists over REST"
description: "The LeadLists REST API: create a lead list from a sentence, build verified leads and export them as CSV or Excel with an API key. Endpoints, errors and an OpenAPI spec."
url: https://leadlists.app/docs/api
---

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](https://app.leadlists.app/settings/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](https://leadlists.app/pricing)). The same key also works with the [MCP server](https://leadlists.app/docs/mcp).

## 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](https://leadlists.app/openapi.json), and every API is listed in the [API catalog](https://leadlists.app/.well-known/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](https://leadlists.app/contact).
