B2BDatabase
Instant key · no sales call

API & MCP

Everything the app can do, your code and your AI agents can do too. Faceted search is free; you spend a credit only when you reveal a real contact — and invalid emails are refunded automatically. Same credit balance, same suppression and verification guarantees as the UI.

Endpoints
GET/v1/search0POST/v1/reveal1 / new contactGET/v1/lookup1 hit / 0 missPOST/v1/enrich1 / matchGET/v1/usage0POST/v1/suppression0

Authentication

Mint a key from your dashboard (or POST /api/keys while signed in). The key is shown once — store it securely. Keys look like b2db_live_… and are hashed at rest. Send it as a Bearer token on every /v1 request:

Authorization header
Authorization: Bearer b2db_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The base URL is https://b2bdatabase.net. Every response includes an X-Request-Id (and a request_id field) for support, plus X-RateLimit-Limit / -Remaining / -Reset headers. Errors use a typed envelope:

Error shape
{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to complete this request.",
    "docs_url": "https://b2bdatabase.net/api-docs",
    "request_id": "req_8f1c2a9b4d7e6f01",
    "needed": 12,
    "available": 5
  }
}

Rate limit: 120 requests / minute per key by default (search is cheap; credits are the real cap). A 429 returns a Retry-After header.

Create an API key

Session-authenticated (uses your login cookie), not key-authenticated:

POST /api/keys
curl -X POST https://b2bdatabase.net/api/keys \
  -H "Content-Type: application/json" \
  --cookie "auth_session=<your session cookie>" \
  -d '{"name":"production server"}'

# → { "id":"key-…", "token":"b2db_live_…", "prefix":"b2db_live_1a2b3c4d",
#     "message":"Save this key now — it will not be shown again." }

Reference

POST/v1/revealcost: 1 / new contact credit(s)

Reveal unmasked contact details for ids from /v1/search. 1 credit per new contact; re-revealing one you already own is free (idempotent). Suppressed or missing ids are never charged or returned, and any invalid-verdict email is auto-refunded — the guarantee. Up to 1000 ids per call.

curl
curl -X POST "https://b2bdatabase.net/v1/reveal" \
  -H "Authorization: Bearer $B2BDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lead_ids":["ld_001","ld_002","ld_003"]}'

# → { "leads":[{ "id":"ld_001","email":"jane@acme.com","email_status":"valid", … }],
#     "charged":2,"refunded":1,"free_reowned":0,"balance":97,
#     "verdict_mix":{"valid":2,"catch_all":0,"risky":0,"invalid":1,"unknown":0},
#     "request_id":"req_…" }
GET/v1/lookupcost: 1 hit / 0 miss credit(s)

Reverse-resolve a single email to its full contact record. You're charged 1 credit only on a hit (0 on a miss, 0 if you already own the contact). Suppressed records return a miss. Invalid verdicts auto-refund.

curl
curl -G "https://b2bdatabase.net/v1/lookup" \
  -H "Authorization: Bearer $B2BDB_API_KEY" \
  --data-urlencode "email=jane@acme.com"

# → { "found":true, "lead":{ "id":"ld_001","full_name":"Jane Doe",
#       "email":"jane@acme.com","email_status":"valid", … },
#     "charged":1,"refunded":0,"free_reowned":false,"balance":96,"request_id":"req_…" }
POST/v1/enrichcost: 1 / match credit(s)

Bulk-enrich up to 1000 identity rows. 1 credit per matched contact (unmatched rows and already-owned contacts cost 0; invalids refund). Each row may give an email (exact match) or a name + company_name / company_domain. Provide an optional ref per row and it's echoed back so you can map results to inputs. If you run out of credits mid-batch the call returns what was enriched with truncated: true.

curl
curl -X POST "https://b2bdatabase.net/v1/enrich" \
  -H "Authorization: Bearer $B2BDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows":[
      {"ref":"row-1","email":"jane@acme.com"},
      {"ref":"row-2","full_name":"John Smith","company_domain":"globex.com"}
    ]
  }'

# → { "results":[
#       {"ref":"row-1","matched":true,"lead":{…},"charged":1,"refunded":0},
#       {"ref":"row-2","matched":false,"lead":null,"charged":0,"refunded":0}],
#     "matched":1,"charged":1,"refunded":0,"balance":95,
#     "total_rows":2,"truncated":false,"request_id":"req_…" }
GET/v1/usagecost: 0 credit(s)

Your current credit balance plus this key's usage rollup. Optional ?days=N (default 30, max 365).

curl
curl -G "https://b2bdatabase.net/v1/usage" \
  -H "Authorization: Bearer $B2BDB_API_KEY" \
  --data-urlencode "days=30"

# → { "balance":95,
#     "usage":{ "total":42,
#       "by_endpoint":[{"endpoint":"search","count":30},{"endpoint":"reveal","count":12}],
#       "by_day":[{"day":"2026-06-30","count":42}], "since":"2026-05-31" },
#     "rate_limit":{"limit":120,"remaining":118,"reset":1751299200},"request_id":"req_…" }
POST/v1/suppressioncost: 0 credit(s)

Programmatic opt-out / Do-Not-Sell push for partner integrations. Adds emails to the permanent suppression list; any matching record is then never served anywhere (search/reveal/lookup/enrich). Idempotent. Accepts a single email or up to 1000 emails[]; reason defaults to partner.

curl
curl -X POST "https://b2bdatabase.net/v1/suppression" \
  -H "Authorization: Bearer $B2BDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":["optout@example.com","other@example.com"],"reason":"partner"}'

# → { "suppressed":2, "reason":"partner", "request_id":"req_…" }
Agent-native

MCP server

The Model Context Protocol server exposes search_leads, reveal_contact, and verify_email as tools any MCP client (Claude Desktop, Cursor, Clay, AI-SDR agents) can call. It talks to the same /v1 API with your key, so credits, suppression, and the verification guarantee apply identically.

Add it to your MCP client config (e.g. Claude Desktop's claude_desktop_config.json):

MCP client config
{
  "mcpServers": {
    "b2bdatabase": {
      "command": "npx",
      "args": ["-y", "@b2bdatabase/mcp"],
      "env": {
        "B2BDB_API_KEY": "b2db_live_…",
        "B2BDB_BASE_URL": "https://b2bdatabase.net"
      }
    }
  }
}

Then ask your agent: "Find VPs of Sales at US SaaS companies and reveal the three freshest verified emails." The agent calls search_leads then reveal_contact — spending credits only on the reveal.

Machine-readable spec

The full OpenAPI 3.1 description lives at /openapi.json — import it into Postman, generate a client, or point an agent at it.