Search Companies

Coming soon

The v2 MCP API is in preview and not yet generally available. These pages document its tools and request/response shapes; live data access is limited to enrolled organizations until v2 is released.

Search and discover companies using the HG Insights v2 search API. Each filter group is a separate, optional parameter; groups combine with AND semantics.

Use this when:

Building a prospect or ICP list (e.g. "US corporate parents with 1K+ employees using Oracle").
Filtering by technology installs, intent, or AI/GenAI maturity.
Whitespace analysis — exclude known CRM accounts (company_identifiers.company_ids with NONE_PRESENT). Do NOT use this when you already know the company domain or hg_id — call company_firmographic instead.

To find companies by name use company_identifiers.name (case-insensitive token substring match); with an exact domain, company_identifiers.domains is more precise. Resolve product/vendor/category IDs first: invalid IDs are NOT rejected — they match nothing and return total_count 0, indistinguishable from a genuine zero-match.

GUARDRAIL: broad firmographic-only filters (e.g. countries=["US"], or revenue/employee alone) match hundreds of thousands to millions of records. Always pair a firmographic-only filter with a meaningful installs, intent, industry, or geography filter (≥2 filter groups).

⚠ TOKEN BUDGET: rows are lean (four identity columns), but limit is capped at 100 (default 10). Use 10–50 for exploration and paginate with offset for bulk workflows; total_count reports matches across all pages.

NOTE: sorting on a ranking signal (e.g. ai_maturity_score) orders results but never adds a column — the four returnable fields are unchanged, so a sort is a no-op for the payload shape.

Response: companies[]{hg_id, name, domain, domain_normalized} + total_count. AI-maturity/GenAI scores, revenue, employees, country, and industry are filterable/sortable but NOT returned — call company_firmographic with hg_id for those.

Credits

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

Parameters

