Search Companies

Search for companies by firmographic and technographic criteria — list/filter workflow (e.g. "find US tech companies using Snowflake with 1K–10K employees"). Use for building prospect/ICP lists, filtering by technology install across many companies, or segmenting by geography, employee band, revenue range, industry, or NAICS.

Do NOT use when:

You already know the domain or hg_id — call company_firmographic (faster, exact match, richer data).
You want a full company profile (intent, spend, technographics) — call company_research.
You want one company's full tech stack — call company_technographic (returns installs, not a list).

GUARDRAIL: a zero-param call is rejected with HTTP 422 (server enforces ≥1 filter). Firmographic-only filters are too broad alone — countries=["US"] matches 500K+ records, revenue/employee filters 100K+. Always pair any firmographic-only filter with a meaningful one: technology_ids, vendor_ids, category_ids, countries, or industry_ids.

⚠ TOKEN BUDGET: limit above 50 with a broad geo/revenue filter can produce 100–250KB responses that overflow the context window. Default limit=10; use 10–50 for exploration; paginate with offset for bulk. Do NOT set limit=1000 unless batching results outside this conversation.

NOTE: rank and last_verified_date are no-ops on firmographic-only queries — they only apply when technology_ids, vendor_ids, or category_ids is present (metadata still echoes rank_mode).

Bad technology_ids/vendor_ids/category_ids return HTTP 422 (not empty results) — resolve via get_vendor_information.

Response: companies[]{hg_id (→ enrichment tools), domain, company_name, relative_revenue (HG USD est, nullable), relative_employees (HG est), country_code (ISO-2), industry, industry_id}; total_count = total matches (paginate with offset).

Parameters

