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). Omitting depth returns direct children only (= depth:1 in "children" mode) — it is not unbounded. Pass an explicit depth (e.g. depth:5) to walk deeper.
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 and mode are the primary levers for controlling both spend and payload size. The tool does not truncate responses client-side — there is no truncated/totalNodes signal — so a large mode:"full" or deep tree can overflow the model's token budget. Start narrow (default depth:1, mode:"children") and escalate deliberately.

Traversal Modes

Mode	Root of returned tree	Use when
"children" (default)	The matched node	You want the matched company's subsidiaries. Omitting depth (or depth:1) returns direct children only; pass depth:5 for deeper 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: depth → country include → country exclude → NAICS include → NAICS exclude → industry include → industry exclude. Depth is applied first (to the raw upstream tree), then the filters run on the depth-capped result — so a shallow depth removes deeper nodes before any filter sees them. Pair filters with depth:5+ so matches lower in the tree aren't cut off before filtering.

• 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.
• Null-valued nodes are excluded: while industry_names / naics_codes (or their exclude_* counterparts) are active, nodes whose value in the filtered field is null are dropped upstream — these fields are sparse. Pair the filter with depth:5+ so matches deeper in the tree aren't missed, and treat a gap as "no non-null match," not "no company."

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.

Related Tools

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

Next Steps

• View all tools
• Read best practices