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. exclude_domains (up to 500) leaves out companies you have already seen, in every mode: they are never returned or charged, and result.left_out.excluded counts those the search came across. A firmographic search fetches further to fill the limit, so sending the domains you already have is how to get the next companies. 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. events: companies that had something happen (event, within within_days), each with a verbatim quote, its source and date; runs in the background and needs an Idempotency-Key. 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. | |
| event | No | Only with mode events: what happened to the companies, in plain words, for example "opened a new office in London" or "disclosed a data breach". | |
| limit | No | Most companies to return: up to 100, default 25. Mode events: up to 25, default 15. | |
| query | No | Plain-language description of the companies; one with no hiring or technology in it also needs a country (country_codes, or in the words). | |
| 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"; for a non-English-speaking country add its own words too. A company matches when its own description, products or specialties mention any of them, in the language they are written in; with keywords, industries may be left out, and an industry that means the same as a keyword asks for it twice. 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 | LinkedIn industry names, for example "Software Development" or "Online and Mail Order Retail"; other words go in keywords (firmographic). | |
| min_rating | No | Only with mode local: the lowest public map rating to keep, 1 to 5 with one decimal, for example 4.5. A business with no rating is left out and not charged. Where it isn't available to this key yet, a request that sets it is refused with the reason. | |
| similar_to | No | Company website domain or URL, e.g. acme.com or https://www.acme.com/about | |
| min_reviews | No | Only with mode local: the fewest public map reviews to keep, for example 20. A business with no review count is left out and not charged. Where it isn't available to this key yet, a request that sets it is refused with the reason. | |
| within_days | No | Only with mode events: the event happened in the last this many days (1 to 365, default 90). A company whose event has no date is left out. | |
| 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. | |
| exclude_domains | No | Company domains to leave out, up to 500: companies you've already seen. They are never returned or charged, and result.left_out.excluded counts those the search came across. In mode firmographic the search fetches further to fill the limit. | |
| 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. | |
| include_handled | No | Only inside an agent run: true includes companies this agent already checked (yes or not_found) in the last 90 days, which the run's searches otherwise leave out. Outside an agent run it changes nothing. | |
| 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 |