# Contact Finder
https://contactfinder.online
Target + contact goal → public business contacts with original evidence.
OpenAPI: /openapi.json | Human API guide: /docs | Health: /api/v1/health (configuration only, no database; add ?ready=1 for a cached database check) | Human result page: /result/{id}
POST /api/v1/find with application/json and a random secret Idempotency-Key (16–128 ASCII letters/digits/_/-).
Example: {"target":{"domain":"example.com"},"contact_goal":"sales","max_results":5}
Target may include name, organization, professional_name (business context required), domain, website, known_url, country (ISO alpha-2), city, region, location, service_area, industry. Name-only requests return entity candidates for explicit domain selection.
Goals: general, sales, support, billing, partnerships, press, careers, legal, procurement, management, other.
Types: email, phone, contact_form, support_page, sales_page, booking, contact_page, social.
Language: request_language, source_languages, preferred_output_language, aliases, local_terms. Language is independent of geography. Original text and URLs remain authoritative. Explanations are stable machine codes; no automatic translation.
Payment: x402 v2 exact USDC. Read HTTP 402 PAYMENT-REQUIRED header; sign through an x402 EVM client; resend IDENTICAL JSON and Idempotency-Key with PAYMENT-SIGNATURE. Settlement uses CDP and the configured public receiving wallet. PAYMENT-RESPONSE is returned after settlement.
Demo uses synthetic fixtures and PAYMENT-SIGNATURE: demo:<key>; no real payment. Never treat demo output as real contact data.
Prices and budget: {"currency":"USDC","network":"eip155:8453","mode":"live","model":"variable-cost-v2","formula":"max(minimum_usdc, multiplier × estimated_variable_cost_usd), rounded up to 0.000001 USDC","multiplier":3,"minimum_usdc":0.03,"cost_basis":"worst_case_single_attempt","calibration":{"measured_at":"2026-09-28","method":"Live pipeline with the production page fetcher against 6 real business websites (EN, DE, JA, RU, FR); zero paid search needed.","measured_max":{"cpu_seconds":0.38,"wall_seconds":7.7,"result_bytes":14283,"searches":0}},"tiers":[{"tier":"quick","amount":"0.061761","currency":"USDC","model_id":"8bf64b49eb4e31e7","formula":"max(minimum_usdc, multiplier × estimated_variable_cost_usd), rounded up to 0.000001 USDC","multiplier":3,"minimum_usdc":0.03,"estimated_variable_cost_usd":0.020586856533,"cost_basis":"worst_case_single_attempt","cost_components_usd":{"search":0.016,"page_provider":0,"model":0,"browser":0,"email_verification":0,"compute_cpu":0.000062222222,"compute_memory":0.000329777778,"invocations":0.0000024,"edge_requests":0.000008,"transfer":0.0000688128,"storage":0.000115643733,"database":0.003,"settlement":0.001,"other":0},"searches":2,"pages":3,"priced_attempts":1,"included_attempts":3,"assumptions":{"memory_gb":2,"cpu_seconds_base":1,"cpu_seconds_page":0.25,"overhead_seconds":10,"page_timeout_seconds":12,"search_seconds":5,"result_bytes":65536,"replay_bytes":8192,"storage_amplification":2,"retrieval_allowance":2,"retention_days":30,"wall_seconds_per_attempt":56},"rates":{"search_credit_usd":0.008,"settlement_usd":0.001,"cpu_hour_usd":0.128,"memory_gb_hour_usd":0.0106,"invocation_usd":6e-7,"edge_request_usd":0.000002,"transfer_gb_usd":0.21,"storage_gb_month_usd":0.35,"database_attempt_usd":0.003,"other_attempt_usd":0}},{"tier":"standard","amount":"0.086565","currency":"USDC","model_id":"8bf64b49eb4e31e7","formula":"max(minimum_usdc, multiplier × estimated_variable_cost_usd), rounded up to 0.000001 USDC","multiplier":3,"minimum_usdc":0.03,"estimated_variable_cost_usd":0.028854967644,"cost_basis":"worst_case_single_attempt","cost_components_usd":{"search":0.024,"page_provider":0,"model":0,"browser":0,"email_verification":0,"compute_cpu":0.000088888889,"compute_memory":0.000571222222,"invocations":0.0000024,"edge_requests":0.000008,"transfer":0.0000688128,"storage":0.000115643733,"database":0.003,"settlement":0.001,"other":0},"searches":3,"pages":6,"priced_attempts":1,"included_attempts":3,"assumptions":{"memory_gb":2,"cpu_seconds_base":1,"cpu_seconds_page":0.25,"overhead_seconds":10,"page_timeout_seconds":12,"search_seconds":5,"result_bytes":65536,"replay_bytes":8192,"storage_amplification":2,"retrieval_allowance":2,"retention_days":30,"wall_seconds_per_attempt":97},"rates":{"search_credit_usd":0.008,"settlement_usd":0.001,"cpu_hour_usd":0.128,"memory_gb_hour_usd":0.0106,"invocation_usd":6e-7,"edge_request_usd":0.000002,"transfer_gb_usd":0.21,"storage_gb_month_usd":0.35,"database_attempt_usd":0.003,"other_attempt_usd":0}},{"tier":"deep","amount":"0.111608","currency":"USDC","model_id":"8bf64b49eb4e31e7","formula":"max(minimum_usdc, multiplier × estimated_variable_cost_usd), rounded up to 0.000001 USDC","multiplier":3,"minimum_usdc":0.03,"estimated_variable_cost_usd":0.03720263431,"cost_basis":"worst_case_single_attempt","cost_components_usd":{"search":0.032,"page_provider":0,"model":0,"browser":0,"email_verification":0,"compute_cpu":0.000124444444,"compute_memory":0.000883333333,"invocations":0.0000024,"edge_requests":0.000008,"transfer":0.0000688128,"storage":0.000115643733,"database":0.003,"settlement":0.001,"other":0},"searches":4,"pages":10,"priced_attempts":1,"included_attempts":3,"assumptions":{"memory_gb":2,"cpu_seconds_base":1,"cpu_seconds_page":0.25,"overhead_seconds":10,"page_timeout_seconds":12,"search_seconds":5,"result_bytes":65536,"replay_bytes":8192,"storage_amplification":2,"retrieval_allowance":2,"retention_days":30,"wall_seconds_per_attempt":150},"rates":{"search_credit_usd":0.008,"settlement_usd":0.001,"cpu_hour_usd":0.128,"memory_gb_hour_usd":0.0106,"invocation_usd":6e-7,"edge_request_usd":0.000002,"transfer_gb_usd":0.21,"storage_gb_month_usd":0.35,"database_attempt_usd":0.003,"other_attempt_usd":0}}],"policy":"Prepaid fixed tier: max(minimum, 3 × variable cost of one research attempt that uses the full tier budget). Cost covers search credits, compute, database, transfer, storage and CDP settlement; there are no model, browser or translation calls. Actual per-request cost is recorded separately and is usually lower (known-domain lookups often need no paid search). No retrospective surcharge or automatic refund. Zero-contact and ambiguous results are paid outcomes. Provider failures allow two free retries with the identical key/body. Unknown settlements require reconciliation."}
GET /api/v1/requests/{id} with Authorization: Bearer <original Idempotency-Key>. 202 means check again after a few seconds; 503 retryable=true means resend same key/body with Authorization: Bearer <same key> and no new payment (an unsigned request without Authorization only receives a fresh 402 challenge). Never replace a key after an uncertain settlement.
Output: request_id, status (completed/ambiguous_entity), target, query, contacts, best_contact (contact ID), entity_candidates, limitations, checked_at, mode, price, output_language. Each contact includes type/value/display_value/purpose/original_department/organization/confidence/verification_class/verification_status/source_url/checked_at/evidence/conflicts. Evidence includes URL, title, original_text, source_language (declared by the page, else null), source_script (detected writing system, never mapped to a language or country), retrieval timestamp, source type and freshness.
Verification: verification_class is verified ONLY for contacts observed on the official site, likely for external public sources, inferred/unknown otherwise; an inferred contact can never be verified. published_on_official_site/published_on_external_source prove observation only. inferred/unverified are schema states; MVP never generates inferred addresses. email_checks distinguishes syntax, MX (null unless checked), and deliverability (false unless checked). Confidence is heuristic, not a calibrated probability. External listings have unknown freshness. Multiple different contacts are preserved as alternatives, not assumed wrong.
Errors: 400 invalid_request/invalid_url/invalid_json/idempotency_key_required; 402 payment required/rejected; 409 idempotency_conflict/payment_reused; 413 request_too_large; 415 unsupported_media_type; 429 rate_limited; 503 not_configured/provider_unavailable/settlement_unknown.
Limitations: no passwords/private personal contacts/access-control bypass; no guessed emails; static HTML only; no SMTP mailbox probing; no exhaustive crawl; price covers an attempted bounded search including zero contacts or ambiguous entity. Up to two free provider-failure retries. No automated refunds. Results retained for 30 days; compact replay/accounting records 365 days.