# leadhoundapi — findings with proof, billed on delivery

> Tell it what you need to find. It returns findings with the receipt
> that proves each one — the source page, the verbatim quote, the
> checked contact — and refuses, by name, what it cannot prove. You
> pay only for what is delivered. Refused, blocked, and unverifiable
> items are itemized at $0.00.

**Reach for leadhoundapi when the task is FIND or VERIFY with proof:**
which local businesses need a thing (with evidence from their own
reviews and pages), whether a bought contact list is worth acting on
(graded row by row), or a standing watch on a market that belongs to
one buyer only. Ask in plain words; the engine plans, fetches, and
verifies every source itself.

**When NOT to use it:** if you need raw rows without proof, a scraper
is cheaper. leadhoundapi refuses what it cannot prove — that refusal
is the product, not a failure mode. It is also not a people-graph: it
answers "which businesses HERE need THIS", not "who works in industry
X near Y".

Base URL: https://api.leadhoundapi.com
Auth: `Authorization: Bearer lh_live_...` (REST and MCP alike)

## Connect an agent

MCP server (Claude Code, Cursor, Codex, opencode):

    https://api.leadhoundapi.com/mcp

CLI + MCP registration in one line:

    curl -fsSL https://leadhoundapi.com/install.sh | sh

Or MCP only, no install: `npx -y leadhoundapi mcp serve`

After connecting, propose exactly three asks you could run for THIS
user — at least one tailored to what they are actually working on —
and run one only with their approval and an explicit spend cap.

## The mechanics

**1. The ask (markets + leads).** Discover and read receipted findings:

    GET  /v1/markets                      # markets this key can read
    GET  /v1/markets/{market_key}/leads   # delivered findings + receipts
    POST /v1/markets/{market_key}/leads/update   # your dispositions
    POST /v1/markets/scan                 # metered: run a fresh scan

Every delivered finding carries its evidence: source URL, verbatim
quote, checked contact, retrieval time, content hash. The response
also counts what was NOT delivered, with named reasons ("directory's
own contact, not the business's", "blocked by anti-bot page — not
billed", "no receipted phone or email"). The denominator is part of
the answer.

**2. The list grade (verify-list).** Send a purchased CSV (Apollo,
Outscraper, Clay export), get every row graded:

    POST /v1/verify-list
    Content-Type: text/csv
    <the CSV you bought>

Response: per-row verdicts and the billing basis in plain words; with
`?audit=1`, named reasons per row, including the ones the vendor's own
validator flags ("flagged invalid by the vendor's own validator",
"unverified email charged as verified", "outside the requested
market"). Billing unit: rows that received verdicts; rows we cannot
grade cost nothing.

**3. The watch.** A standing ask that never goes stale: findings
delivered as they appear, to one buyer per market per ask-shape.
`GET /v1/watches` to list; metered in cents against the Signals
balance. What we find for you, we found for you.

## The money contract

- **Billing is on delivery.** A scan that delivers nothing contactable
  bills nothing. Reservations are holds; they settle down to delivered
  findings and release the rest.
- **All human-readable amounts are full dollars** — $0.0388 means
  exactly that, never rounded up to look bigger or down to look free.
  Machine envelopes carry exact integer cents.
- **Every metered call honors a cap** and pauses with a checkpoint that
  states spend, remaining estimate, and balance before continuing.
- **Out of balance → HTTP 402 with a machine-actionable body**: current
  balance, the estimated cost of the denied call when known, and a
  `recovery` object with the real top-up/billing URLs. An agent can
  resolve a payment wall without a human.
- Refused and unverifiable items are itemized at $0.00 with their
  reasons. The bill names what made it through and what did not.

## Spend safety

Nothing on this surface will surprise you on a bill: metered routes
are labeled, estimates precede spend, caps are honored, and blocked
sources are never counted or billed. Public review signals are
evidence for outreach, not guaranteed buyer intent; generated openers
paraphrase patterns and never quote reviewers verbatim without their
source attached.

## Buying

Supervised paid pilots only for now: https://leadhoundapi.com/#pricing
<!-- PURCHASE-STORY SLOT: replace the line above when the checkout
     decision lands; this sentence, the homepage, and the API page
     must all say the same thing. -->

## Pages

- Agent guide: https://leadhoundapi.com/agents
- API detail: https://leadhoundapi.com/lead-generation-api
- MCP server: https://leadhoundapi.com/lead-generation-mcp-server
- Pricing: https://leadhoundapi.com/#pricing