BetterContact

HOW in lib/bettercontact.py. Docs cached at reference/docs/bettercontact/raw/.

Auth & config

• Base URL: https://app.bettercontact.rocks/api/v2 · Auth: header X-API-Key (env BETTERCONTACT_API_KEY; never hardcode).

Async flow

1. start_enrichment(data=[{first_name,last_name,company,company_domain,linkedin_url,...}], enrich_email_address=True, enrich_phone_number=False, webhook=None) → POST /async → returns {id}. Max 100 leads/request.
2. get_enrichment(request_id) → GET /async/{request_id} — poll until terminal (or use webhook).

Guardrails

• enrich_phone_number=True raises the charge from 0.5 to 4.8 credits (billed once, on retrieval, when the result carries data) — default off, enable only when a phone number is actually needed. Pilot a small batch first.

Handoff

Waterfall enrichment layer (multi-provider email/phone). Take a shortlist → BetterContact → validate (Enrichley/email-validation) → ATS/sequencer. Runs in the phone_enrichment chain; a phone-only request (enrich_email_address: false, enrich_phone_number: true) is how that waterfall calls it and bypasses the work-email-only channel guard.

Field notes (production experience)

Field-shape note: these are vendor-native operational notes. The client returns the raw vendor JSON and uses the method names in this file — read field shapes accordingly (no normalized-wrapper / result.data. prefix).

• Async: start_enrichment returns a request id immediately -> fetch terminal data via get_enrichment(request_id).
• Email status hierarchy: deliverable > catch_all_safe > catch_all_not_safe > undeliverable - only trust deliverable and catch_all_safe for outreach.
• Batch up to 100 contacts per request.
• Pricing: 0.5 credits for an email reveal, 4.8 for a phone reveal (email included), charged once when the retrieved result carries data -> only set enrich_phone_number: true when explicitly needed. get_enrichment returns credits_consumed.
• Rate limit: 60 req/min per key (shared across endpoints).
• Use it for: multi-provider waterfall email/phone when single-provider finders (LeadMagic/Prospeo) miss. Not for validation-only or company enrichment.

Callable surface — lib/bettercontact.py

Import: from lib.bettercontact import BetterContact → instantiate BetterContact() (reads key from env). Base: https://app.bettercontact.rocks/api/v2. Generic passthrough: request(method, path, *, params, json).

• get_account() -> dict — GET /account — account info + remaining credits: {success, credits_left, email} on the caller's own BetterContact account; requires the workspace's own key.
• get_enrichment(request_id: str) -> dict — GET /async/{request_id} — poll the enrichment result.
• ping() -> dict — BYOK key-verification probe — GET /account (free, no job started).
• start_enrichment(data: list[dict], *, enrich_email_address: bool = True, enrich_phone_number: bool = False, webhook: str | None = None, **opts) -> dict — POST /async — start waterfall enrichment for up to 100 leads. Returns {id}.