Company Hierarchy

company_hierarchy — corporate ownership tree / subsidiaries / parent company / who owns X / sister companies. Traverses the UCM tree for ONE company by domain or hg_id.

company_domain IS LITERAL, not a brand alias: "alphabet.com" = a UK fleet subsidiary, NOT Google — a wrong-but-valid domain returns confident WRONG data with NO error. Holding domains: Alphabet="abc.xyz", Meta="meta.com". No known domain? Resolve via search_companies FIRST.

USE WHEN: "who owns X?", subsidiaries, parent chain, or sister companies. Do NOT use for: firmographics only → company_firmographic; a full tech/intent/spend profile → company_enrich; a list of companies → search_companies.

DEFAULTS: mode="children", depth=1 (direct children only). MODES: "children"=subtree at matched node · "full"=whole tree from GHQ · "parents"=ancestor chain up to GHQ.

BEWARE: (1) Fortune-500 parents return 100–330+ nodes — depth is the size lever. (2) mode:"full" returns the WHOLE parent family; check company_level. (3) depth applies BEFORE filters — pair country_codes/naics/industry filters with depth:5+. (4) UCM may return DUPLICATE nodes; dedupe by id.

RECIPES: "who owns X?"→mode:"parents" · all subs→depth:5 · EU entities→country_codes:["DE","FR"],depth:5. Trim returned columns with selected_fields.

Matched node always kept even if it fails a filter. hierarchy:null → read no_match_reason. mode:"parents"+already_at_ghq:true → company IS the GHQ. Credit: 0.1/node.

Parameters

Name	Type	Default	Description
`company_domain`	string	-	Company domain, e.g. "microsoft.com". Either company_domain or hg_id is required; if both are provided, hg_id takes precedence. Interpreted literally — not a brand alias. Protocol prefixes, leading www., and trailing paths are stripped automatically; case is normalized.
`hg_id`	string	-	HG Insights company ID (31-32 alphanumeric characters). Either company_domain or hg_id is required. When provided, this overrides company_domain. Obtain from a previous search_companies result.
`mode`	string	`children`	Default "children". "children" returns the subtree rooted at the MATCHED node — the matched node is the root, so depth:1 = direct children. "full" returns the complete subtree rooted at the GHQ; matched node marked selected:true (usually NOT the root — "google.com" → tree rooted at Alphabet Inc.). "parents" returns the ancestor chain from matched node up to the GHQ; returns just the node itself if it is already the GHQ. company_level values: "Group HQ", "Corporate Parent", "Domestic Parent", "Site", "Subsidiary". "Domestic Parent" nodes are often regional/legal shells. There is NO server-side company_level filter param — to keep only "real" businesses, filter the returned nodes client-side on the always-present company_level field.
`selected_fields`	array	-	Optional fields to include on each node beyond the always-present set (id, name, children, country_code, company_level, parent_id; plus selected:true on the matched node). Default null = no optional fields are returned. Always-present fields (country_code, company_level, parent_id) are accepted here as no-ops. Prefer a short explicit list; use all_fields:true only when you genuinely need every field. Many optional fields are sparse — nulls stripped unless include_nulls:true. Allowed values: domain, domain_normalized, global_hq_id, global_hq_name, corporate_parent_id, corporate_parent_name, domestic_parent_id, domestic_parent_name, country_name, city_name, state_name, employees_total, employees_band, revenue_total, revenue_band, industry_name, naics_code, naics_name, sic_codes, sic_names, country_code, company_level, parent_id.
`all_fields`	boolean	`false`	When true, every optional field is loaded on each node (equivalent to listing all values in selected_fields). Default false. Significantly increases payload size; prefer selected_fields with a short explicit list. Combine with depth:0 for a single-node firmographic snapshot without traversing children — but if you only need firmographics (no tree), company_firmographic is faster and cheaper.
`country_codes`	array	-	ISO alpha-2 country codes to INCLUDE (e.g. ["DE","GB"]). Ancestor nodes outside the filter are kept as BRIDGE NODES when they have a passing descendant — use the country_code node field to distinguish bridges from matches. Supplying this populates total_count_in_scope in the response (count of matching nodes, excludes bridges). Filter order: depth → country incl → country excl → naics incl → naics excl → industry incl → industry excl (depth is applied FIRST, then the filters run on the depth-capped tree). Within a param, values are OR; across params, AND.
`exclude_country_codes`	array	-	ISO alpha-2 country codes to EXCLUDE from the tree (e.g. ["US"]). Applied after country_codes include. A node is removed only when it has no passing descendants.
`naics_codes`	array	-	NAICS code prefixes to INCLUDE (e.g. ["51"] for Information, ["54","541810"] for Professional Services). Prefix-matched: "54" matches any 6-digit code starting with 54. Bridge-node ancestors outside the filter are retained as connectors. The naics_code node field is auto-fetched — no need to add it to selected_fields. Nodes whose naics_code is null are EXCLUDED while this filter is active (the field is sparse). Pair with depth:5+ so matches deeper in the tree aren't missed.
`exclude_naics_codes`	array	-	NAICS code prefixes to EXCLUDE. Applied after naics_codes include. A node is removed only when it has no passing descendants.
`industry_names`	array	-	Case-insensitive substrings to match against each node's industry_name field (e.g. ["software","technology"]). A node is kept when its industry_name contains ANY of the provided values. The industry_name node field is auto-fetched when supplied. Nodes whose industry_name is null are EXCLUDED while this filter is active (the field is sparse). Pair with depth:5+ so matches deeper in the tree aren't missed.
`exclude_industry_names`	array	-	Case-insensitive substrings to EXCLUDE on industry_name. Applied after industry_names include.
`depth`	integer	-	Cap on levels of children, counted from the ROOT of the returned tree. In mode:"children" (default) root = matched node: depth:0 = node only, depth:1 = direct children (DEFAULT), depth:2 = two levels. In mode:"full" root = GHQ: depth:0 = GHQ only. When omitted, the API returns direct children only — equivalent to depth:1 in mode:"children". Omitting depth does NOT return the full subtree; to walk deeper, pass an explicit depth (e.g. depth:5). WARNING: depth:1 is NOT a size guarantee — a Fortune-500 GHQ can have 60-150+ direct subsidiaries (e.g. Cisco returned 113 nodes, Salesforce 62 at depth:1). Deep trees can be very large (100–330+ nodes on Fortune-500 parents) and may overflow the response — depth is the size lever. Rough budget: ~200–400 bytes/node at default fields, ~3× with all_fields:true. IMPORTANT: depth is applied BEFORE the filters (upstream order: depth → country → naics → industry), so a shallow depth removes deeper nodes before any filter runs — filtering at the default depth:1 only ever sees the top level and misses matches lower in the tree. Always pair filter calls with an explicit depth:5+.
`include_nulls`	boolean	`false`	If true, fields with null values are kept on each node (including parent_id:null on the root and selected:false on non-matching nodes). Default false strips nulls and selected:false — significantly reduces payload size on large trees. Use include_nulls:true only when you need to distinguish "field absent" from "field present but null".

