Skip to main content

Company Hierarchy

Traverse the full UCM corporate ownership tree (multi-level parent/subsidiary hierarchy) for one company, by HG id or domain.

Use this when: you need the ownership TREE — "who owns X", direct or all subsidiaries, sister companies, or entities filtered by country/NAICS/industry. Do NOT use this when: you only need ONE company plus its immediate ultimate-parent — use company_firmographic (company_level + global_hq_* in a single cheaper call). For brand→domain resolution use search_companies.

DEFAULTS: mode="children", depth=1 (omit depth = direct children only, NOT the full subtree), no optional fields, nulls stripped. Bare call = matched node + direct children (id/name/country_code/company_level/parent_id).

SIZE: mode="full" or deep trees on Fortune-500 parents run 100–330+ nodes and can OVERFLOW the response. No client-side truncation — depth is the size lever; start narrow and escalate.

BEWARE: (1) acquired co + mode="full" returns the WHOLE parent family — check company_level, use mode="children" if not "Group HQ". (2) depth is applied BEFORE filters, so filtering at the default depth:1 misses deeper matches — pair every filter with depth:5+. (3) naics_code/industry_name are sparse; null-valued nodes are dropped SILENTLY by those filters.

Recipes: "who owns X"→mode:"parents" · all subs→depth:5 · sister cos→mode:"parents" then mode:"full" on GHQ · firmographic snapshot→depth:0,all_fields:true.

Domain is LITERAL — "alphabet.com" = a UK fleet co, not Google (Alphabet→"abc.xyz", Meta→"meta.com"); sub-brands resolve to their GHQ. Matched node is always kept even if it fails a filter. hierarchy:null = unresolved. Credit: 0.1/node.

Credits​

0.1 — 0.1 per node returned. See the full credit table for how AI Credits work.

Parameters​

NameTypeDefaultDescription
hierarchy Requiredobject-Company identifier — exactly one of id or domain required.
hierarchy.idstring-HG company ID (31–32 alphanumeric characters), e.g. from search_companies or company_firmographic. Resolves faster and more precisely than a domain. Mutually exclusive with domain.
hierarchy.domainstring-Company domain, e.g. "microsoft.com". URLs and "www." are normalized. Matched LITERALLY, not as a brand alias — "alphabet.com" resolves to an unrelated UK fleet company, not Google (use "abc.xyz" for Alphabet, "meta.com" for Meta). For brand→domain resolution, call search_companies first. Mutually exclusive with id.
modestring-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 — filter by company_level client-side for "real" businesses.
selected_fieldsarray-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-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.
country_codesarray-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 country_code 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-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-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. naics_code 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-NAICS code prefixes to EXCLUDE. Applied after naics_codes include. A node is removed only when it has no passing descendants.
industry_namesarray-Case-insensitive substrings to match against each node's industry_name (e.g. ["software","technology"]). A node is kept when its industry_name contains ANY of the provided values. industry_name 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-Case-insensitive substrings to EXCLUDE on industry_name. Applied after industry_names include.
depthinteger-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). Deep trees can be very large (100–330+ nodes on Fortune-500 parents) and may overflow the response — depth is the size lever. 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-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 Phoenix Integrations settings:

  • HG Insights (v2) (hginsights_v2)

Use Cases​

  • Who owns company X? — mode:"parents" walks the ancestor chain up to the Group HQ
  • 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": "get_company_hierarchy",
  "arguments": {
    "hierarchy": {
      "domain": "microsoft.com"
    }
  }
}

Who owns this company?

{
  "tool": "get_company_hierarchy",
  "arguments": {
    "hierarchy": {
      "domain": "linkedin.com"
    },
    "mode": "parents"
  }
}

All subsidiaries, deep

{
  "tool": "get_company_hierarchy",
  "arguments": {
    "hierarchy": {
      "domain": "ibm.com"
    },
    "mode": "children",
    "depth": 5
  }
}

Response Format​

FieldTypeDescription
hierarchyobject | nullRoot node of the corporate hierarchy tree (recursive). Null when no match or tree fully pruned by filters.
countnumberTotal nodes in the returned tree.
total_count_in_scopenumber | nullNodes directly matching country_codes filter (excludes bridge-node connectors). Null when no country filter is active.

company_firmographic, search_companies, company_research, company_technographic