Skip to content
Last updated

Get Corporate Hierarchy

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.

The Hierarchy Tiers

HG organizes a corporate family into four tiers:

Company hierarchy framework showing Global HQ, Corporate Parent, Domestic Parent, and Subsidiary tiers for Microsoft and Alphabet

TierDescription
Global HQThe top of the corporate family, the ultimate parent entity worldwide
Corporate parentA parent entity below global HQ, typically owning a specific business unit or acquisition
Domestic parentThe parent entity within a specific country, relevant for multinational groups where a local entity sits between the corporate parent and in-country subsidiaries
Subsidiary / siteA 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.

Endpoint

POST /data-api/v2/companies/hierarchy

Request

Identify 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"
}
ParameterTypeRequiredDescription
hierarchy.idstringYes*HG company ID
hierarchy.domainstringYes*Company domain
modestringYesfull, children, or parents (see below)
formatstringNotree (default, nested) or list (flat)
selected_fieldsarrayNoFields to return per node, see Fields
filtersobjectNocountries, regions, tiers, max_tier, see Filtering
sortarrayNoSort directives, see Sorting

*Either hierarchy.id or hierarchy.domain is required, not both.

Traversal Modes

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

Response

{
  "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"]
  }'

Fields

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.

Filtering

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"
  }
}
FilterDescription
countriesISO 3166-1 alpha-2 country codes. Requires format: list.
regionsAMER, EMEA, or APAC, OR'd with countries. Requires format: list.
tiersRestrict to specific tiers: group_hq, corporate_parent, domestic_parent, subsidiary. Requires format: list.
max_tierRestrict 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.

Sorting

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"}
  ]
}

Preview Credit Cost

/companies/hierarchy consumes credits based on data returned. Preview the cost first with the same request body:

POST /data-api/v2/companies/hierarchy/estimate

See Credits and Usage for the general estimate response shape.