Required Integrations

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

HG Insights (Data API) (hginsights_v2_data_api)

Use Cases

Who owns company X? — mode:"parents" walks the ancestor chain up to the Group HQ (already_at_ghq:true means X is itself the GHQ)
List a company's direct subsidiaries — default call (mode:"children", depth:1)
Map every subsidiary in a corporate family — mode:"children" with depth:5
Find sister companies of a subsidiary — mode:"parents" to the GHQ, then mode:"full" on it
Which EU entities does this company own? — country_codes:["DE","FR",...] with depth:5

Example Usage

Direct subsidiaries (defaults)

{
  "tool": "company_hierarchy",
  "arguments": {
    "company_domain": "microsoft.com"
  }
}

Who owns this company?

{
  "tool": "company_hierarchy",
  "arguments": {
    "company_domain": "linkedin.com",
    "mode": "parents"
  }
}

All subsidiaries, deep

{
  "tool": "company_hierarchy",
  "arguments": {
    "company_domain": "ibm.com",
    "mode": "children",
    "depth": 5
  }
}

Response Format

Field	Type	Description
`hierarchy`	object \| null	Root node of the corporate hierarchy tree (recursive; node fields are verbatim upstream snake_case). Null when no match or tree fully pruned by filters — check no_match_reason for the cause.
`node_count`	number	Total nodes in the returned tree.
`total_count_in_scope`	number \| null	Nodes directly matching the country_codes filter (excludes bridge-node connectors). Null when no country filter is active.
`no_match_reason`	string	Human-readable explanation when hierarchy is null. Either "no UCM record for this identifier — try search_companies to verify" or "all nodes pruned by active filters — widen filters or increase depth".
`already_at_ghq`	boolean	True (only present in mode:"parents") when the matched company is already the Group HQ — it has no parent chain above it.

company_firmographic, company_enrich, search_companies, company_technographic

Parameters​

Required Integrations​

Use Cases​

Example Usage​

Response Format​

Related Tools​

Parameters

Required Integrations

Use Cases

Example Usage

Response Format

Related Tools