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).

Credits

1 — 1 per 100 companies returned. See the full credit table for how AI Credits work.

Parameters

Name	Type	Default	Description
`technology_ids`	array	-	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	-	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	-	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	-	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	-	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	-	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	-	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	-	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	-	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	-	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	-	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	-	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	-	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	-	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	-	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	-	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	-	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	-	Use localized install data (per-country signals). Default false = global signals. Must be true for technology_countries to have any effect.
`rank`	string	-	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	`10`	Maximum companies to return (default: 10, max: 1000). Use 10–50 for exploratory queries; paginate with offset for bulk workflows.
`offset`	integer	-	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

This tool is only available when your organization has the following integration configured in the Phoenix Integrations settings:

HG Insights (v2) (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
  }
}

Response Format

Field	Type	Description
`companies`	array	Array of company results (empty when group_by is specified).
`companies[].hg_id`	string	HG Insights company ID (32 alphanumeric chars). Pass directly to hg_id param on any enrichment tool (company_firmographic, company_technographic, company_research, etc.).
`companies[].company_name`	string
`companies[].domain`	string
`companies[].relative_revenue`	number \| null	HG Insights proprietary annual revenue estimate in USD (e.g. 582900000000 = ~$583B). May differ from self-reported figures. Null when unknown.
`companies[].relative_employees`	number \| null	HG Insights proprietary headcount estimate. May differ from self-reported figures. Null when unknown.
`companies[].country_code`	string \| null	ISO-2 country code (e.g. "US", "DE") — same format as the countries filter.
`companies[].industry`	string \| null
`companies[].industry_id`	number \| null	HG industry ID — use for industry_ids filter.
`groups`	array	Present when group_by is specified.
`groups[].country`	string
`groups[].product_id`	string
`groups[].product_name`	string
`groups[].vendor_name`	string
`groups[].category`	string
`groups[].industry`	string
`groups[].company_count`	number
`total_count`	number	Total matches across all pages — always the full count regardless of limit/offset. Use to decide whether to paginate.
`credits_consumed`	number	Credits billed for this call: 1 credit per 100 companies returned on this page (not per total_count). Fractional.
`metadata`	object
`metadata.filters_applied`	array
`metadata.unresolved_countries`	array

Example response

{
  "companies": [
    {
      "hg_id": "3A5EF9669B05EE3CF5A907FAC501B214",
      "company_name": "Snowflake Inc.",
      "domain": "snowflake.com",
      "relative_revenue": 4681752508,
      "relative_employees": 9030,
      "country_code": "US",
      "industry": "Computer and Electronic Product Manufacturing",
      "industry_id": 3
    }
  ],
  "total_count": 216,
  "credits_consumed": 0.02,
  "metadata": {
    "filters_applied": [
      "countries",
      "company_name"
    ]
  }
}

company_firmographic, company_technographic, search_industries_naics_sic, get_vendor_information, get_product_category

Credits​

Parameters​

Required Integrations​

Use Cases​

Example Usage​

Response Format​

Related Tools​