Get Company Hierarchy

Traverse the UCM corporate hierarchy tree for a company by HG ID or domain. Walk the matched node's subtree, expand to the full Group HQ family, or return the ancestor chain up to the GHQ.

Tool key: get_company_hierarchy

Parameters

Name	Type	Required	Default	Description
`hierarchy.id`	string	Conditional	-	HG company ID (31–32 alphanumeric). Provide exactly one of `id` or `domain`.
`hierarchy.domain`	string	Conditional	-	Company domain, e.g. `"microsoft.com"`. Interpreted literally — not a brand alias.
`mode`	enum	No	`"children"`	Traversal mode: `"children"`, `"full"`, or `"parents"` (see below).
`depth`	number	No	`1` (in `"children"` mode)	Cap on levels of children counted from the root of the returned tree (0–20). Omit for unbounded.
`selected_fields`	string[]	No	-	Optional fields to load on each node beyond the always-present set. Max 20.
`all_fields`	boolean	No	`false`	Escape hatch — load every optional field. Increases payload size significantly.
`country_codes`	string[]	No	-	ISO alpha-2 country codes to INCLUDE. Populates `total_count_in_scope`.
`exclude_country_codes`	string[]	No	-	ISO alpha-2 country codes to EXCLUDE (applied after include).
`naics_codes`	string[]	No	-	NAICS code prefixes to INCLUDE (e.g. `["51"]`).
`exclude_naics_codes`	string[]	No	-	NAICS prefixes to EXCLUDE.
`industry_names`	string[]	No	-	Case-insensitive substrings to match against `industry_name`.
`exclude_industry_names`	string[]	No	-	Case-insensitive substrings to exclude.
`include_nulls`	boolean	No	`false`	Keep fields whose values are null (including `parent_id:null` on the root).

Required Integrations

hginsights_v2

Credits

0.1 credits per node returned (dynamic; computed after the upstream response). Example: a 5-node subtree costs 0.5 credits; a 200-node Fortune-500 tree costs 20 credits. An empty/unresolved hierarchy (hierarchy: null) costs 0.

Because cost scales with node count, depth is the primary lever for controlling spend. The tool soft-truncates very large responses client-side to keep payloads within model token limits — start narrow (default depth:1, mode:"children") and escalate as needed.

Traversal Modes

Mode	Root of returned tree	Use when
`"children"` (default)	The matched node	You want the matched company's subsidiaries. Pair with `depth:1` for direct children, `depth:5` or omit for all descendants.
`"full"`	The Group HQ (GHQ)	You want the entire corporate family. The matched node is flagged `selected:true`.
`"parents"`	Ancestor chain	You want only the upward path from the matched node to its GHQ.

Beware: mode:"full" on an acquired company expands to the WHOLE parent family (e.g. varian.com → Siemens AG). Check company_level / global_hq_name on the matched node before escalating to "full".

Filters

Filters are applied in this order: country include → country exclude → NAICS include → NAICS exclude → industry include → industry exclude → depth.

country_codes pruning keeps nodes whose country_code is in the list. Ancestors outside the filter are retained as bridge nodes when they have a passing descendant — use country_code on each node to distinguish bridges from matches. The matched (selected:true) node is always retained, even if it fails the filter.
Within a parameter, values combine with OR; across parameters they combine with AND.
naics_code and industry_name are auto-fetched when their filters are active — no need to add them to selected_fields.

Response

The tool returns a passthrough of upstream hierarchy nodes — the shape mirrors the HG /v2/organizations/hierarchy response, so new upstream fields flow through without code changes.

hierarchy — root node of the returned tree, or null when the id/domain did not resolve upstream. Each node has id, name, country_code, company_level, parent_id, and a recursive children[] (omitted when empty). The matched node carries selected: true. Optional fields appear only when requested via selected_fields / all_fields.
count — total nodes in the returned tree.
total_count_in_scope — nodes in the returned tree that match country_codes (excludes bridge connectors). Populated only when a country_codes INCLUDE filter is active.

company_level values: "Group HQ", "Corporate Parent", "Domestic Parent", "Site", "Subsidiary".

Example: direct subsidiaries

{
  "tool": "get_company_hierarchy",
  "parameters": {
    "hierarchy": { "domain": "microsoft.com" }
  }
}

Returns Microsoft and its direct children (depth:1, default mode) with id/name/country_code/company_level/parent_id only.

Example: European subsidiaries with revenue

{
  "tool": "get_company_hierarchy",
  "parameters": {
    "hierarchy": { "domain": "siemens.com" },
    "mode": "children",
    "country_codes": ["DE", "FR", "IT", "ES", "NL"],
    "depth": 5,
    "selected_fields": ["revenue_total", "employees_total", "industry_name"]
  }
}

Example: who owns this company?

{
  "tool": "get_company_hierarchy",
  "parameters": {
    "hierarchy": { "domain": "varian.com" },
    "mode": "parents"
  }
}

Returns only the ancestor chain from Varian up to its Group HQ (Siemens AG).

Error Handling

Company not found — domain / hg_id did not resolve. Verify the value and try again; for brand intents (e.g. "Alphabet Inc.") resolve via search_companies first and pass the returned hg_id.
Missing integration — the organization has no hginsights_v2 credentials configured.

search_companies — resolve a brand or natural language query to an hg_id before calling this tool.
company_firmographic — third-party firmographic snapshot for any node in the returned tree.

Parameters​

Required Integrations​

Credits​

Traversal Modes​

Filters​

Response​

Example: direct subsidiaries​

Example: European subsidiaries with revenue​

Example: who owns this company?​

Error Handling​

Related Tools​

Next Steps​