411data developer guide

Reverse phone and person lookup, LLM web research, and multi-tool lead-session enrichment. Billing debits virtual USD first, then 402 + x402 when balance is empty. Enrichment routes use bill-on-match — no charge when matched: false.

Register an agent

Wallet-bound (recommended) — Base wallet with ≥ $1 USDC at mint (balance check only; we never withdraw). Grants $0.20 starting virtual USD. Browser: /connect.

Headless SIWE mint:

curl -sS -X POST https://411data.io/api/v1/agents/wallet-nonce \
  -H 'Content-Type: application/json' \
  -d '{"address":"0xYOURWALLET","allowance_usd":"10"}'
# Sign siwe_message (+ optional allowance_intent_message), then POST /api/v1/agents/wallet-register

The bearer (411_…) is returned once on first mint per wallet. Save it. Rotate with POST /api/v1/agents/token/rotate while you still have the current token. If the bearer is lost everywhere but you still control the mint wallet, use wallet recovery at /connect?action=recover (POST /api/v1/agents/wallet-recover/challenge → send $1 USDC on Base → POST /api/v1/agents/wallet-recover/complete with a lead-history answer). Same agent_id; requires enrich/search history in the last 90 days.

curl https://411data.io/api/v1/agents/me \
  -H 'Authorization: Bearer 411_…'

Anonymous calls to paid routes → 402 AGENT_TOKEN_REQUIRED. Mint at /connect.

Usage keys — Admin bearers create scoped 411k_… keys for scripts and teammate chat. Manage at /connect?action=usage-keys. Details: /cookbook/usage_keys.

Billing

1. Virtual USD balance — every paid call debits credit first (~$0.20 at wallet mint).
2. 402 + x402 — only when balance cannot cover the route price. Settle on-chain, retry with PAYMENT-SIGNATURE.

Bill-on-match: enrichment refunds when matched: false (empty or unusable rows).

Top up: /cookbook/prepay_deposits. Deposit match promo (when enabled): /promo and /cookbook/deposit_match_promo. Live prices: /pricing and /.well-known/x402.

Enrichment endpoints

All paid routes require Authorization: Bearer 411_… (or 411k_…).

Phone — reverse lookup — $0.330

Whitepages person search on the number. Returns data.people (names, phones, emails, addresses).

curl -X POST https://411data.io/api/v1/enrich/phone \
  -H 'Authorization: Bearer 411_…' \
  -H 'Content-Type: application/json' \
  -d '{"phone":"+17242060094"}'

Example match: James W Cole Sr (+ 4 related people on the same number). metadata.query_mode is reverse_phone.

Person — name, phone, or address — $0.500

Same Whitepages backend as phone-only lookup. Pass whichever fields you have.

curl -X POST https://411data.io/api/v1/enrich/person \
  -H 'Authorization: Bearer 411_…' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Joseph B Manno","state_code":"PA","city":"Ridgway"}'

Or reverse phone: {"phone":"+17242060094"}.

Websearch — public business research — $1.000

LLM + web search when you have a business name and optional location hints. Required: business_name. Optional: city, state, domain, prompt.

Fields are intentionally loose — send whatever location columns you have; omit the rest. Only business_name is required.

curl -X POST https://411data.io/api/v1/enrich/websearch \
  -H 'Authorization: Bearer 411_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "business_name": "Finicky Window Cleaning, Inc.",
    "city": "Dunedin",
    "state": "FL"
  }'

Returns phones, people (name + title), addresses, and legal_associates when found. Recipe: /cookbook/enrich_websearch_when.

Long sessions may bill above the listed price when research runs extra vendor hops; see /pricing for the current default.

For long-running work without holding the HTTP connection, use POST /api/v1/enrich/jobs with route: enrich/websearch.

Lead-session — agentic enrichment — $1.500

Multi-tool session (person hunt, websearch, synthesis). lead is free-form — paste a CRM row with whatever column names your export uses. Common keys the orchestrator understands include contact_id, company, business_name, number1, street, city, state, zip, email, mailing_address, and dm_name. Extra columns are ignored; missing columns are fine.

curl -X POST https://411data.io/api/v1/enrich/lead-session \
  -H 'Authorization: Bearer 411_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "lead": {
      "contact_id": 81551343,
      "company": "JOSEPH B MANNO",
      "street": "5 TANNERY RD",
      "city": "RIDGWAY",
      "state": "PA",
      "zip": "15853",
      "number1": "8147761310"
    },
    "budget_usd": 2.0,
    "max_rounds": 5,
    "mode": "auto"
  }'

Optional session knobs (defaults shown above):

• budget_usd (default 2.0, max 20.0 per call) — hard cap on vendor tool spend inside one lead-session invocation. The enrich-agent session header budget can be raised up to $50 per chat; the agent passes min(remaining, 20) on each hunt. inside this session (websearch, person hunt, company, etc.).

