Find leads
find_leadsSearch 200M+ B2B contacts by structured filters (titles, locations, industries, company_headcount, company_domains). At least one of titles, industries, locations, or company_domains is required. company_domains accepts up to 100 domains or URLs and restricts results to people at those companies. Industry values follow LinkedIn's taxonomy (for example, 'Hospitals and Health Care'). Returned leads have work_email null. If title_filter.withheld is above 0, the sources found people whose titles did not match; widen titles to see them. Costs 0.25 credits per lead returned, with a 3-credit minimum when any lead is returned; zero results are free. budget_credits is a spend ceiling, never permission to use a dearer source: when the call could cost more, limit is lowered to the largest that fits and result.budget_applied says so. dry_run: true returns the plan instead (the most the call can cost, how many sources could answer, and each limit it would trip) with nothing looked up, reserved or charged. Example: {"audience":"Heads of Sales and VPs of Sales at US software companies with 50 to 500 employees","titles":["Head of Sales","VP Sales"],"industries":["Software Development"],"locations":["United States"],"company_headcount":{"min":50,"max":500},"limit":25} route picks how sources are chosen: balanced (the default), cheapest, broadest or fastest. The price is the same whichever you pick, and the answer's layrcake.route says which route was used and whether it came from the request, this key's default or the default.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| route | No | Source preference for this call: balanced (the default), cheapest (the lowest-cost sources), broadest (the sources expected to find the most) or fastest. The price doesn't change with it. Where route choice isn't available to this key yet, only balanced is accepted. | |
| titles | No | ||
| dry_run | No | Return this call's plan instead of running it, as of evaluated_at: the most it can cost, how many sources could answer, what budget_credits changes, and every limit the real call would trip. Nothing is looked up, reserved or charged, and a later call may differ. Where previews aren't available to this key yet, a request that sets it is refused with the reason. | |
| premium | No | Consent, for this call only, to a dearer source when the standard sources come back short, as long as the whole call, the premium step included, stays within budget_credits (which it requires). The premium step is charged separately and reported in result.premium_step. Without it, budget_credits is only a ceiling. Where premium offers aren't available to this key yet, a request that sets it is refused with the reason. | |
| audience | Yes | ||
| locations | No | ||
| industries | No | ||
| offer_token | No | Accept a previous answer's offer: send the same call again, unchanged, with its offer.offer_token. Only the premium step runs, as its own charge at the offer's price, up to its max_credits; the token works once, until expires_at, and only when max_credits is within this key's premium allowance. Where premium offers aren't available to this key yet, a request that sets it is refused with the reason. | |
| budget_credits | No | Spend ceiling for this call, in credits. If the most the call can cost is above it, limit is lowered to the largest that fits and result.budget_applied says so; the call is refused, before anything is reserved or charged, only when not even one lead fits. It is a ceiling only: it never lets the call use a dearer source. Where spend ceilings aren't available to this key yet, a request that sets it is refused with the reason. | |
| company_domains | No | ||
| idempotency_key | No | A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that. | |
| company_headcount | No |