# 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](/assets/company-hierarchy.bdfff792f52470374b112b8977694d9a3aac606dc8c948ad4ac8990f9639b06d.cfa4363d.svg)

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

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

```json
{
  "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](#fields) |
| `filters` | object | No | `countries`, `regions`, `tiers`, `max_tier`, see [Filtering](#filtering) |
| `sort` | array | No | Sort directives, see [Sorting](#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

```json
{
  "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](/v2/guides/enrichment):

```bash
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:

```json
{
  "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.

```json
{
  "hierarchy": {"id": "1698C53EBC888758570396E0334965C1"},
  "mode": "full",
  "format": "list",
  "filters": {
    "countries": ["BR"],
    "regions": ["EMEA"],
    "tiers": ["corporate_parent", "domestic_parent"],
    "max_tier": "subsidiary"
  }
}
```

table
colgroup
col
col
thead
tr
th
Filter
th
Description
tbody
tr
td
code
countries
td
ISO 3166-1 alpha-2 country codes. Requires 
code
format: list
.
tr
td
code
regions
td
code
AMER
, 
code
EMEA
, or 
code
APAC
, OR'd with 
code
countries
. Requires 
code
format: list
.
tr
td
code
tiers
td
Restrict to specific tiers: 
code
group_hq
, 
code
corporate_parent
, 
code
domestic_parent
, 
code
subsidiary
. Requires 
code
format: list
.
tr
td
code
max_tier
td
Restrict to companies at or above this tier (same four values). Works with 
code
tree
or 
code
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](/v2/guides/find-companies) (`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:

```json
{
  "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](/v2/guides/credits-and-usage#estimating-cost-before-you-call) for the general estimate response shape.