Search companies
Stage companies by industry, size, funding, or geo.
Tool: search_companies
The call returns named rows plus search_id and creates no companies or lead group. Review the rows, use continue_search with search_id and the returned search_version for another bounded turn, then save_search(search_id) once to create or append to a company group. Changed filters start a new independent search. Defaults to US HQ (hq_country='United States') when you pass no geo; set hq_country or hq_location to search elsewhere. NOT for: hiring signals → search_companies_hiring; lookalike → search_companies_similar; one company's detail → get_company_detail.
Parameters
| Param | Type | Required | Description |
|---|---|---|---|
company_name | string | no | Company name (fuzzy) - prefer domain when known. |
domain | string or string[] | no | Company domain list (exact). |
industry | string | no | Industry (fuzzy) - resolve_industry for validated values. |
headcount_band | string[] | no | Size bucket, e.g. 201-500 (enum) - the size filter (no numeric min/max). |
hq_country | string[] | no | Country names, ISO-2, or ISO-3; normalized to ISO-3. Pass multiple countries as a list. |
hq_location | string | no | HQ location string (fuzzy). |
funding_stage | string[] | no | Last round type list, e.g. series_a (enum). |
last_funding_after | string | no | ISO date or 6m_ago - last raise on/after. |
annual_revenue_min | integer | no | Minimum estimated annual revenue in USD (gte). |
year_founded | integer | no | Founding year; use as a recency floor. |
limit | integer | no | Maximum rows for this staged turn, 1-1000. Default: 25. |
exclude_lead_group | string (slug or UUID) | no | Skip companies already in this group using stable domains. |
Returns named staged company rows and a durable
search_id; it does not create companies or a lead group.Every durable response returns
search_version; pass that value tocontinue_search(search_id, search_version)for one bounded turn.On the first save, use
save_search(search_id, group_name=...)orsave_search(search_id, lead_group_id=...)to commit approved rows.Changing filters starts a new typed search.
Unknown named params are rejected with
validation_error(a typo'd filter must never silently broaden the search) - unlike most operations, which ignore extras.
Sample request — success
{
"industry": "Software"
}Sample request — named params
{
"industry": "Software",
"headcount_band": [
"51-200"
]
}