# 411data — full machine documentation

> Agent-native lead and business-data enrichment API.
> Origin: https://411data.io
> Skill: https://411data.io/skill.md
> MCP: https://411data.io/mcp

## Identity

411data packages reverse phone and person lookup, LLM web-search
enrichment, and agentic lead-session orchestration. Every request and response
is stored in `request_response_store`, and billing debits virtual USD balance
first then x402 USDC on Base. **Bill-on-match** routes refund the charge when
no usable result is found.

Bearer tokens: `411_…` (admin) or scoped usage keys `411k_…` (enrichment
routes only, per-key spend caps).

## Billing waterfall

1. Debit `virtual_balance_usd` on the agent (~$0.20 starting credit at wallet mint).
2. When balance < route price → `402 Payment Required` with x402 envelope.
3. Settle with `PAYMENT-SIGNATURE` header (EIP-3009 USDC on Base) or MPP allowance.

402 JSON includes: `billing_reason`, `virtual_balance_usd`, `connect_url`,
`topup_url`, `llm_user_message`, `detail`.

Prepay without wallet signing: send USDC from a linked wallet →
`POST /api/v1/balance/deposit/claim`. See `/cookbook/prepay_deposits`.

## MCP tools (live catalogue)

Server: `411data` at `https://411data.io/mcp`
Auth: `Authorization: Bearer 411_…`

| Tool | Method | Path | Default price |
|------|--------|------|---------------|
| agents_me | GET | /api/v1/agents/me | Free |
| agents_balance | GET | /api/v1/agents/balance | Free |
| enrich_phone | POST | /api/v1/enrich/phone | $0.330 |
| enrich_person | POST | /api/v1/enrich/person | $0.500 |
| enrich_websearch | POST | /api/v1/enrich/websearch | $1.000 min (+ 30% when COGS > $1) |
| enrich_lead_session | POST | /api/v1/enrich/lead-session | $1.500 base |
| submit_enrich_job | POST | /api/v1/enrich/jobs | Bill up to $1.500 |
| get_enrich_job | GET | /api/v1/enrich/jobs/{job_id} | Free (poll_bearer) |
| support_tickets | POST | /api/v1/support/tickets | $0.010 ($1.00 credit for confirmed bugs) |

Catalog-tier tools (`enrich_email`, `enrich_company`, `leads_search`) are
offline by default (`CATALOG_ROUTES_ENABLED=0`).

## REST — enrichment

### POST /api/v1/enrich/phone

Body: `{"phone": "+17242060094"}`

Reverse phone lookup. Same backend as `enrich/person` with phone-only input.
Returns person name, emails, and addresses in `data.people`.

Example input is a verified Whitepages reverse-phone hit (returns multiple
`people` rows; first match shown below).

Response shape:
```json
{
  "endpoint": "enrich/phone",
  "input": {"phone": "+17242060094"},
  "matched": true,
  "data": {
    "people": [{
      "name": "James W Cole Sr",
      "aliases": ["James Cole Jr", "Jim W Cole"],
      "phones": [{
        "number": "(724) 206-0094",
        "label": "unknown",
        "score": 71,
        "type": "unknown",
        "source": "https://411data.io/person-hunt"
      }],
      "emails": [],
      "addresses": [],
      "relatives": [],
      "source": "https://411data.io/person-hunt",
      "wp_id": "PX3vrMbpE3k"
    }],
    "metadata": {"result_count": 5, "query_mode": "reverse_phone", "page": 1, "page_size": 5}
  },
  "vendor": "whitepages",
  "cache_hit": false,
  "billed": true
}
```

When `matched` is false on a bill-on-match route, the charge is refunded.

### POST /api/v1/enrich/person

Body: `{"name": "John Smith", "state_code": "PA", "zipcode": "15213"}` —
or reverse phone via `{"phone": "+17242060094"}`.

Person search for phones (including mobile), emails, and addresses.

### POST /api/v1/enrich/websearch

Body: `{"business_name": "Acme Corp", "city": "Tampa", "state": "FL", "domain": "acme.com"}`

LLM + web search for public phones, people, and addresses. Use when structured
vendors lack coverage for a business name.

### POST /api/v1/enrich/lead-session

Body: `{"lead": {"company": "Acme Corp", "number1": "4125550100"}, "budget_usd": 2.0}`

Multi-tool agentic enrichment (directory hunts, web research, synthesis).
$1.500 base pre-charged; supplemental debit when session vendor COGS × margin
exceeds base. Bill-on-match refunds when no usable enrichment fields are found.

### POST /api/v1/enrich/jobs (async queue)

Body:
```json
{
  "route": "enrich/websearch",
  "payload": {"business_name": "Acme Corp", "city": "Tampa", "state": "FL"},
  "bill_up_to_usd": 1.5,
  "callback_url": "https://example.com/hooks/enrich"
}
```