Name	Type	Default	Description
`company_identifiers`	object	-	Filters by known company identifiers (HG IDs, domains, or name).
`company_identifiers.company_ids`	object	-	HG company hex IDs (32-char). Use ANY_PRESENT to include; NONE_PRESENT to exclude known accounts (whitespace analysis).
`company_identifiers.company_ids.ids` Required	array	-	Hex-encoded IDs
`company_identifiers.company_ids.inclusion_method` Required	string	-
`company_identifiers.company_ids_including_corporate_relatives`	object	-	Like company_ids but also matches the entire corporate family of each provided ID.
`company_identifiers.company_ids_including_corporate_relatives.ids` Required	array	-	Hex-encoded IDs
`company_identifiers.company_ids_including_corporate_relatives.inclusion_method` Required	string	-
`company_identifiers.domains`	object	-	Filter by normalized company domain. NONE_PRESENT excludes those domains.
`company_identifiers.domains.ids` Required	array	-	Company domains (e.g. "cisco.com")
`company_identifiers.domains.inclusion_method` Required	string	-
`company_identifiers.name`	string	-	Free-text company-name search. Case-insensitive substring match — every space-separated token must appear in the company name (e.g. "acme corp" matches "Acme Corporation"). Use when you have a name but not a domain or hg_id.
`firmographics`	object	-	Firmographic-based filters: company hierarchy, geography, size, and industry.
`firmographics.company_level`	string	-	Hierarchy level. CORPORATE_PARENT = brand-level; GLOBAL_HEADQUARTER = ultimate parent. Omit for all entities.
`firmographics.country_codes`	array	-	HQ country filter. Multiple clauses combine. NONE_PRESENT to exclude countries.
`firmographics.country_codes[].ids` Required	array	-	ISO-2 country codes, e.g. ["US","DE"]
`firmographics.country_codes[].inclusion_method` Required	string	-
`firmographics.region_names`	object	-	Geographic region — ids accepts "AMER", "APAC", "EMEA", "LATAM", etc. Only ANY_PRESENT supported.
`firmographics.region_names.ids` Required	array	-	Literal region code strings, e.g. "AMER", "APAC", "EMEA", "LATAM" — NOT hex IDs.
`firmographics.region_names.inclusion_method` Required	string	-
`firmographics.state_ids`	object	-	US state hex IDs. Only ANY_PRESENT supported.
`firmographics.state_ids.ids` Required	array	-	US state hex IDs (32-char) — resolve via search_industries_naics_sic or company_firmographic, NOT literal state names/abbreviations.
`firmographics.state_ids.inclusion_method` Required	string	-
`firmographics.employees`	object	-	Employee count filter.
`firmographics.employees.min`	integer	-	Minimum employee count
`firmographics.employees.max`	integer	-	Maximum employee count
`firmographics.employees.has_fixed_employees`	boolean	-	true = only companies with a fixed headcount (exclude ranged records)
`firmographics.revenue`	object	-	Annual revenue filter in USD (HG proprietary estimate).
`firmographics.revenue.min`	number	-	Minimum annual revenue in USD
`firmographics.revenue.max`	number	-	Maximum annual revenue in USD
`firmographics.revenue.has_fixed_revenue`	boolean	-	true = only companies with a fixed revenue value (exclude ranged records)
`firmographics.industries`	array	-	HG industry filter. Multiple clauses combine.
`firmographics.industries[].ids` Required	array	-	HG industry integer IDs — resolve via search_industries_naics_sic
`firmographics.industries[].inclusion_method` Required	string	-
`firmographics.naics_codes`	array	-	NAICS filter. Array of clauses; each clause carries EITHER hex ids OR raw codes (exactly one). Multiple clauses combine.
`firmographics.naics_codes[].ids`	array	-	HG internal NAICS hex IDs (32-char) — NOT raw code strings
`firmographics.naics_codes[].codes`	array	-	Raw NAICS code strings, e.g. ["5221"]
`firmographics.naics_codes[].inclusion_method` Required	string	-
`firmographics.sic_codes`	array	-	SIC filter. Array of clauses; each clause carries EITHER hex ids OR raw codes (exactly one). Multiple clauses combine.
`firmographics.sic_codes[].ids`	array	-	HG internal SIC hex IDs (32-char) — NOT raw code strings
`firmographics.sic_codes[].codes`	array	-	Raw SIC code strings, e.g. ["5912"]
`firmographics.sic_codes[].inclusion_method` Required	string	-
`installs`	object	-	Filters on detected technology installs (technographics).
`installs.products`	array	-	Filter by installed products. Array allows combining multiple inclusion methods (e.g. must have A, must not have B).
`installs.products[].ids` Required	array	-	HG product IDs — resolve via get_vendor_information or product_search_and_enrich. Invalid IDs are not rejected: they match nothing and return total_count 0.
`installs.products[].inclusion_method` Required	string	-	ANY_PRESENT = has at least one; ALL_PRESENT = has all; NONE_PRESENT = has none
`installs.products[].fai`	object	-	Functional Area Intelligence — narrow installs by associated buying-committee departments and/or roles. At least one of departments/roles required.
`installs.products[].fai.departments`	object	-	Buying-committee departments (hex IDs).
`installs.products[].fai.departments.ids` Required	array	-	Functional-area hex IDs
`installs.products[].fai.departments.inclusion_method` Required	string	-
`installs.products[].fai.roles`	object	-	Buying-committee roles (hex IDs).
`installs.products[].fai.roles.ids` Required	array	-	Functional-area hex IDs
`installs.products[].fai.roles.inclusion_method` Required	string	-
`installs.products[].install_age`	object	-	Install age in years
`installs.products[].install_age.min`	integer	-
`installs.products[].install_age.max`	integer	-
`installs.products[].install_age_months`	object	-	Install age in months
`installs.products[].install_age_months.min`	integer	-
`installs.products[].install_age_months.max`	integer	-
`installs.products[].intensity`	object	-	Install intensity score
`installs.products[].intensity.min`	integer	-
`installs.products[].intensity.max`	integer	-
`installs.vendors`	array	-	Filter by vendor installs. Array allows combining multiple inclusion methods.
`installs.vendors[].ids` Required	array	-	HG vendor IDs — resolve via get_vendor_information. Invalid IDs are not rejected: they match nothing and return total_count 0.
`installs.vendors[].inclusion_method` Required	string	-
`installs.vendors[].fai`	object	-	Functional Area Intelligence — narrow installs by associated buying-committee departments and/or roles. At least one of departments/roles required.
`installs.vendors[].fai.departments`	object	-	Buying-committee departments (hex IDs).
`installs.vendors[].fai.departments.ids` Required	array	-	Functional-area hex IDs
`installs.vendors[].fai.departments.inclusion_method` Required	string	-
`installs.vendors[].fai.roles`	object	-	Buying-committee roles (hex IDs).
`installs.vendors[].fai.roles.ids` Required	array	-	Functional-area hex IDs
`installs.vendors[].fai.roles.inclusion_method` Required	string	-
`installs.vendors[].product_count`	object	-	Number of products from this vendor installed
`installs.vendors[].product_count.min`	integer	-
`installs.vendors[].product_count.max`	integer	-
`installs.vendors[].install_age`	object	-
`installs.vendors[].install_age.min`	integer	-
`installs.vendors[].install_age.max`	integer	-
`installs.vendors[].install_age_months`	object	-
`installs.vendors[].install_age_months.min`	integer	-
`installs.vendors[].install_age_months.max`	integer	-
`installs.product_categories`	object	-	Filter by product category.
`installs.product_categories.ids` Required	array	-	Product category hex IDs (32-char) — resolve via get_product_category. Invalid IDs are not rejected: they match nothing and return total_count 0.
`installs.product_categories.inclusion_method` Required	string	-
`installs.product_categories.fai`	object	-	Functional Area Intelligence — narrow installs by associated buying-committee departments and/or roles. At least one of departments/roles required.
`installs.product_categories.fai.departments`	object	-	Buying-committee departments (hex IDs).
`installs.product_categories.fai.departments.ids` Required	array	-	Functional-area hex IDs
`installs.product_categories.fai.departments.inclusion_method` Required	string	-
`installs.product_categories.fai.roles`	object	-	Buying-committee roles (hex IDs).
`installs.product_categories.fai.roles.ids` Required	array	-	Functional-area hex IDs
`installs.product_categories.fai.roles.inclusion_method` Required	string	-
`installs.product_categories.install_age`	object	-
`installs.product_categories.install_age.min`	integer	-
`installs.product_categories.install_age.max`	integer	-
`installs.product_categories.install_age_months`	object	-
`installs.product_categories.install_age_months.min`	integer	-
`installs.product_categories.install_age_months.max`	integer	-
`installs.product_attributes`	object	-	Filter by product attributes.
`installs.product_attributes.ids` Required	array	-	Product attribute integer IDs
`installs.product_attributes.inclusion_method` Required	string	-
`installs.product_attributes.install_age`	object	-
`installs.product_attributes.install_age.min`	integer	-
`installs.product_attributes.install_age.max`	integer	-
`installs.product_attributes.install_age_months`	object	-
`installs.product_attributes.install_age_months.min`	integer	-
`installs.product_attributes.install_age_months.max`	integer	-
`installs.country`	object	-	Filter by the install's own country (where the technology is deployed) — NOT the company HQ country.
`installs.country.codes` Required	array	-	ISO 3166-1 alpha-2 codes, e.g. ["US","GB"]
`installs.product_last_verified_date`	object	-	Filter installs by their last-verified date (inclusive YYYY-MM-DD range). At least one of min/max required.
`installs.product_last_verified_date.min`	string	-	Earliest date, inclusive (YYYY-MM-DD).
`installs.product_last_verified_date.max`	string	-	Latest date, inclusive (YYYY-MM-DD).
`intent`	object	-	Intent signal filters — companies showing buying interest on topics or in locations.
`intent.topics`	object	-	Intent topics (buying signal). ALL_PRESENT = company shows signal on all listed topics.
`intent.topics.ids` Required	array	-	Intent topic hex IDs — resolve via list_intent_topics
`intent.topics.inclusion_method` Required	string	-
`intent.signal_score`	string	-	Minimum signal intensity: MEDIUM (score 65–84) or HIGH (score 85–100).
`intent.context_type_ids`	object	-	Intent context type hex IDs.
`intent.context_type_ids.ids` Required	array	-	Hex-encoded IDs
`intent.context_type_ids.inclusion_method` Required	string	-
`intent.buyers_journey_ids`	object	-	Buyer's journey stage hex IDs.
`intent.buyers_journey_ids.ids` Required	array	-	Hex-encoded IDs
`intent.buyers_journey_ids.inclusion_method` Required	string	-
`intent.number_of_cadences`	integer	-	Number of cadences showing intent.
`intent.location`	object	-	Filter by where the intent signal was detected (not company HQ). At least one sub-field required.
`intent.location.country_alpha2s`	array	-
`intent.location.country_alpha2s[].ids` Required	array	-	ISO-2 country codes
`intent.location.country_alpha2s[].inclusion_method` Required	string	-
`intent.location.region_names`	object	-
`intent.location.region_names.ids` Required	array	-	Hex-encoded IDs
`intent.location.region_names.inclusion_method` Required	string	-
`intent.location.state_ids`	object	-
`intent.location.state_ids.ids` Required	array	-	Hex-encoded IDs
`intent.location.state_ids.inclusion_method` Required	string	-
`ai_maturity`	object	-	AI and data maturity filters.
`ai_maturity.ai_maturity_score`	object	-	Composite AI maturity score (0–100).
`ai_maturity.ai_maturity_score.min`	number	-
`ai_maturity.ai_maturity_score.max`	number	-
`ai_maturity.ai_maturity_rank`	object	-	AI maturity rank (1 = highest).
`ai_maturity.ai_maturity_rank.min`	integer	-
`ai_maturity.ai_maturity_rank.max`	integer	-
`ai_maturity.ai_maturity_6m_delta`	object	-	6-month change in AI maturity score.
`ai_maturity.ai_maturity_6m_delta.min`	number	-
`ai_maturity.ai_maturity_6m_delta.max`	number	-
`ai_maturity.genai_intent_score`	object	-	GenAI buying-intent score (0–100).
`ai_maturity.genai_intent_score.min`	integer	-
`ai_maturity.genai_intent_score.max`	integer	-
`ai_maturity.ai_product_use`	boolean	-	true = only companies with an AI product installed.
`ai_maturity.data_maturity_level`	array	-	Data maturity tier.
`ai_maturity.dominant_cloud_provider`	array	-	Dominant cloud provider name(s).
`cloud_maturity`	object	-	Cloud adoption/maturity filters (integer ranges).
`cloud_maturity.aws_products_count`	object	-	Count of AWS products in the stack.
`cloud_maturity.aws_products_count.min`	integer	-
`cloud_maturity.aws_products_count.max`	integer	-
`cloud_maturity.azure_products_count`	object	-	Count of Azure products in the stack.
`cloud_maturity.azure_products_count.min`	integer	-
`cloud_maturity.azure_products_count.max`	integer	-
`cloud_maturity.gcp_products_count`	object	-	Count of GCP products in the stack.
`cloud_maturity.gcp_products_count.min`	integer	-
`cloud_maturity.gcp_products_count.max`	integer	-
`cloud_maturity.cloud_stack_percent_change`	object	-	Change in cloud stack size — may be negative (min/max accept negative bounds).
`cloud_maturity.cloud_stack_percent_change.min`	integer	-
`cloud_maturity.cloud_stack_percent_change.max`	integer	-
`cloud_maturity.current_products_used_cloud_percent`	object	-	Cloud share (%) of current products used.
`cloud_maturity.current_products_used_cloud_percent.min`	integer	-
`cloud_maturity.current_products_used_cloud_percent.max`	integer	-
`cloud_maturity.current_products_used_total_count`	object	-	Total count of current products used.
`cloud_maturity.current_products_used_total_count.min`	integer	-
`cloud_maturity.current_products_used_total_count.max`	integer	-
`cloud_maturity.new_products_used_cloud_percent`	object	-	Cloud share (%) of newly-adopted products.
`cloud_maturity.new_products_used_cloud_percent.min`	integer	-
`cloud_maturity.new_products_used_cloud_percent.max`	integer	-
`corporate_hierarchy`	object	-	DEPRECATED — prefer firmographics.company_level, which takes precedence when both are set. Boolean corporate-hierarchy flags.
`corporate_hierarchy.is_corporate_parent`	boolean	-	true = only corporate parents.
`corporate_hierarchy.is_domestic_parent`	boolean	-	true = only domestic parents.
`corporate_hierarchy.is_global_headquarters`	boolean	-	true = only global headquarters.
`spend`	array	-	Filter by IT spend in a category. Array of clauses — each requires categories + range.
`spend[].categories` Required	object	-	Required. Spend category to filter on.
`spend[].categories.ids` Required	array	-	Spend category hex IDs
`spend[].categories.inclusion_method` Required	string	-
`spend[].range` Required	object	-	Required. Spend range in USD (min and/or max).
`spend[].range.min`	number	-
`spend[].range.max`	number	-
`limit`	integer	-	Maximum companies to return per page (default: 10, hard max: 100). Use 10–50 for exploration; paginate with offset for bulk workflows. total_count reports the full match count regardless of limit.
`offset`	integer	-	Pagination offset (0–24999). total_count gives total matches across all pages.
`sorts`	array	-	Sort order — array of {direction, field}. Sortable: 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) — the ranking signals can be sorted/filtered but are not returned as result columns.
`sorts[].direction` Required	string	-
`sorts[].field` Required	string	-

