Bill-on-match billing

411data enrichment routes use fixed (exact) pricing charged up front by the balance waterfall, with automatic refund when no usable match is found.

Routes (live)

Route Refund when
/api/v1/enrich/phone matched: false
/api/v1/enrich/person matched: false
/api/v1/enrich/websearch matched: false
/api/v1/enrich/lead-session no usable enrichment fields

Catalog routes (offline by default) also bill-on-match when enabled: /api/v1/enrich/email, /enrich/company (matched: false), and /api/v1/leads/search (zero rows).

Response signals

{
  "matched": false,
  "billed": false,
  "cache_hit": false
}

After refund, billed should read false on no-match responses.

Billing order (unchanged)

  1. Virtual USD balance debited first.
  2. 402 + x402 only when balance cannot cover the price.

Audit

Every call is stored in request_response_store with input hash for cache lookups — repeated identical inputs may return cache_hit: true without re-hitting vendors.

Lead-session vendor hops also honor cache_hit. Cross-agent lead-session warm-seed uses unrolled phone/company/person indexes (GLOBAL_LEAD_CACHE_TTL_HOURS, default 168h) — not CRM contact_id.