HG Search Companies

Build company lists from HG data with search_companies: pick the right filter groups, resolve every ID first, and enrich the survivors before you compare or rank them.

When to use

• A workflow needs a prospect list, target-account list, ICP segment, TAM count or whitespace list.
• A prompt asks "which companies use X", "who is researching Y" or "companies like Z in region W".
• You need to resolve a company name to an hg_id and have no domain.

Don't use it when you already have the domain or hg_id: call company_firmographic (or the section tool you need) directly.

Tools you'll touch

• search_companies: company discovery by criteria. Returns identity only. Cost: 1 per 100 companies returned (a 25-row page costs 0.25). Cached 7 days.
• search_industries_naics_sic, get_vendor_information, product_search_and_enrich (search), get_product_category, get_product_attribute, list_intent_topics, list_fai_departments: free ID lookups. Resolve every ID with them first.
• company_firmographic: enrich survivors (0.1 per company, batches of up to 25).

The filter groups

Groups are separate top-level parameters combined with AND. Inside a group, each array of clauses also combines with AND, and each clause carries ids plus an inclusion_method: ANY_PRESENT (has at least one), ALL_PRESENT (has all) or NONE_PRESENT (has none).

Group	Main Keys	Notes
firmographics	company_level, country_codes, region_names, state_ids, employees{min,max}, revenue{min,max}, industries, naics_codes, sic_codes	country_codes is HQ country. Revenue is USD, an HG estimate
installs	products, vendors, product_categories, product_attributes, country, product_last_verified_date{min,max}	Product and vendor clauses take intensity{min,max}, install_age (years), install_age_months and fai{departments,roles}; vendors also take product_count
intent	topics, signal_score, location, context_type_ids, buyers_journey_ids, number_of_cadences	signal_score is "MEDIUM" (65 to 84) or "HIGH" (85 to 100)
spend	array of {categories{ids,inclusion_method}, range{min,max}}	Range in USD
ai_maturity	ai_maturity_score, ai_maturity_rank, ai_maturity_6m_delta, genai_intent_score, ai_product_use, data_maturity_level, dominant_cloud_provider	Ranges, booleans and arrays
cloud_maturity	aws_products_count, azure_products_count, gcp_products_count, cloud_stack_percent_change, current_products_used_cloud_percent, and others	Integer ranges; percent change may be negative
company_identifiers	name, domains, company_ids, company_ids_including_corporate_relatives	NONE_PRESENT excludes known accounts; the "corporate relatives" form also excludes or includes each company's whole family

corporate_hierarchy is deprecated. Use firmographics.company_level.

Rules