Required Integrations

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

HG Insights (Data API) (hginsights_v2__data_api)

Use Cases

Build a prospect/ICP list by combining firmographics (size, geography) with an installs filter for a specific product or vendor
Find companies with high AI maturity or GenAI buying intent (ai_maturity filter + sorts on genai_intent_score)
Whitespace analysis — exclude known CRM accounts via company_identifiers.company_ids with NONE_PRESENT, then keep only in-market segments
Segment an industry (firmographics.industries / naics_codes) by which companies have adopted a given technology (installs.products)
Surface intent-showing accounts in a region (intent.topics + intent.location) for targeted outreach

Example Usage

US corporate parents (1K+ employees) running a product

{
  "tool": "search_companies",
  "arguments": {
    "firmographics": {
      "company_level": "CORPORATE_PARENT",
      "country_codes": [
        {
          "ids": [
            "US"
          ],
          "inclusion_method": "ANY_PRESENT"
        }
      ],
      "employees": {
        "min": 1000
      }
    },
    "installs": {
      "products": [
        {
          "ids": [
            12345
          ],
          "inclusion_method": "ANY_PRESENT"
        }
      ]
    },
    "limit": 25
  }
}

High GenAI-intent companies, sorted by intent score

{
  "tool": "search_companies",
  "arguments": {
    "ai_maturity": {
      "genai_intent_score": {
        "min": 85
      }
    },
    "sorts": [
      {
        "field": "genai_intent_score",
        "direction": "DESC"
      }
    ],
    "limit": 50
  }
}

Whitespace — exclude known accounts, keep a tech segment

{
  "tool": "search_companies",
  "arguments": {
    "company_identifiers": {
      "company_ids": {
        "ids": [
          "00000000000000000000000000000001"
        ],
        "inclusion_method": "NONE_PRESENT"
      }
    },
    "installs": {
      "vendors": [
        {
          "ids": [
            67890
          ],
          "inclusion_method": "ANY_PRESENT"
        }
      ]
    },
    "limit": 25
  }
}

Response Format

Field	Type	Description
`companies`	array	Array of matching company results.
`companies[].hg_id`	string	HG Insights company ID (31-32-char hex; leading zeros may be truncated). Pass to enrichment tools (company_firmographic, company_technographic, company_enrich, etc.).
`companies[].name`	string \| null
`companies[].domain`	string \| null
`companies[].domain_normalized`	string \| null
`total_count`	number	Total matching companies across all pages.

company_firmographic, company_technographic, search_industries_naics_sic, get_vendor_information, get_product_category, list_intent_topics

Credits​

Parameters​

Required Integrations​

Use Cases​

Example Usage​

Response Format​

Related Tools​