{"openapi":"3.1.0","info":{"title":"411data","version":"0.1.0","description":"Agent-native lead enrichment: email, company, phone, websearch, lead search. x402 + MCP + free trial.","contact":{"name":"411data","url":"https://411data.io/about"},"x-guidance":"411data is an **agent-native** lead and data enrichment API. Paid endpoints\nreturn single-record enrichment or paged lead lists via a vendor waterfall;\n**bill-on-match** auto-credits when no row is found.\n\n**Workflow**\n1. Mint a wallet-bound agent at `/connect` ($0.20 starting virtual USD\n   balance + multi-wallet MPP support) or headless via\n   `POST /api/v1/agents/wallet-register` after SIWE.\n2. Call enrichment routes (debited from virtual balance first):\n   - `$0.050` `POST /api/v1/enrich/email`, `/enrich/company`, `/enrich/phone`\n   - `$0.150` `POST /api/v1/enrich/websearch` (LLM + web search)\n   - `$0.100` `POST /api/v1/leads/search` (filtered lead list; page via `cursor`)\n3. Pre-flight with free cookbook: `GET /cookbook/search?q=…` then\n   `GET /cookbook/read/{slug}` for worked recipes.\n\n**Free surface:** `GET /openapi-free.json` documents mint + cookbook.\nPaid catalogue: `GET /openapi.json`.\n\n**Payment:** Every billed call FIRST debits your agent's virtual USD\nbalance; the x402 v2 challenge only fires after the balance is exhausted.\nThe server runs the official `x402[fastapi,evm]` Python SDK — envelopes\nfollow the canonical v2 spec (base64 `payment-required:` header carrying\n`accepts[]` with CAIP-2 networks like `eip155:8453` and atomic-units\n`amount` strings like `\"10000\"` for $0.010 USDC, plus\n`extensions.411data-mpp` and `extensions.bazaar` for wallet allowance +\nJSON Schemas). Settle by signing an EIP-3009 `TransferWithAuthorization`\nto the listed `payTo` and retrying with `X-PAYMENT: <base64>`. After-settle\nreceipts arrive in the `payment-response: <base64>` header. Catalogue:\n`GET /.well-known/x402`. Bazaar-style discovery for facilitator indexers:\n`GET /discovery/resources`.\n","x-411data-free-openapi":"https://411data.io/openapi-free.json","x-rate-limits":{"policy":"edge-only","layers":[{"id":"cloudflare","type":"zone-burst"},{"id":"nginx","type":"limit_req"}],"retry_header":"Retry-After","in_app_quota":"none — virtual USD balance is the spend control","docs":"https://411data.io/developers#rate-limits"},"x-llm-recipes":[{"id":"enrich_email","goal":"Enrich a single email address into person + company fields.","steps":["Optional: GET /cookbook/search?q=enrich email for recipe hints.","POST /api/v1/enrich/email with {\"email\": \"jane@example.com\"}.","If `match == false` or rows empty, the call is auto-credited (bill-on-match)."],"cost_usd":"$0.050 per call (debited from virtual balance first)."},{"id":"enrich_company","goal":"Enrich a company by name and/or domain.","steps":["POST /api/v1/enrich/company with {\"company\": \"Acme Corp\", \"domain\": \"acme.com\"}.","Use domain when known — improves vendor hit rate."],"cost_usd":"$0.050 per call."},{"id":"enrich_phone","goal":"Reverse-lookup enrichment from a phone number.","steps":["POST /api/v1/enrich/phone with {\"phone\": \"+14155551212\"} (E.164 preferred)."],"cost_usd":"$0.050 per call."},{"id":"enrich_websearch","goal":"Find public phones, people, and addresses for a business via LLM web search.","steps":["POST /api/v1/enrich/websearch with {\"business_name\": \"Acme Corp\", \"city\": \"Tampa\", \"state\": \"FL\"}.","Higher latency and cost than structured enrich routes — use when name-only lookup is required."],"cost_usd":"$0.150 per call."},{"id":"leads_search","goal":"Paged B2B lead list by industry/geo/title filters.","steps":["POST /api/v1/leads/search with filters (e.g. {\"industry\": \"software\", \"state\": \"FL\", \"limit\": 25}).","Page via `page.cursor` until `page.has_more == false`. Empty pages auto-credit."],"cost_usd":"$0.100 per page."},{"id":"402_settle_loop","goal":"What to do when a paid call returns 402.","steps":["Read `billing_reason`, `detail`, `virtual_balance_usd`, `wallet_usdc_balance_usd`, `connect_url`, and `topup_url` (or `deposit_url` / `prepay_page_url`) on every 402 — explain them to the user.","If `code == AGENT_TOKEN_REQUIRED`, mint at `connect_url` (/connect) first.","If `code == PAYMENT_REQUIRED`, GET /api/v1/agents/balance — if balance ≥ price, retry the same call (server will debit balance, no signature required).","If balance < price: show the user `topup_url` as a clickable link (prepay wizard: connect wallet → amount → sign USDC on Base). Prefer that over raw deposit/claim unless the user is headless. Manual path: /cookbook/prepay_deposits. Sender wallet must be linked via /wallet-link first.","If balance < price, read `earn_credits_via_session_summary` on the 402 body: POST /api/v1/contributions/session-summary/preview, show the user `display`, then submit with `preview_token` after confirm ($0.05–$0.30 per accepted summary; /cookbook/session_feedback).","Alternatively sign an EIP-3009 TransferWithAuthorization to the `accepts[].payTo` for the listed `maxAmountRequired` and retry with `PAYMENT-SIGNATURE: <base64>`.","After 2xx, look for `payment-response: <base64>` (the on-chain settlement receipt)."],"cost_usd":"Per the route's x-payment-info.price."}]},"externalDocs":{"url":"https://411data.io/developers","description":"Developer guide — mint, billing waterfall, bill-on-match, x402 settle loop."},"servers":[{"url":"https://411data.io"}],"components":{"schemas":{"ProductError":{"type":"object","properties":{"code":{"type":"string","enum":["AGENT_TOKEN_REQUIRED","PAYMENT_REQUIRED","ROUTE_NOT_FOUND","AGENT_SUSPENDED","FORBIDDEN","RATE_LIMIT","BURST_RATE_EXCEEDED","VALIDATION_ERROR"]},"error":{"type":"string"},"detail":{"type":"string"},"route":{"type":"string"},"retryable":{"type":"boolean"},"suggested_action":{"type":"string","enum":["mint_agent","settle_x402_and_retry_with_x_payment","fix_request","wait_and_retry"]},"mint":{"$ref":"#/components/schemas/ProductErrorMint"},"discover":{"$ref":"#/components/schemas/ProductErrorDiscover"}}},"ProductErrorMint":{"type":"object","description":"Mint hints attached to AGENT_TOKEN_REQUIRED 401/402 responses.","properties":{"wallet_url":{"type":"string","format":"uri","description":"Wallet-bound mint flow (`/connect`)."},"register_url":{"type":"string","format":"uri","description":"Wallet-register endpoint (`POST /api/v1/agents/wallet-register`)."},"starting_balance_usd_wallet":{"type":["string","number"],"description":"Virtual USD credit granted on wallet mint."},"starting_balance_usd_google":{"type":["string","number"],"description":"Deprecated; use starting_balance_usd_wallet."},"docs":{"type":"string","format":"uri"}}},"ProductErrorDiscover":{"type":"object","description":"Discovery pointers attached to ROUTE_NOT_FOUND 404s.","properties":{"openapi":{"type":"string","format":"uri"},"openapi_free":{"type":"string","format":"uri"},"wellknown_x402":{"type":"string","format":"uri"},"agent_card":{"type":"string","format":"uri"},"discovery_resources":{"type":"string","format":"uri"},"pricing":{"type":"string","format":"uri"}}},"PaymentRequired402":{"type":"object","description":"x402 v2 payment-required envelope. Also delivered base64-encoded in the `payment-required:` response header.","properties":{"x402Version":{"type":"integer","const":2},"error":{"type":"string"},"code":{"type":"string","enum":["PAYMENT_REQUIRED","AGENT_TOKEN_REQUIRED"]},"detail":{"type":"string"},"accepts":{"type":"array","items":{"$ref":"#/components/schemas/X402Accept"}},"extensions":{"type":"object","description":"Per-extension info blocks. `411data-mpp` carries per-wallet allowance pool snapshot; `bazaar` carries indexer-friendly service metadata."},"mint":{"$ref":"#/components/schemas/ProductErrorMint"},"route":{"type":"string"},"retryable":{"type":"boolean"},"suggested_action":{"type":"string"},"billing_reason":{"type":"string","description":"Why billing blocked the call (e.g. agent_token_required, virtual_balance_insufficient, burst_rate_exceeded)."},"connect_url":{"type":"string","format":"uri","description":"Fund wallet or mint an agent at https://411data.io/connect."},"topup_url":{"type":"string","format":"uri","description":"Prepay wizard when virtual balance is insufficient — /connect?action=topup."},"deposit_url":{"type":"string","format":"uri","description":"Alias for topup_url — USDC prepay to refill virtual balance."},"prepay_page_url":{"type":"string","format":"uri","description":"Alias for topup_url — show this link to the user in chat."},"llm_user_message":{"type":"string","description":"Plain-text instruction for the LLM to relay to the user (includes prepay URL when enabled)."},"virtual_balance_usd":{"type":"number","description":"Agent virtual USD balance when `code == \"PAYMENT_REQUIRED\"`."},"wallet_usdc_balance_usd":{"type":"number","description":"On-chain USDC on Base for the agent's primary linked wallet (best effort)."},"alternative_actions":{"type":"array","items":{"type":"string"},"description":"Other recovery paths, e.g. `earn_session_feedback_credits`."},"earn_credits_via_session_summary":{"type":"object","description":"How to earn virtual USD by submitting a PII-free session summary (preview → user confirm → submit).","properties":{"summary":{"type":"string"},"enabled":{"type":"boolean"},"preview":{"type":"object"},"submit":{"type":"object"},"cookbook":{"type":"string","format":"uri"},"credit_tiers_usd":{"type":"object"},"daily_submit_cap":{"type":"integer"},"daily_credit_cap_usd":{"type":"number"},"steps_for_llm":{"type":"array","items":{"type":"string"}}}}},"required":["x402Version","accepts"]},"X402Accept":{"type":"object","properties":{"scheme":{"type":"string","enum":["exact","upto"]},"network":{"type":"string","description":"CAIP-2 network id (e.g. `eip155:8453` for Base mainnet)."},"maxAmountRequired":{"type":"string","description":"Atomic-units price (USDC has 6 decimals — `\"10000\"` = $0.010)."},"payTo":{"type":"string","description":"Recipient address."},"asset":{"type":"string","description":"Token contract address."},"extra":{"$ref":"#/components/schemas/X402AcceptExtra"}},"required":["scheme","network","maxAmountRequired","payTo","asset"]},"X402AcceptExtra":{"type":"object","description":"Scheme/facilitator-specific metadata. Stable keys below; additional keys allowed.","properties":{"name":{"type":"string","description":"EIP-712 domain name (e.g. `USD Coin`)."},"version":{"type":"string","description":"EIP-712 domain version (e.g. `2` on Base mainnet USDC)."},"facilitatorId":{"type":"string","description":"Stable id (`xpay`, `cdp`, `payai`, `dexter`) — buyer's choice in `accepts[]` selects which facilitator settles."},"facilitator":{"type":"string","format":"uri","description":"Facilitator HTTPS endpoint."},"assetTransferMethod":{"type":"string","enum":["eip3009","permit2"],"description":"On-chain transfer scheme."}},"additionalProperties":true}},"responses":{"BadRequest":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"Forbidden":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"NotFound":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"RateLimited":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"ValidationError":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}}},"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Agent token minted at /connect (wallet-bound; see /developers for headless SIWE flow), presented as ``Authorization: Bearer <token>``. Paid routes accept the token; when the agent's virtual USD balance is exhausted they return 402 with an x402 v2 challenge."}}},"paths":{"/api/v1/enrich/email":{"post":{"summary":"411data Enrich Email","description":"Single-record email enrichment via reseller waterfall.","operationId":"411dataEnrichEmail","tags":["enrichment","email","lead"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}},{"mpp":{"method":"x402-paired-allowance","intent":"deferred-debit","currency":"USD"}}]},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"endpoint":{"type":"string","description":"Logical route key, e.g. enrich/email."},"input":{"type":"object","description":"Normalized request input echoed back."},"matched":{"type":"boolean","description":"True when a usable vendor/LLM result was found."},"data":{"type":["object","null"],"description":"Vendor-specific payload when matched."},"vendor":{"type":["string","null"],"description":"Winning vendor key when matched."},"cache_hit":{"type":"boolean","description":"True when served from request_response_store."},"billed":{"type":"boolean","description":"False when bill-on-match refunded a no-match call."}},"required":["endpoint","input","matched","billed"]},"example":{"endpoint":"enrich/email","input":{"email":"jane@acme.com"},"matched":true,"data":{"company":"Acme Corp","title":"VP Sales","name":"Jane Doe"},"vendor":"stub","cache_hit":false,"billed":true}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"402":{"description":"Payment required (x402 challenge).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402"}}}}},"x-agent-hints":{"use_when":["Identify person + company from a work or personal email"],"avoid_when":["You only have a company domain — use enrich_company","Local business with no email — try enrich_websearch"],"cost_class":"medium","latency_class":"medium","usage_tips":["Bill-on-match: charge is refunded when matched=false (enrichment) or zero rows (leads).","Always report matched and billed to the user — do not invent contact fields when matched=false.","See /cookbook/bill_on_match.","Vendor waterfall tries resellers in order until one matches.","Recipe: /cookbook/enrich_email_waterfall."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"}},"required":["email"]},"example":{"email":"jane@example.com"}}}}}},"/api/v1/enrich/company":{"post":{"summary":"411data Enrich Company","description":"Single-record company enrichment via reseller waterfall.","operationId":"411dataEnrichCompany","tags":["enrichment","company","lead"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}},{"mpp":{"method":"x402-paired-allowance","intent":"deferred-debit","currency":"USD"}}]},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"endpoint":{"type":"string","description":"Logical route key, e.g. enrich/email."},"input":{"type":"object","description":"Normalized request input echoed back."},"matched":{"type":"boolean","description":"True when a usable vendor/LLM result was found."},"data":{"type":["object","null"],"description":"Vendor-specific payload when matched."},"vendor":{"type":["string","null"],"description":"Winning vendor key when matched."},"cache_hit":{"type":"boolean","description":"True when served from request_response_store."},"billed":{"type":"boolean","description":"False when bill-on-match refunded a no-match call."}},"required":["endpoint","input","matched","billed"]},"example":{"endpoint":"enrich/company","input":{"company":"Acme Corp","domain":"acme.com"},"matched":true,"data":{"name":"Acme Corp","domain":"acme.com","industry":"Software","employee_range":"51-200"},"vendor":"stub","cache_hit":false,"billed":true}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"402":{"description":"Payment required (x402 challenge).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402"}}}}},"x-agent-hints":{"use_when":["Firmographics from company name and/or domain"],"avoid_when":["You have a person's email — use enrich_email first"],"cost_class":"medium","latency_class":"medium","usage_tips":["Bill-on-match: charge is refunded when matched=false (enrichment) or zero rows (leads).","Always report matched and billed to the user — do not invent contact fields when matched=false.","See /cookbook/bill_on_match.","At least one of company or domain is required.","Recipe: /cookbook/enrich_company_domain."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company":{"type":"string","maxLength":200},"domain":{"type":"string","maxLength":255}}},"example":{"company":"Acme Corp","domain":"acme.com"}}}}}},"/api/v1/enrich/phone":{"post":{"summary":"411data Enrich Phone","description":"Single-record phone enrichment via reseller waterfall.","operationId":"411dataEnrichPhone","tags":["enrichment","phone","lead"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}},{"mpp":{"method":"x402-paired-allowance","intent":"deferred-debit","currency":"USD"}}]},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"endpoint":{"type":"string","description":"Logical route key, e.g. enrich/email."},"input":{"type":"object","description":"Normalized request input echoed back."},"matched":{"type":"boolean","description":"True when a usable vendor/LLM result was found."},"data":{"type":["object","null"],"description":"Vendor-specific payload when matched."},"vendor":{"type":["string","null"],"description":"Winning vendor key when matched."},"cache_hit":{"type":"boolean","description":"True when served from request_response_store."},"billed":{"type":"boolean","description":"False when bill-on-match refunded a no-match call."}},"required":["endpoint","input","matched","billed"]},"example":{"endpoint":"enrich/phone","input":{"phone":"+14155551212"},"matched":true,"data":{"name":"Jane Doe","company":"Acme Corp"},"vendor":"stub","cache_hit":false,"billed":true}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"402":{"description":"Payment required (x402 challenge).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402"}}}}},"x-agent-hints":{"use_when":["Reverse lookup: phone → person/company association"],"avoid_when":["You have email or domain already — cheaper paths exist"],"cost_class":"medium","latency_class":"medium","usage_tips":["Bill-on-match: charge is refunded when matched=false (enrichment) or zero rows (leads).","Always report matched and billed to the user — do not invent contact fields when matched=false.","See /cookbook/bill_on_match.","E.164 preferred; API normalizes common formats."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phone":{"type":"string","minLength":5,"maxLength":40}},"required":["phone"]},"example":{"phone":"+14155551212"}}}}}},"/api/v1/enrich/websearch":{"post":{"summary":"411data Enrich Websearch","description":"Custom LLM + web search for business contact data.","operationId":"411dataEnrichWebsearch","tags":["enrichment","websearch","llm","lead"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.150000"},"protocols":[{"x402":{}},{"mpp":{"method":"x402-paired-allowance","intent":"deferred-debit","currency":"USD"}}]},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"endpoint":{"type":"string","description":"Logical route key, e.g. enrich/email."},"input":{"type":"object","description":"Normalized request input echoed back."},"matched":{"type":"boolean","description":"True when a usable vendor/LLM result was found."},"data":{"type":["object","null"],"description":"Vendor-specific payload when matched."},"vendor":{"type":["string","null"],"description":"Winning vendor key when matched."},"cache_hit":{"type":"boolean","description":"True when served from request_response_store."},"billed":{"type":"boolean","description":"False when bill-on-match refunded a no-match call."}},"required":["endpoint","input","matched","billed"]},"example":{"endpoint":"enrich/websearch","input":{"business_name":"Acme Corp","city":"Tampa","state":"FL"},"matched":true,"data":{"phones":["+18135550100"],"people":[{"name":"Jane Doe","title":"Owner"}]},"vendor":"llm_websearch","cache_hit":false,"billed":true}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"402":{"description":"Payment required (x402 challenge).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402"}}}}},"x-agent-hints":{"use_when":["Public phones/people/addresses for a named local business when vendors lack coverage"],"avoid_when":["Waterfall enrich_company or enrich_email would suffice"],"cost_class":"high","latency_class":"slow","usage_tips":["Bill-on-match: charge is refunded when matched=false (enrichment) or zero rows (leads).","Always report matched and billed to the user — do not invent contact fields when matched=false.","See /cookbook/bill_on_match.","Higher price — use only after waterfall misses.","Recipe: /cookbook/enrich_websearch_when."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"business_name":{"type":"string","minLength":2,"maxLength":200},"city":{"type":"string","maxLength":120},"state":{"type":"string","maxLength":120},"domain":{"type":"string","maxLength":255}},"required":["business_name"]},"example":{"business_name":"Acme Corp","city":"Tampa","state":"FL"}}}}}},"/api/v1/leads/search":{"post":{"summary":"411data Lead Search","description":"Paged lead list by industry/geo/title filters.","operationId":"411dataLeadSearch","tags":["leads","search","b2b"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.100000"},"protocols":[{"x402":{}},{"mpp":{"method":"x402-paired-allowance","intent":"deferred-debit","currency":"USD"}}]},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object"}},"cursor":{"type":["string","null"]},"matched":{"type":"boolean"},"billed":{"type":"boolean"}},"required":["rows","matched","billed"]},"example":{"rows":[{"company":"Acme Corp","title":"CTO","state":"FL"}],"cursor":null,"matched":true,"billed":true}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"402":{"description":"Payment required (x402 challenge).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402"}}}}},"x-agent-hints":{"use_when":["Paged B2B lead list by industry, geo, title, or company size"],"avoid_when":["Single-record lookup — use enrich_* instead"],"cost_class":"medium","latency_class":"medium","usage_tips":["Bill-on-match: charge is refunded when matched=false (enrichment) or zero rows (leads).","Always report matched and billed to the user — do not invent contact fields when matched=false.","See /cookbook/bill_on_match.","Pin filters before paying — see /cookbook/leads_search_filters.","Pagination via cursor; zero rows triggers refund."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"industry":{"type":"string","maxLength":120},"city":{"type":"string","maxLength":120},"state":{"type":"string","maxLength":120},"title":{"type":"string","maxLength":120},"company_size":{"type":"string","maxLength":40},"limit":{"type":"integer","minimum":1,"maximum":100},"cursor":{"type":"string","maxLength":400}}},"example":{"industry":"software","state":"FL","limit":25}}}}}}}}