# Leadity

> Leadity sells business leads scraped live from Google Maps, paid per lead in credits. These docs cover the Leadity HTTP API, the Leadity MCP server for AI agents, API keys and scopes, how to spend credits safely, and a reference page for every operation.

Agents can search and read these docs over MCP at https://docs.leadity.io/mcp (no key needed). The HTTP API publishes an OpenAPI document at https://api.leadity.io/v1/openapi.json. Every page below is also served as Markdown at its own URL plus .md.

## Documentation

- [Introduction](https://docs.leadity.io/introduction.md): Order business leads scraped live from Google Maps, from your own code or from an AI agent.
- [Quickstart](https://docs.leadity.io/quickstart.md): Create a key, make your first request and place your first order in a few minutes.
- [Authentication](https://docs.leadity.io/authentication.md): Send your key as a Bearer token on every request. Every account check still applies to it.
- [API keys and scopes](https://docs.leadity.io/api-keys.md): Two kinds of key, three scopes, and at most five live keys of each kind per account.
- [Making requests](https://docs.leadity.io/making-requests.md): The base URL, the request and response format, and the OpenAPI document.
- [Filters](https://docs.leadity.io/filters.md): The independent filters an order can turn on, and how each one changes what is delivered.
- [Pagination](https://docs.leadity.io/pagination.md): Lists page with a cursor. A live scrape's leads are complete only once the scrape has settled.
- [Polling and status](https://docs.leadity.io/polling.md): There are no webhooks. Poll a running scrape every 30 to 60 seconds until it is complete.
- [Downloads](https://docs.leadity.io/downloads.md): Leads, reviews and validation results as CSV files, and as short-lived links on MCP.
- [Rate limits](https://docs.leadity.io/rate-limits.md): Too many requests answer 429 with a Retry-After header. Wait that long and try again.
- [Errors](https://docs.leadity.io/errors.md): Every refusal answers the same small body with a stable code. This is the whole list.
- [Spending credits safely](https://docs.leadity.io/spending-credits.md): Price first, cap every purchase with maxCredits, and retry with the same Idempotency-Key.
- [Idempotency](https://docs.leadity.io/idempotency.md): Every call that takes credits carries a key of yours, so a retry replays the first answer instead of buying twice.
- [Changelog](https://docs.leadity.io/changelog.md): What Leadity can do now that it could not before, newest first.

## API Reference

- [API reference](https://docs.leadity.io/api-reference/introduction.md): Every operation of the Leadity HTTP API, generated from the definitions the API itself runs.
- [List niches](https://docs.leadity.io/api-reference/catalog/list-niches.md): List the niches you can order, grouped by market.
- [Get pricing](https://docs.leadity.io/api-reference/catalog/get-pricing.md): Read the price card: what each lead and each filter costs, in credits.
- [List territories](https://docs.leadity.io/api-reference/catalog/list-territories.md): List the countries and the regions you can order in.
- [List areas](https://docs.leadity.io/api-reference/catalog/list-areas.md): List one region's areas and their ZIP or postal codes.
- [Search areas](https://docs.leadity.io/api-reference/catalog/search-areas.md): Find areas and ZIP or postal codes by name across a country.
- [Get coverage](https://docs.leadity.io/api-reference/catalog/get-coverage.md): See which areas you have already swept for each niche.
- [Get account](https://docs.leadity.io/api-reference/account/get-account.md): Read the account's balance and what this key may do.
- [Get scrape defaults](https://docs.leadity.io/api-reference/account/get-scrape-defaults.md): Read the filters and lead count the account's new orders open on.
- [Get analytics](https://docs.leadity.io/api-reference/account/get-analytics.md): Read what the account has swept and owns, per niche and state.
- [List plans](https://docs.leadity.io/api-reference/billing/list-plans.md): List both credit ladders: monthly plans and one-time packs.
- [Get subscription](https://docs.leadity.io/api-reference/billing/get-subscription.md): Read the account's plan and every credit expiry.
- [List credit history](https://docs.leadity.io/api-reference/billing/list-credit-history.md): Read the credit ledger: every purchase, spend, refund and expiry.
- [Create checkout](https://docs.leadity.io/api-reference/billing/create-checkout.md): Open a checkout and answer the link a person pays at.
- [Create top up checkout](https://docs.leadity.io/api-reference/billing/create-top-up-checkout.md): Open a checkout that adds credits to the monthly plan, and answer the link a person pays at.
- [Estimate scrape](https://docs.leadity.io/api-reference/scrapes/estimate-scrape.md): Quote an order for free: what is still new, the per-lead rate and the floors.
- [Create scrape](https://docs.leadity.io/api-reference/scrapes/create-scrape.md): Order a scrape: find businesses live on Google Maps and deliver them as leads.
- [List scrapes](https://docs.leadity.io/api-reference/scrapes/list-scrapes.md): List the account's scrapes, newest first.
- [Get scrape](https://docs.leadity.io/api-reference/scrapes/get-scrape.md): Read one scrape in full: its selection, its progress and its upgrades.
- [Get scrape status](https://docs.leadity.io/api-reference/scrapes/get-scrape-status.md): Poll a scrape cheaply: its status, and whether it is complete.
- [Rename scrape](https://docs.leadity.io/api-reference/scrapes/rename-scrape.md): Rename a scrape.
- [Stop scrape](https://docs.leadity.io/api-reference/scrapes/stop-scrape.md): Stop a live scrape: keep what it delivered and refund the rest.
- [List leads](https://docs.leadity.io/api-reference/scrapes/list-leads.md): Read a scrape's delivered leads, a page at a time.
- [Download leads](https://docs.leadity.io/api-reference/scrapes/download-leads.md): Download a scrape's delivered leads as one CSV file.
- [Download reviews](https://docs.leadity.io/api-reference/scrapes/download-reviews.md): Download the Google reviews a scrape walked, as one CSV file.
- [Export scrapes](https://docs.leadity.io/api-reference/scrapes/export-scrapes.md): Download several scrapes' leads as one CSV file.
- [List scrape offers](https://docs.leadity.io/api-reference/scrapes/list-scrape-offers.md): List what a finished scrape can still sell, with prices. Free.
- [Purchase residuals](https://docs.leadity.io/api-reference/scrapes/purchase-residuals.md): Buy one cell of a finished scrape's held-back businesses.
- [Purchase phone reveal](https://docs.leadity.io/api-reference/scrapes/purchase-phone-reveal.md): Buy the phone line types of a finished scrape's delivered leads.
- [Purchase email find](https://docs.leadity.io/api-reference/scrapes/purchase-email-find.md): Buy email addresses for a finished scrape's delivered leads.
- [Purchase email verify](https://docs.leadity.io/api-reference/scrapes/purchase-email-verify.md): Buy deliverability verdicts for a finished scrape's email addresses.
- [Purchase owner names](https://docs.leadity.io/api-reference/scrapes/purchase-owner-names.md): Buy owner names for a finished scrape's delivered leads.
- [Preview validation](https://docs.leadity.io/api-reference/validations/preview-validation.md): Quote a list for free: how many items survive parsing and what they cost.
- [Create validation](https://docs.leadity.io/api-reference/validations/create-validation.md): Validate a list of phone numbers or email addresses you supply.
- [List validations](https://docs.leadity.io/api-reference/validations/list-validations.md): List the account's validation runs, newest first.
- [Download validation](https://docs.leadity.io/api-reference/validations/download-validation.md): Download a validation run's answers as one CSV file.
- [Get validation](https://docs.leadity.io/api-reference/validations/get-validation.md): Read one validation run, with its verdict counts.
- [List validation items](https://docs.leadity.io/api-reference/validations/list-validation-items.md): Read a validation run's answers, a page at a time.
- [Stop validation](https://docs.leadity.io/api-reference/validations/stop-validation.md): Stop a live validation run: keep what it answered and refund the rest.

## MCP

- [MCP server](https://docs.leadity.io/mcp/overview.md): The Leadity operations as tools for any AI agent that speaks the Model Context Protocol.
- [Set up the MCP server](https://docs.leadity.io/mcp/setup.md): Connect Claude Code, Claude Desktop, Cursor or any MCP client to Leadity with an MCP key.
- [MCP tools](https://docs.leadity.io/mcp/tools.md): Every tool the Leadity MCP server offers, with its scope and how a client should treat it.
- [Docs MCP for agents](https://docs.leadity.io/mcp/docs-mcp.md): A public MCP server that lets any agent search and read these docs, with no key.

## Optional

- [All pages in one file](https://docs.leadity.io/llms-full.txt): every page above, in full