Find companies
find_companiesDiscover companies by hiring activity, technologies in use, similarity to one company domain, or a plain-language query (up to 400 characters, translated server-side into those filters and echoed back in result.interpreted). Industry phrases in a plain-language query are not applied; they appear in result.interpreted.dropped.industries so the result can be disclosed and narrowed with supported filters. Hiring, technology and query requests accept provider-taxonomy industries, ISO alpha-2 country_codes and company_headcount. Sent with a query, they win over what the query says; company_headcount merges bound by bound, so a bound you leave out keeps the query's value unless that would invert the range, in which case your range is used alone. result.interpreted.caller_filters lists them with every reading of the query they replaced or dropped. limit defaults to 25, maximum 100. Returns unique companies with evidence and company_domains, plus jobs_last_30_days and last funding round facts when the source reports them. Technology matches carry match_confidence; only high-confidence companies are returned and billed unless include_low_confidence is true, which adds a separate unbilled low_confidence_companies list. Technologies take a tool's usual name (for example Customer.io or Pendo); an unknown name is refused with close suggestions. A similar_to request also accepts country_codes and company_headcount: each lookalike then comes back with headcount, industry and country, companies that don't fit are dropped and free (counted in result.filtered_out), and each company kept costs 33 credits. Hiring results cost 11 credits each, unfiltered lookalikes 13 and technology results 16; zero results are free. mode: "firmographic" finds companies by industries (LinkedIn's names, as on find_leads) and ISO alpha-2 country_codes, optionally narrowed by locations (cities or regions, matched against each company's headquarters) and company_headcount; 2 credits a company. mode: "local" finds local businesses by categories (for example "dentist") in locations, each a city with its country (for example "Leeds, United Kingdom"); 3 credits a business, with a website. 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: {"hiring":{"titles":["GTM Engineer","Sales Development Representative"],"posted_within_days":30},"country_codes":["US","GB"],"company_headcount":{"min":50,"max":500},"limit":10} 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 |
|---|---|---|---|
| mode | No | firmographic: companies by industries (LinkedIn's names, as on find_leads), country_codes, and optionally locations and company_headcount. local: local businesses by categories (for example "dentist") in locations. Leave it out for hiring, technologies, similar_to or query. Where a mode isn't available to this key yet, a request that sets it is refused with the reason. | |
| limit | No | ||
| query | 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. | |
| hiring | 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. | |
| audience | No | ||
| keywords | No | Only with mode firmographic: 1 to 10 phrases, for example "carbon accounting" or "dental practice management". A company matches when its own description, products or specialties mention any of them; with keywords, industries may be left out. Each company then comes back with its description. Where keywords aren't available to this key yet, a request that sets them is refused with the reason. | |
| locations | No | Places, only with mode. firmographic: optional cities or regions inside country_codes, matched against each company's headquarters. local: required, each a city with its country, for example "Leeds, United Kingdom" or "Austin, TX". | |
| categories | No | Only with mode local: the kinds of business, for example "dentist" or "commercial cleaning service". | |
| industries | No | ||
| similar_to | No | Company website domain or URL, e.g. acme.com or https://www.acme.com/about | |
| technologies | No | ||
| country_codes | No | ||
| 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 company 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. | |
| 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. | |
| exclude_keywords | No | Only with mode firmographic: up to 10 phrases, for example "recruitment agency" or "consultancy". Companies whose own description mentions any of them are left out. Each company then comes back with its description. Where exclude_keywords aren't available to this key yet, a request that sets them is refused with the reason. | |
| company_headcount | No | Employee-count range. With no min or max, companies with fewer than 10 employees are left out. Any bound replaces that default: a max without a min searches from 1 employee. | |
| include_low_confidence | No |