Most companies you look up aren't standalone. They belong to a corporate family with a global headquarters, parent entities, and subsidiaries. POST /companies/hierarchy returns that structure so you can tell a subsidiary from the parent company that owns it, or find every entity under a group HQ.
HG organizes a corporate family into four tiers:
| Tier | Description |
|---|---|
| Global HQ | The top of the corporate family, the ultimate parent entity worldwide |
| Corporate parent | A parent entity below global HQ, typically owning a specific business unit or acquisition |
| Domestic parent | The parent entity within a specific country, relevant for multinational groups where a local entity sits between the corporate parent and in-country subsidiaries |
| Subsidiary / site | A company or site that rolls up to one of the parent tiers above |
A company can be more than one tier at once. Microsoft Corporation is both the Global HQ and (in the US) effectively its own domestic/corporate parent, since it has no entity above it.
POST /data-api/v2/companies/hierarchyIdentify the company by HG ID or domain, then choose a mode to control how much of the tree comes back.
{
"hierarchy": {
"id": "1698C53EBC888758570396E0334965C1"
},
"mode": "full"
}| Parameter | Type | Required | Description |
|---|---|---|---|
hierarchy.id | string | Yes* | HG company ID |
hierarchy.domain | string | Yes* | Company domain |
mode | string | Yes | full, children, or parents (see below) |
format | string | No | tree (default, nested) or list (flat) |
selected_fields | array | No | Fields to return per node, see Fields |
filters | object | No | countries, regions, tiers, max_tier, see Filtering |
sort | array | No | Sort directives, see Sorting |
*Either hierarchy.id or hierarchy.domain is required, not both.
full: returns the entire tree rooted at the Global HQ, regardless of which company you matched. Every node in the corporate family comes back.children: returns the subtree rooted at the company you matched, including all its subsidiaries and their descendants. Use this to see what rolls up under a specific entity.parents: returns only the ancestor chain from the Global HQ down to the matched company, with no siblings or cousins. Use this to find what a specific subsidiary belongs to.
{
"hierarchy": {
"id": "1698C53EBC888758570396E0334965C1",
"name": "Walmart Inc.",
"company_level": "Group HQ",
"parent_id": null,
"selected": false,
"children": []
},
"count": 110
}count is the total number of entities in the returned hierarchy, capped at 1,200 rows. selected marks the node matching your original hierarchy.id/domain lookup, useful when you requested mode: full and need to find your starting point in a larger tree.
parent_id is each node's immediate parent, not the Global HQ. In format: list, every node carries its own parent_id, so you can reconstruct the full tree client-side by linking each company to the node whose id matches its parent_id. That's the same way the diagram above was built.
Need more than the tree? The hierarchy response only returns the fields you select, no firmographics, technographics, or spend. To get the full profile for any company in the tree, take its id and pass it to Enrich Companies:
curl -X POST "https://api.hginsights.com/data-api/v2/companies/enrich" \
-H "Authorization: Bearer $HG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"companies": {
"ids": ["1698C53EBC888758570396E0334965C1"]
},
"fields": ["firmographics", "technographics", "spend"]
}'By default, each node includes id, name, domain, domain_normalized, company_level, and parent_id. Override with selected_fields to get more:
{
"hierarchy": {"domain": "walmart.com"},
"mode": "full",
"selected_fields": [
"id", "name", "domain", "company_level",
"global_hq_id", "global_hq_name",
"corporate_parent_id", "corporate_parent_name",
"domestic_parent_id", "domestic_parent_name",
"revenue_total", "employees_total", "country_code"
]
}Full list: id, name, domain, domain_normalized, company_level, global_hq_id, global_hq_name, corporate_parent_id, corporate_parent_name, domestic_parent_id, domestic_parent_name, parent_id, country_code, country_name, city_name, state_name, revenue_total, revenue_band, employees_total, employees_band, industry_name, naics_code, naics_name, sic_codes, sic_names.
countries, regions, and tiers all require format: list. They return a 400 FILTER_NOT_VALID_FOR_TREE error if used with format: tree (including the default). max_tier works with either format and is the one way to limit tree depth.
{
"hierarchy": {"id": "1698C53EBC888758570396E0334965C1"},
"mode": "full",
"format": "list",
"filters": {
"countries": ["BR"],
"regions": ["EMEA"],
"tiers": ["corporate_parent", "domestic_parent"],
"max_tier": "subsidiary"
}
}| Filter | Description |
|---|---|
countries | ISO 3166-1 alpha-2 country codes. Requires format: list. |
regions | AMER, EMEA, or APAC, OR'd with countries. Requires format: list. |
tiers | Restrict to specific tiers: group_hq, corporate_parent, domestic_parent, subsidiary. Requires format: list. |
max_tier | Restrict to companies at or above this tier (same four values). Works with tree or list, use it to cap how deep a tree goes. |
Naming note: the hierarchy endpoint's own tier values (group_hq, corporate_parent, domestic_parent, subsidiary) use different casing than the company_level filter on Company Search (GLOBAL_HEADQUARTER, CORPORATE_PARENT, DOMESTIC_PARENT, ALL_ENTITIES). They refer to the same concepts, just don't copy-paste one filter's values into the other endpoint.
Sort by revenue_total, employees_total, or name, with control over null placement:
{
"hierarchy": {"id": "1698C53EBC888758570396E0334965C1"},
"mode": "full",
"format": "list",
"sort": [
{"field": "revenue_total", "order": "desc", "nulls": "last"}
]
}/companies/hierarchy consumes credits based on data returned. Preview the cost first with the same request body:
POST /data-api/v2/companies/hierarchy/estimateSee Credits and Usage for the general estimate response shape.