search_companies next channel

Status: Modified (v2 rewrite; nested filter groups; identity-only result rows) This tool is on the private next MCP channel for allow-listed orgs. When promoted, this file moves to mcp-tools/search-companies.md.

Search and discover companies using the HG Insights v2 search API. Each filter group is a separate parameter — all are optional and combine with AND semantics. Returns lean identity-only rows (hg_id, name, domain, domain_normalized) plus a total_count. Feed the returned hg_ids into company_firmographic, company_technographic, company_spend, etc. to pull detailed data.

Integration required: hginsights_v2__data_api Cache schema version: 5 (differs from base — stale cached payloads from the public channel will not be served)

Parameters

Parameter	Type	Required	Default	Description
company_identifiers	object	Optional	—	Filters by known company identifiers (HG IDs or domains). Supports company_ids, domains, and company_ids_including_corporate_relatives (matches a company and its whole corporate family). Use inclusion_method: "NONE_PRESENT" for whitespace analysis.
firmographics	object	Optional	—	Firmographic-based filters: company_level (ALL_ENTITIES / CORPORATE_PARENT / DOMESTIC_PARENT / GLOBAL_HEADQUARTER), country_codes, region_names, state_ids, employees ({ min, max }), revenue ({ min, max }), industries, naics_codes.
installs	object	Optional	—	Filters on detected technology installs. Each clause is a { ids, inclusion_method } object where inclusion_method is ANY_PRESENT / ALL_PRESENT / NONE_PRESENT. Sub-keys: products, vendors, product_categories, product_attributes, country, product_last_verified_date, and *.fai for buying-committee dept/role filtering.
intent	object	Optional	—	Intent signal filters: topics ({ ids, inclusion_method }), signal_score (MEDIUM / HIGH), context_type_ids, buyers_journey_ids, number_of_cadences, location.
ai_maturity	object	Optional	—	AI and data maturity filters: ai_maturity_score, ai_maturity_rank, ai_maturity_6m_delta, genai_intent_score (ranges), ai_product_use, data_maturity_level, dominant_cloud_provider.
cloud_maturity	object	Optional	—	Cloud adoption/maturity filters: AWS/Azure/GCP product counts, cloud_stack_percent_change (can be negative), current/new cloud-product percentages.
corporate_hierarchy	object	Optional	—	DEPRECATED — prefer firmographics.company_level, which takes precedence when both are set. Boolean flags: is_corporate_parent, is_domestic_parent, is_global_headquarters.
spend	object[]	Optional	—	Filter by IT spend in a category. Array of clauses — each requires categories + range.
limit	integer	Optional	10	Maximum companies to return (default: 10, max: 100). Paginate with offset.
offset	integer	Optional	0	Pagination offset (0–24999). total_count gives total matches across all pages.
sorts	object[]	Optional	—	Sort order — array of {direction, field}. Sortable fields: id, name, domain, domain_normalized, plus ranking signals (ai_maturity_score, ai_maturity_rank, ai_maturity_6m_delta, genai_intent_score, current_products_used_cloud_percent, cloud_stack_percent_change). Ranking signals can be sorted/filtered but are not returned as result columns.

Migration from old flat parameters

The old flat parameters (technology_ids, countries, revenue_min, company_name, …) are removed. Use the nested filter-group objects instead.

Before	After
technology_ids: [348]	installs.products: [{ "ids": [348], "inclusion_method": "ANY_PRESENT" }]
technology_mode: "AND"	installs.products with inclusion_method: "ALL_PRESENT"
exclude_technology_ids: [348]	installs.products: [{ "ids": [348], "inclusion_method": "NONE_PRESENT" }]
vendor_ids: [316]	installs.vendors: [{ "ids": [316], "inclusion_method": "ANY_PRESENT" }]
category_ids: ["…"]	installs.product_categories: { "ids": ["…"], "inclusion_method": "ANY_PRESENT" }
countries: ["US"]	firmographics.country_codes: [{ "ids": ["US"], "inclusion_method": "ANY_PRESENT" }]
employee_min / employee_max	firmographics.employees: { "min": 1000, "max": 5000 }
revenue_min / revenue_max	firmographics.revenue: { "min": 1000000 }
industry_ids: [12]	firmographics.industries: [{ "ids": [12], "inclusion_method": "ANY_PRESENT" }]
company_name: "Cisco"	removed — search by domain or exact ID instead
limit cap	1000