Name	Type	Required	Default	Description
`technology_ids`	array	❌ No	-	HG Insights product IDs — exact match, max 10. Validated: an unrecognized ID returns HTTP 422 (no silent empty result). Resolve IDs via get_vendor_information or product_search_and_enrich before filtering — there is no technology_name param.
`vendor_ids`	array	❌ No	-	HG Insights vendor IDs — matches all products from that vendor, max 10. Validated: unknown vendor ID returns HTTP 422. Resolve via get_vendor_information. Use technology_ids instead when you want specific products.
`category_ids`	array	❌ No	-	HG Insights category IDs (UUID, e.g. "a1b2c3d4-e5f6-7890-abcd-ef1234567890"), max 10. Validated: unknown category ID returns HTTP 422. Resolve via get_vendor_information — it returns category_ids on each product row.
`exclude_technology_ids`	array	❌ No	-	Product IDs to exclude from results, max 10. Applied after inclusion filters (technology_ids, vendor_ids, category_ids). Validated: unknown product ID returns HTTP 422.
`technology_mode`	string	❌ No	-	AND = company must have ALL listed technology_ids (default). OR = company needs any one. IMPORTANT: this setting only controls how multiple technology_ids are combined — vendor_ids and category_ids are always OR-matched regardless of this value.
`industry_ids`	array	❌ No	-	HG industry IDs — exact match on the company's own industry_id, max 20. Validated: unknown ID returns HTTP 422. Resolve valid IDs via search_industries_naics_sic.
`naics_codes`	array	❌ No	-	NAICS code prefixes, max 10. "54" matches all 54xxxx codes; "541512" is exact. Validated: unrecognized prefix returns HTTP 422. Find valid codes via search_industries_naics_sic.
`sic_codes`	array	❌ No	-	SIC codes — array membership match on the company's sic_codes field, max 20. Validated: unknown code returns HTTP 422. Find valid codes via search_industries_naics_sic.
`countries`	array	❌ No	-	Exact match on company HQ country (ISO-2, e.g. "US", "DE", "GB"), max 10. Filters by headquarters location, not where the tech was detected. Can be combined with technology_countries — e.g. countries=["US"] + technology_countries=["DE"] finds US-HQ companies where the technology signal was detected in Germany.
`technology_countries`	array	❌ No	-	ISO-2 country codes for WHERE the technology signal was detected (not company HQ), max 10. ⚠ ENFORCED — requires is_localized=true (omitting returns HTTP 422). ⚠ ENFORCED — requires at least one companion filter (technology_ids, vendor_ids, category_ids, or a firmographic filter); omitting all companions returns HTTP 422. NOTE: Without a technology filter (technology_ids/vendor_ids/category_ids), returns companies with any install signal in that country — not a specific product. Results may include companies with a country_code different from this filter (signal location ≠ HQ location). Can be combined with countries — e.g. technology_countries=["DE"] + countries=["US"] finds US-HQ companies with the tech detected in Germany.
`domains`	array	❌ No	-	Exact match on normalised company domain (e.g. "salesforce.com") — exact spelling, no protocol or www prefix, max 100. Preferred over company_name when you know the domain.
`last_verified_date`	string	❌ No	-	ISO 8601 date (e.g. "2024-01-01"). Excludes installs last verified before this date. Combine with rank=3m to restrict to recently re-confirmed installs only.
`revenue_min`	number	❌ No	-	Minimum annual revenue in USD (e.g. 1000000 = $1M, 1000000000 = $1B). HG proprietary estimate — may differ from self-reported figures. Do NOT use as the only filter — pair with technology_ids, vendor_ids, category_ids, or countries to avoid matching millions of companies.
`revenue_max`	number	❌ No	-	Maximum annual revenue in USD (e.g. 1000000000 = $1B). HG proprietary estimate — may differ from self-reported figures. Do NOT use as the only filter — pair with technology_ids, vendor_ids, category_ids, or countries.
`employee_min`	integer	❌ No	-	Minimum employee count. Common bands: 1–100 (SMB), 101–1000 (mid-market), 1001+ (enterprise). HG proprietary estimate — may differ from self-reported figures. Pair with technology_ids or countries to avoid overly broad results.
`employee_max`	integer	❌ No	-	Maximum employee count. Pair with employee_min to define a band. HG proprietary estimate — may differ from self-reported figures. Pair with technology_ids or countries to avoid overly broad results.
`company_name`	string	❌ No	-	Case-insensitive substring (ILIKE) match on company name. Only use for known, specific names (e.g. "Salesforce", "Cisco Systems"). Do NOT pass descriptive phrases like "fast-growing SaaS" — this is a direct database string match, not semantic search; descriptive phrases return zero results. Prefer the domains filter for known companies.
`is_localized`	boolean	❌ No	-	Use localized install data (per-country signals). Default false = global signals. Must be true for technology_countries to have any effect.
`rank`	string	❌ No	-	all_time (default): historically strongest installs — best for ICP lists. 3m: recent adoption momentum — best for intent-based outreach. Combine with last_verified_date to further restrict to recently re-confirmed installs. NOTE: rank and last_verified_date only affect results when at least one of technology_ids, vendor_ids, or category_ids is present — they filter install recency, not company-level recency; on firmographic-only queries they have no effect.
`limit`	number	❌ No	`10`	Maximum companies to return (default: 10, max: 1000). Use 10–50 for exploratory queries; paginate with offset for bulk workflows.
`offset`	integer	❌ No	-	Pagination offset (default: 0). Use with limit to page through results. total_count in the response gives total matches across all pages regardless of limit.

Required Integrations

hginsights_v2

Use Cases

Build a target account list of US mid-market companies (1,000–10,000 employees) using a given CRM
Find European enterprise companies (revenue > $500M) that adopted AWS or Azure
Discover companies in a NAICS sector headquartered in a specific country
Identify US companies where a technology was detected in their UK operations (technology_countries + is_localized)
Find companies NOT using a competitor (exclude_technology_ids) but using a product (technology_ids)

Example Usage

Mid-market US companies using a technology

{
  "tool": "search_companies",
  "arguments": {
    "countries": [
      "US"
    ],
    "employee_min": 1000,
    "employee_max": 10000,
    "technology_ids": [
      12345
    ],
    "limit": 25
  }
}

Enterprise EMEA by revenue with a tech filter

{
  "tool": "search_companies",
  "arguments": {
    "countries": [
      "DE",
      "FR",
      "GB"
    ],
    "revenue_min": 500000000,
    "technology_ids": [
      67890
    ],
    "rank": "3m",
    "limit": 50
  }
}

Paginate through results (page 2)

{
  "tool": "search_companies",
  "arguments": {
    "countries": [
      "US"
    ],
    "industry_ids": [
      3
    ],
    "limit": 25,
    "offset": 25
  }
}

company_firmographic, company_technographic, search_industries_naics_sic, get_vendor_information, get_product_category

Parameters​

Required Integrations​

Use Cases​

Example Usage​

Related Tools​

Parameters

Required Integrations

Use Cases

Example Usage

Related Tools