1. Always set firmographics.company_level. Without it every entity level comes back, so subsidiaries and sites of the same group fill the list. Use "CORPORATE_PARENT" for brand-level accounts and "GLOBAL_HEADQUARTER" for ultimate parents. Other values: "DOMESTIC_PARENT", "ALL_ENTITIES". Output records label levels differently ("Group HQ", "Corporate Parent", "Subsidiary"); see hg-subsidiary-handling.
2. Combine at least two filter groups. A firmographic-only filter (a country, a size range) matches hundreds of thousands of records. Pair it with installs, intent, spend, ai_maturity or a company_identifiers exclusion.
3. Resolve every ID with a free lookup first. Invalid IDs are not rejected: they match nothing and return total_count: 0. A zero after a guessed ID means bad input, not an empty market. Product, vendor, attribute and industry IDs are integers; category, topic, FAI, state, NAICS-id and company IDs are 32-character hex.
4. The output is identity only: companies[]{hg_id, name, domain, domain_normalized} plus total_count. No size, industry or scores, even when you filtered or sorted on them. Enrich the survivors with company_firmographic (or the section tool you need) before comparing. domain can be empty, so fan out by hg_id, never by domain.
5. Resolve names by domain first. company_identifiers.name is a case-insensitive token-substring match over all entity names: every token must appear somewhere in a name. A well-known brand can return around a thousand matches with the real company absent from the first page. If you have a domain, use company_identifiers.domains with bare domains ("acme.com", not a URL: this filter doesn't normalise). If you only have a name, add company_level and a second group such as country_codes, then confirm with company_firmographic.
6. Industry codes. naics_codes[].codes only matches 6-digit NAICS 2012 leaves; 2-, 3-, 4- and 5-digit rollups and codes introduced in NAICS 2017 or 2022 match nothing. Expand a sector first with search_industries_naics_sic (q:"<prefix or name>", taxonomy:"naics", naics_leaf_only:true) and pass all the leaves. For SIC, pass sic_standard_code ("7372"), not sic_code ("I7372"). The HG industry taxonomy (industries, 23 buckets) has no Software bucket; use NAICS or SIC for software and IT services.
7. Three geographies, three meanings. firmographics.country_codes = HQ country; installs.country.codes = where the install is deployed; intent.location = where the signal was seen. firmographics.region_names takes literals "AMER", "APAC", "EMEA", "LATAM" (ANY_PRESENT only). state_ids take 32-character hex ids, not names or abbreviations; literal state names match nothing.
8. Sorting is limited. sorts[]{field, direction} accepts id, name, domain, domain_normalized and the AI or cloud signals (ai_maturity_score, ai_maturity_rank, ai_maturity_6m_delta, genai_intent_score, current_products_used_cloud_percent, cloud_stack_percent_change). There is no sort by employees, revenue, intensity or spend. For "top accounts by usage", filter with an intensity{min} range, then rank after a batched company_technographic call, reading intensity within each company (hg-technographic).
9. Paging. limit defaults to 10, max 100; offset runs 0 to 24,999. The default order is unspecified, so set sorts (e.g. id ascending) whenever you page to keep pages stable. If total_count exceeds 25,000, narrow the filters instead of paging.
10. Intensity is unbounded. installs.products[].intensity is an all-time count of detection days, not a 0 to 100 score. Use a min only to drop trace installs, and set it relative to the company size you're targeting.

Worked examples

IDs below are placeholders. Resolve real ones first.

Brand-level EMEA accounts running a product but not its competitor

{
  "firmographics": {
    "company_level": "CORPORATE_PARENT",
    "region_names": {"ids": ["EMEA"], "inclusion_method": "ANY_PRESENT"},
    "employees": {"min": 1000, "max": 10000}
  },
  "installs": {
    "products": [
      {"ids": [11111], "inclusion_method": "ANY_PRESENT", "intensity": {"min": 50}},
      {"ids": [22222], "inclusion_method": "NONE_PRESENT"}
    ]
  },
  "sorts": [{"field": "id", "direction": "ASC"}],
  "limit": 50
}

US industry segment, new adopters of a vendor, excluding current customers and their families

{
  "firmographics": {
    "company_level": "CORPORATE_PARENT",
    "country_codes": [{"ids": ["US"], "inclusion_method": "ANY_PRESENT"}],
    "naics_codes": [{"codes": ["333111", "333112"], "inclusion_method": "ANY_PRESENT"}]
  },
  "installs": {
    "vendors": [{"ids": [33333], "inclusion_method": "ANY_PRESENT", "install_age_months": {"max": 12}}]
  },
  "company_identifiers": {
    "company_ids_including_corporate_relatives": {
      "ids": ["0000000000000000000000000000000A", "0000000000000000000000000000000B"],
      "inclusion_method": "NONE_PRESENT"
    }
  },
  "limit": 100
}

Ultimate parents with high intent on a topic, signal seen in Germany

{
  "firmographics": {"company_level": "GLOBAL_HEADQUARTER", "employees": {"min": 5000}},
  "intent": {
    "topics": {"ids": ["0123456789abcdef0123456789abcdef"], "inclusion_method": "ANY_PRESENT"},
    "signal_score": "HIGH",
    "location": {"country_alpha2s": [{"ids": ["DE"], "inclusion_method": "ANY_PRESENT"}]}
  },
  "limit": 25
}

Resolve a name you have no domain for

{
  "company_identifiers": {"name": "acme robotics"},
  "firmographics": {
    "company_level": "CORPORATE_PARENT",
    "country_codes": [{"ids": ["GB"], "inclusion_method": "ANY_PRESENT"}]
  },
  "limit": 10
}

Then pass the candidate hg_ids to company_firmographic and pick by name, domain, country and size. Confirm with the user if two candidates remain.

After the search

1. Read total_count before paging: it sizes the market and the cost (1 credit per 100 rows you pull).
2. Enrich survivors in batches of 25 with company_firmographic (hg_ids), matching results by company_id, never by position.
3. Rank and filter on the enriched fields, not on the search order, which is unspecified unless you set sorts.

Common pitfalls

1. Leaving out company_level. The list fills with sites and subsidiaries of the same few groups.
2. Passing a 4-digit NAICS code. It matches nothing. Expand to 6-digit 2012 leaves.
3. Reporting "no companies" after a guessed ID. Invalid IDs silently match nothing. Resolve with the free lookups.
4. Treating name search as fuzzy or semantic. It is a token-substring match. Resolve by domain first.
5. Ranking by size or usage from the search result. Those fields aren't returned or sortable. Enrich first.
6. Mixing up HQ, install and intent geography. Pick the one the question is about.
7. Paging without sorts. Pages are not stable without an explicit sort.

Reference

• V2 tool docs: https://phoenix.hginsights.com/docs/mcp-tools/v2/search-companies
• V2 tool docs: https://phoenix.hginsights.com/docs/mcp-tools/v2/search-industries-naics-sic
• Full docs for LLMs: https://phoenix.hginsights.com/docs/llms-full.txt
• Related skills: hg-mcp-calling-rules, hg-firmographic, hg-subsidiary-handling, hg-peer-cohort-selection, hg-technographic, hg-intent