Response Format

{
  "companies": [
    {
      "hg_id": "3AB6196C456CE3313A04A57BA6FA7BE3",
      "name": "Ford Motor Company",
      "domain": "ford.com",
      "domain_normalized": "ford.com"
    }
  ],
  "total_count": 16108275
}

Output changes from base tool

Before: rows included company_name, relative_revenue, relative_employees, country_code, industry, industry_id. After: rows are hg_id, name, domain, domain_normalized only. credits_consumed and metadata envelope fields are gone.

Feed the returned hg_ids into company_firmographic (or company_technographic, company_spend, etc.) to pull revenue, employee count, country, and industry.

Example Usage

Find companies with Snowflake installed, in the US, with 1000–5000 employees:

{
  "tool": "search_companies",
  "parameters": {
    "installs": {
      "products": [{ "ids": [26434], "inclusion_method": "ANY_PRESENT" }],
      "country": { "codes": ["US"] }
    },
    "firmographics": {
      "employees": { "min": 1000, "max": 5000 }
    },
    "limit": 20
  }
}

Find companies showing high intent on cloud security:

{
  "tool": "search_companies",
  "parameters": {
    "intent": {
      "topics": { "ids": ["A1B2C3D4…"], "inclusion_method": "ANY_PRESENT" },
      "signal_score": "HIGH"
    },
    "limit": 10
  }
}

Related Tools

• list_intent_topics — resolve topic names to hex IDs for intent.topics.ids.
• company_firmographic — enrich returned hg_ids with firmographic detail.
• company_technographic — enrich returned hg_ids with tech stack.
• get_product_category — resolve category names to IDs for installs.product_categories.

Changelog

2026-07-30 — Breaking: migrated to the unified /data-api/v2/companies/search contract

Availability: live now on the private next MCP channel for allow-listed orgs. The public /api/mcp contract is unchanged until the promotion PR lands.

Why this changed: search_companies now mirrors the official HG Insights company-search API one-to-one, enabling far richer, more precise targeting — intent, AI maturity, cloud maturity, IT spend, corporate hierarchy, FAI, and per-install location — all in a single call.

Breaking change: filters are now nested groups

The old flat parameters (technology_ids, countries, revenue_min, etc.) are removed. See the migration table above.

Breaking change: result rows are leaner

company_name, relative_revenue, relative_employees, country_code, industry, and industry_id are no longer returned — get them by passing each hg_id to company_firmographic. credits_consumed and metadata envelope fields are gone. limit is now capped at 100 (was 1000); page through larger sets with offset (max 24999).

What stayed the same: tool is still called search_companies, and hg_id, domain, and total_count keep the same names and meaning.

What changed in pricing (#2087): search_companies is no longer free. It bills 1 credit per 100 companies returned on the page (fractional — 50 results is 0.5 credits), charged on the returned page size rather than total_count. This applies to both the next channel and the base tool.

Deprecated corporate_hierarchy params

Deprecated	Replacement
corporate_hierarchy.is_corporate_parent: true	firmographics.company_level: "CORPORATE_PARENT"
corporate_hierarchy.is_domestic_parent: true	firmographics.company_level: "DOMESTIC_PARENT"
corporate_hierarchy.is_global_headquarters: true	firmographics.company_level: "GLOBAL_HEADQUARTER"

The corporate_hierarchy filter group is still accepted but deprecated. firmographics.company_level takes precedence when both are provided.