Search Companies

Search for companies matching technology installs, firmographic criteria, or a combination of both.

Tool key: search_companies

Data Coverage

Metric	Value	Source
Companies in universe	40M+	HG Insights internal (verified 2026-05-11).

Filter the company universe by technology, industry, geography, and firmographics.

Parameters

Technology filters

Name	Type	Max	Description
technology_ids	number[]	10	HG Insights product IDs. Exact match. Resolve via get_vendor_information.
vendor_ids	number[]	10	HG Insights vendor IDs. Matches any product from that vendor.
category_ids	string[]	10	HG category IDs (32-char hex). Matches any product in the category.
technology_mode	"AND" | "OR"	—	"AND" (default): company must have all listed technologies. "OR": at least one.
exclude_technology_ids	number[]	10	Product IDs to exclude. Applied after inclusion filters. Validated: unknown ID returns HTTP 422.

Firmographic filters

Name	Type	Max	Description
countries	string[]	10	ISO 3166-1 alpha-2 HQ country codes (e.g. "US", "GB").
us_states	string[]	10	US 2-letter state abbreviations, exact uppercase match (e.g. "CA", "WA").
states	string[]	10	International state/province names (ILIKE). Do not use for US — use us_states instead.
industry_ids	number[]	20	HG industry IDs. Resolve via search_industries_naics_sic.
naics_codes	string[]	10	NAICS code prefix match. "54" matches all 54xxxx codes; "541512" is exact.
sic_codes	string[]	20	SIC codes — array membership match on the company's sic_codes field.
employee_min	number	—	Minimum headcount (inclusive). Companies with unknown headcount are excluded.
employee_max	number	—	Maximum headcount (inclusive). Companies with unknown headcount are excluded.
revenue_min	number	—	Minimum revenue in USD (inclusive). Companies with unknown revenue are excluded.
revenue_max	number	—	Maximum revenue in USD (inclusive). Companies with unknown revenue are excluded.
company_name	string	—	Substring match on company name (ILIKE). Max 200 chars.
domains	string[]	100	Exact match on normalised domain (e.g. "salesforce.com").

Install scope and signal-country filter

Name	Type	Default	Description
is_localized	boolean	false	false = global signals (install_global). true = per-country signals (install_localized).
technology_countries	string[]	—	ISO-2 codes for where the signal was detected. Only active when is_localized=true. Max 10.
last_verified_date	string	—	ISO 8601 date (e.g. "2024-01-01"). Excludes installs last verified before this date.

Ranking & pagination

Name	Type	Default	Max	Description
rank	"all_time" | "3m"	"all_time"	—	Order by all-time peak intensity or 3-month recent activity. Applies only when a technology filter is present.
limit	number	10	1000	Number of results to return.
offset	number	0	—	Results to skip (cursor-free pagination).

Required Integrations

• hginsights_v2

Credits

1 credit per company returned. Empty results cost 0.

How It Works

Pass technology and/or firmographic filters — all filters are AND-combined. The only exception is the technology group, where technology_mode controls whether the company must match all listed technologies ("AND", default) or any one ("OR").

Recommended workflow — always resolve IDs before searching:

1. Call get_vendor_information to find the correct vendor and obtain product IDs and category IDs.
2. Pass product IDs into technology_ids (exact match, no ambiguity).
3. For full-vendor queries: pass vendor IDs into vendor_ids.

countries vs technology_countries:

• countries — filters on company HQ country.
• technology_countries — filters on where the install was detected (requires is_localized=true).

Firmographic-only scan: when no technology filter is provided, results are ordered by relative_revenue DESC (largest companies first) and rank is ignored.

Use Cases

• List building and prospect identification
• Market research and segmentation
• Territory planning
• Technology adoption analysis

Example Usage

Find enterprise companies using Workday HCM

{
  "tool": "search_companies",
  "parameters": {
    "technology_ids": [6530],
    "employee_min": 10000,
    "rank": "all_time",
    "limit": 25
  }
}

UK companies using Salesforce OR HubSpot

{
  "tool": "search_companies",
  "parameters": {
    "technology_ids": [22, 16331],
    "technology_mode": "OR",
    "countries": ["GB"],
    "limit": 50
  }
}

US-HQ companies with French Salesforce deployments

{
  "tool": "search_companies",
  "parameters": {
    "technology_ids": [22],
    "countries": ["US"],
    "is_localized": true,
    "technology_countries": ["FR"],
    "limit": 25
  }
}

Pure firmographic scan — German mid-market companies

{
  "tool": "search_companies",
  "parameters": {
    "revenue_min": 100000000,
    "revenue_max": 500000000,
    "countries": ["DE"],
    "limit": 100
  }
}

Response Format

{
  "companies": [
    {
      "company_id": "47AE44BFDEDA1F6783316029106EEA2F",
      "company_name": "Charter Communications, Inc.",
      "domain": "charter.com",
      "relative_revenue": 120000000,
      "relative_employees": 95000,
      "country": "United States",
      "industry": "Telecommunications",
      "industry_id": 15
    }
  ],
  "total_count": 8432,
  "limit": 10,
  "offset": 0,
  "metadata": {
    "filters_applied": ["technology_ids", "countries"],
    "rank_mode": "all_time",
    "scope": "global"
  },
  "credits_consumed": 10
}

• company_id — pass to company_firmographic (as hg_id) or other enrichment tools
• relative_revenue / relative_employees — null when unknown
• industry_id — use this value in future industry_ids filters

Error Handling

Common errors:

• No valid filters: Provide at least one filter (technology, geography, firmographic, etc.)
• Missing Integration: HG Insights v2 API key not configured
• Authentication Error: Invalid API key
• Rate Limit: API rate limit exceeded

Related Tools

• get_vendor_information - Resolve vendor/product names to IDs before searching
• company_firmographic - Get detailed company information by ID or domain
• company_technographic - Analyze a company's technology stack
• company_intent - Check buying signals
• company_spend - Analyze spending patterns

Next Steps

• View all tools
• See example workflows
• Read best practices