API Explorer

Single input — synchronous.

Bulk mode — up to 50 records in ONE request, run in parallel (provide either `input` or `inputs`, never both). Prefer this over a loop of single calls. RATE LIMIT: the whole batch is ONE request against your per-account limit, however many rows it holds — the per-row provider calls run internally and are not counted. So 50 rows sent as one batch cost 1 request, while the same 50 rows sent one at a time cost 50. PARTIAL FAILURE: a row that finds nothing, or whose provider errors, never fails the batch — every row is still attempted, the call returns 200, and that row carries its own error in its `results[]` entry. Two whole-batch failures exist: 400 if ANY row fails schema validation (the array is validated before the batch runs, so no row is attempted — clean your rows first), and 402 when EVERY row ran out of credits. ORDER: `results[]` is index-aligned with `inputs[]` — `results[i]` is always the outcome of `inputs[i]`, regardless of which row finished first. SPEND CAP: `max_credits` applies PER ROW, not per batch — a cap of 5 on a 50-row batch permits up to 5 credits for each row. TIMEOUT: the batch runs under one wall-clock budget, so a very large batch of slow lookups can return with later rows marked `timed_out` (those are refunded); re-send only those rows.

Provider routing. "auto" (default) runs a managed waterfall; a single slug pins one vendor; an array is your ordered fallback chain. Valid slugs for this verb: "findymail", "prospeo", "leadmagic", "limadata-work-email", "apollo-people-match", "wiza". These are routing slugs, not catalog provider names — a slug is often the vendor plus the capability it serves (the catalog lists "limadata"; this field takes "limadata-work-email"). An unrecognized slug returns 400 and lists the accepted set.

Per-record spend cap. A provider that would hold more than this for the record up front is not called, and a provider that answers but costs more than this is rejected and refunded, so you never pay more than N credits for one record (a miss if nothing answers in budget). A search that finds nobody costs 0. Charges a provider makes after it answers (for example per contact delivered later) are not covered. Useful to keep a single pricey provider from dominating a large fan-out.

Return a miss as HTTP 200 `{ "found": false, "verdict": "not_found", "providers_tried": N }` instead of 404. Use it when a 404 is indistinguishable from a real failure in your client (spreadsheet tools paint every non-2xx cell red, and "re-run the errored cells" then re-executes whole provider waterfalls for rows that will miss again). The verdict vocabulary matches the async sibling `/v1/jobs/{job_id}/results`. A miss is free either way. Only the "no provider had it" 404 converts — 400 (invalid input), 402 (out of credits) and 504 (`timed_out`, the waterfall was cut short so the miss is unproven) are unchanged. Default false.

On a miss with a linkedin_url: enrich the person to resolve their CURRENT employer's domain and retry the waterfall once with it — recovers stale/acquired input domains (extra ~1 credit for the enrich hop, disclosed in `_meta.employer_resolution`). Default false.