mode

• auto — Runs end-to-end without pausing for you. It runs enrichment tools in sequence (websearch → person hunt → company, etc.), stops when coverage is good enough, budget is hit, or there’s nothing left to try.
• interactive — Same orchestration, but if there are marginal gaps left (nice-to-have phones, owners, etc.) and budget is tight, it can pause with status: "awaiting_user" and suggested follow-up prompts instead of stopping silently.

For API/MCP calls, auto is what you almost always want — one shot, full answer back. Use interactive only if you’re building a UI that can show dig_deeper / suggested_user_prompts and let the user send a follow-up.

max_rounds — 5 (default, range 1–10)

A safety cap on orchestration steps, not “LLM chat turns.” Each time a paid enrichment tool runs and its result is merged (enrich_websearch, whitepages_person_hunt, enrich_company, etc.), the round counter goes up by 1. The main loop stops when either:

• rounds >= max_rounds, or
• spent_usd >= budget_usd, or
• coverage says “done.”

So 5 means “run at most about five tool hops in this session.” That’s enough for the usual path (websearch + person hunt + company + phase-2 supplements) without letting a thin CRM record spin forever.

Typical tuning: leave defaults for normal enrichment; raise max_rounds (up to 10) only if you’re doing deep multi-hop research and have budget headroom.

Re-run with the same lead plus prompts for dig-deeper follow-ups.

Response includes a lead_enrichment_v1 backfill graph (phones, contacts, entities, summary_markdown). Sessions may cost more than the listed default when additional tools run; cap spend with budget_usd.

Sync lead-session calls often run 30–180 s. For fire-and-poll, use POST /api/v1/enrich/jobs with route: enrich/lead-session (async jobs can pass higher in-payload budget_usd up to the job’s bill_up_to_usd ceiling).

Async jobs — deferred billing

Queue enrich/websearch or enrich/lead-session without holding the HTTP connection open. Submit returns 202; poll with a scoped poll_bearer (411j_…). Full recipe: /cookbook/async_enrich_jobs.

Spending ceiling (bill_up_to_usd): defaults to $1.50 when omitted; client may override up to $50. Actual settle ≤ ceiling; unused precharge refunded.

Submit (virtual balance):

curl -sS -X POST https://411data.io/api/v1/enrich/jobs \
  -H 'Authorization: Bearer 411_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "route": "enrich/websearch",
    "payload": {
      "business_name": "Acme Corp",
      "city": "Tampa",
      "state": "FL"
    },
    "bill_up_to_usd": 1.5
  }'

202 response (abbreviated): job_id, poll_bearer, poll_interval_sec, billing_mode (virtual_balance or x402_upto), bill_up_to_usd.

Poll (free):

curl -sS https://411data.io/api/v1/enrich/jobs/ej_… \
  -H 'Authorization: Bearer 411j_…'

Poll until status is completed or failed. result mirrors the sync route JSON.

Lead-session via queue — same submit path with "route": "enrich/lead-session" and payload containing the same lead, budget_usd, max_rounds, and mode fields as the sync endpoint.

Anonymous / CDP upto: omit bearer on submit → 402 scheme: upto → sign Permit2 → retry with PAYMENT-SIGNATURE → 202 → poll. Settles on-chain after the job completes ($0 on no-match).

Optional callback_url fires enrich.job_completed when done. Listed in Bazaar at GET /discovery/resources (upto resource, separate from sync routes).

Support — $0.010

curl -X POST https://411data.io/api/v1/support/tickets \
  -H 'Authorization: Bearer 411_…' \
  -H 'Content-Type: application/json' \
  -d '{"category":"bug","subject":"Short title","body":"Repro steps…"}'

category: bug | billing | account | other. Bug reports earn a $1.00 virtual USD credit after operator confirmation.

Catalog routes (offline)

enrich/email, enrich/company, and leads/search return 503 until catalog vendors are re-enabled.

x402

When virtual balance is exhausted, the API returns 402 with an x402 v2 accepts[] envelope. Sign EIP-3009 TransferWithAuthorization, retry with PAYMENT-SIGNATURE.

curl -i -X POST https://411data.io/api/v1/enrich/phone \
  -H 'Authorization: Bearer 411_…' \
  -H 'Content-Type: application/json' \
  -d '{"phone":"+17242060094"}'

Bazaar discovery: GET /discovery/resources (no auth).

Prices (defaults)

Integrations

• Event callbacks — /connect?action=event-callbacks, catalog GET /api/v1/event-callbacks/catalog
• Billing export / webhooks — /connect?action=billing
• MCP — /mcp.json

Links

• /skill.md · /cookbook · /pricing · /openapi.json