Skip to main content

Company Hierarchy

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.

Traverse the UCM corporate ownership tree (parents, subsidiaries, sister companies) for ONE company by HG id or domain.

company_domain IS LITERAL, never 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 the brand via search_companies FIRST.

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

DEFAULTS: mode="children", depth=1 (direct children only, NOT the full subtree), no optional fields, nulls stripped. MODES: "children"=subtree at matched node · "full"=whole tree from GHQ (matched=selected:true) · "parents"=ancestor chain up to GHQ.

BEWARE: (1) Fortune-500 parents return 100–330+ nodes and can OVERFLOW — depth is the size lever. (2) acquired co + mode:"full" returns the WHOLE parent family; check company_level, use mode:"children" if not "Group HQ". (3) depth applies BEFORE filters — pair country_codes/naics/industry filters with depth:5+. (4) UCM may return DUPLICATE nodes; dedupe by id, not name.

RECIPES: "who owns X?"→mode:"parents" · all subs→depth:5 · EU entities→country_codes:["DE","FR"],depth:5 · revenue→depth:0,selected_fields:["revenue_total"].

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

Parameters​

NameTypeRequiredDefaultDescription
company_domainstring❌ No-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_idstring❌ No-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.
modestring❌ NochildrenDefault "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_fieldsarray❌ No-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_fieldsboolean❌ NofalseWhen 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_codesarray❌ No-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_codesarray❌ No-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_codesarray❌ No-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_codesarray❌ No-NAICS code prefixes to EXCLUDE. Applied after naics_codes include. A node is removed only when it has no passing descendants.
industry_namesarray❌ No-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_namesarray❌ No-Case-insensitive substrings to EXCLUDE on industry_name. Applied after industry_names include.
depthinteger❌ No-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_nullsboolean❌ NofalseIf 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​

  • 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
  }
}

company_firmographic, company_enrich, search_companies, company_technographic