---
name: 411data
description: Agent-native lead and business-data enrichment (reverse phone, person search, LLM websearch, lead-session, async enrich jobs). Billing waterfall — virtual USD balance first (~$0.20 starting credit on wallet mint at /connect), then 402 + x402 v2 (EIP-3009 USDC on Base mainnet). Async jobs at POST /api/v1/enrich/jobs (virtual precharge or CDP upto). Bazaar discovery at /discovery/resources.
version: 0.1.0
origin: https://411data.io
mcp_endpoint: https://411data.io/mcp
mcp_descriptor: https://411data.io/mcp.json
openapi: https://411data.io/openapi.json
openapi_free: https://411data.io/openapi-free.json
well_known_x402: https://411data.io/.well-known/x402
bazaar_discovery: https://411data.io/discovery/resources
tags: [leads, enrichment, b2b, phone, person, agent, x402, mcp, bazaar]
---

# 411data skill

This file teaches an LLM agent how to use the 411data service end-to-end.

## 0. Scope discipline — READ THIS FIRST

411data enriches **phones, people, and business leads** through reverse phone
lookup, person search, LLM web-search, and agentic lead-session orchestration. Every input and output
is stored for audit.

- **Answer using only the data returned by 411data tools.**
- If a tool returns no match, an error, or a 402 the user has not paid,
  **say so plainly**. Offer to broaden filters, register an agent token,
  settle x402, **prepay USDC** ([`/cookbook/prepay_deposits`](https://411data.io/cookbook/prepay_deposits)).
  **Do not invent contact records to fill gaps.**
- **Bill-on-match:** enrichment routes charge up front, then **auto-refund**
  when no usable match is found (`matched: false`). See
  [`/cookbook/bill_on_match`](https://411data.io/cookbook/bill_on_match).
- **Before tackling a new question shape, scan the cookbook** at
  https://411data.io/cookbook — free worked examples for reverse phone,
  person lookup, websearch vs lead-session, and bill-on-match.
- **Refuse to invent data.** If enrichment returns no match, do not
  guess emails or phone numbers from the web. See
  https://411data.io/cookbook/anti_invent.

## 1. Mint an agent token

Wallet-bound mint (recommended): https://411data.io/connect

- Requires ≥ $1 USDC on Base at mint time (eligibility check only).
- Grants **$0.20 virtual USD** starting balance.
- Optional MPP allowance signature for hands-free x402 after balance hits zero.

Bearer format: `411_…` (admin) or scoped usage key `411k_…` (data routes only).

## 2. Hosted enrich agent (humans)

Interactive chat UI: https://411data.io/enrich_agent (mint bearer at /connect first).

## 3. REST API (automation)

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

# Person lookup (name, address, or reverse phone)
curl -X POST https://411data.io/api/v1/enrich/person \
  -H 'Authorization: Bearer 411_…' \
  -H 'Content-Type: application/json' \
  -d '{"name":"John Smith","state_code":"PA","zipcode":"15213"}'

# Business-name web search
curl -X POST https://411data.io/api/v1/enrich/websearch \
  -H 'Authorization: Bearer 411_…' \
  -H 'Content-Type: application/json' \
  -d '{"business_name":"Acme Corp","city":"Tampa","state":"FL"}'

# Agentic lead-session (multi-tool CRM enrichment)
curl -X POST https://411data.io/api/v1/enrich/lead-session \
  -H 'Authorization: Bearer 411_…' \
  -H 'Content-Type: application/json' \
  -d '{"lead":{"company":"Acme Corp","number1":"4125550100"},"budget_usd":2.0}'

# Async enrich job (deferred billing — websearch or lead-session)
curl -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 with job_id + poll_bearer (411j_…); poll GET /api/v1/enrich/jobs/{job_id}
```

**Async jobs:** Bearer submit pre-charges virtual USD (default ceiling **$1.50** when
`bill_up_to_usd` omitted; override up to **$50**) and refunds unused credit
on completion. Anonymous buyers get CDP `upto` (402 → sign → 202 → poll).
Recipe: [`/cookbook/async_enrich_jobs`](https://411data.io/cookbook/async_enrich_jobs).

Catalog routes (`enrich/email`, `enrich/company`, `leads/search`) are offline
by default. See https://411data.io/pricing for the live catalogue.

## 4. Billing waterfall

1. **Virtual USD balance first** — every paid call debits `virtual_balance_usd`.
2. **402 + x402 only when balance is exhausted** — wallet MPP allowance or fresh USDC settlement on Base.

402 bodies include `billing_reason`, `virtual_balance_usd`, `connect_url`, `topup_url`, and `llm_user_message`.

## 5. Usage keys (admin → scripts)

Admin bearer (`411_…`) can create scoped keys at `/connect?action=usage-keys` or `POST /api/v1/keys`. Keys (`411k_…`) are limited to enrichment + lead routes and enforce per-key spend caps.

## 6. Further reading

- Developer guide: https://411data.io/developers
- Cookbook: https://411data.io/cookbook
- Async enrich jobs: https://411data.io/cookbook/async_enrich_jobs
- Pricing: https://411data.io/pricing
- x402 manifest: https://411data.io/.well-known/x402

<!-- 411data:email-signup-discovery -->
## Email signup (no wallet)

Self-serve path for humans without a Base wallet:

```bash
curl -X POST https://411data.io/api/v1/signup/email \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@company.com"}'
```

Response is always the same whether or not the address is eligible. Open the emailed `?magic=` link to mint a scoped `411k_…` key. SPA: https://411data.io/connect?action=email-signup
<!-- /411data:email-signup-discovery -->