Supported `route`: `enrich/websearch`, `enrich/lead-session`, and partial lead-session ops
(`enrich/lead-session/slot-rerun`, `enrich/lead-session/slot-person`,
`enrich/lead-session/slots-rerun`, `synthesize-patch`, `finding-rerun`, `sic-rerun`).
Default `bill_up_to_usd` is the route catalog price when omitted (**$1.50** for full
sessions; **$0.35** per slot-rerun or slot-person; **N × $0.35** for slots-rerun);
client override up to **$50.00**.

**Billing paths:**
1. **Virtual balance** — `Authorization: Bearer 411_…` (no payment header).
   Pre-charges `bill_up_to_usd`, returns **202** with `poll_bearer` (`411j_…`),
   refunds unused credit on completion (`billing_status: settled_virtual`).
2. **CDP x402 upto** — no bearer → **402** (`scheme: upto`, `maxTimeoutSeconds: 1200`)
   → sign Permit2 → retry with `PAYMENT-SIGNATURE` → **202** → deferred on-chain
   settle (`billing_status: settled`). **$0 on no-match.**

### GET /api/v1/enrich/jobs/{job_id}

Poll job status. Requires `Authorization: Bearer <poll_bearer>` from the 202 body
(or the owning agent bearer). Returns `status`, `billing_status`, `result`,
`settled_usd`, `settle_tx_hash`.

Full recipe: `/cookbook/async_enrich_jobs`.

### POST /api/v1/support/tickets

Body: `{"subject": "Billing question", "body": "…"}`

Open a support thread ($0.010 flat). Use `category: bug` for reproducible defects —
eligible for a $1.00 virtual USD credit after operator confirmation.

## Catalog routes (offline by default)

These return `503` unless `CATALOG_ROUTES_ENABLED=1`:

- `POST /api/v1/enrich/email` — `{"email": "jane@acme.com"}` — $0.100
- `POST /api/v1/enrich/company` — `{"company": "Acme Corp", "domain": "acme.com"}` — $0.100
- `POST /api/v1/leads/search` — filtered B2B list with `cursor` pagination — $0.100/page

## Free routes (always-free surface)

- `/`, `/about`, `/developers`, `/quickstart`, `/example-questions`, `/pricing`, `/x402`, `/enrich_agent`
- `/skill.md`, `/llms.txt`, `/llms-full.txt`, `/openapi.json`, `/openapi-free.json`
- `/.well-known/*`, `/mcp`, `/mcp.json`, `/mcp/setup`, `/healthz`
- `/api/v1/agents/wallet-nonce`, `/api/v1/agents/wallet-register`
- `/api/v1/onramp/challenge`, `/api/v1/onramp/session`
- `/cookbook`, `/cookbook/*` (markdown recipes)

Account routes (free with bearer): `/api/v1/agents/me`, `/api/v1/agents/balance`,
`/api/v1/agents/wallets`, token rotate, wallet link/unlink.

Admin-only free: `GET/POST/DELETE /api/v1/keys` (scoped usage keys).

## Usage keys

Admin bearer creates `411k_…` keys for scripts and automation. Keys are scoped
to enrichment + lead routes and enforce daily/per-key spend caps.
Manage at `/connect?action=usage-keys`.

## Mint flow (wallet-bound)

1. `POST /api/v1/agents/wallet-nonce` → SIWE message + allowance intent
2. Sign both with `personal_sign`
3. `POST /api/v1/agents/wallet-register` → bearer `411_…` (shown once)

Requires ≥ $1 USDC on Base at mint. Starting balance: $0.20 virtual USD.

## x402 discovery

- `GET /.well-known/x402` — full paid-route catalogue (live routes only)
- `GET /discovery/resources` — Bazaar enumeration
- `GET /openapi.json` — OpenAPI with `x-payment-info` per operation

## Cookbook

https://411data.io/cookbook — worked examples for enrichment patterns.

Key recipes:
- filter_discipline_meta — compose filters before paying
- enrich_websearch_when — structured lookup vs LLM websearch
- async_enrich_jobs — deferred billing (virtual balance + CDP upto)
- bill_on_match — refund semantics
- anti_invent — refuse to hallucinate contact data

## Do NOT

- Invent emails, phones, or titles when tools return no match.
- Stay within 411data scope — lead and business enrichment only; refuse unrelated product catalogs (fitment, inventory, etc.).
- Forecast lead quality scores — the API returns observed enrichment only.

## Links

- Connect / mint: https://411data.io/connect
- Enrich agent (hosted chat): https://411data.io/enrich_agent
- Playground: https://411data.io/playground
- Top-up: https://411data.io/connect?action=topup

<!-- 411data:email-signup-discovery -->
### POST /api/v1/signup/email

Body: `{"email": "you@company.com"}`

Self-serve GTM signup without a wallet. Response is always the same JSON (no enumeration). A single-use magic link mints a scoped `411k_…` usage key on redeem via the existing magic-link flow. Every billed call debits virtual USD balance first; wallet x402 only when that balance is exhausted. One-time $5 virtual USD bonus on the first prepay deposit of $10 or more (once per account).
<!-- /411data:email-signup-discovery -->