Company Hierarchy

Request

Returns the company hierarchy as a nested tree (format: tree, default) or a flat list (format: list).

Use mode to control the traversal: full returns the entire tree from Group HQ, children returns the subtree rooted at the matched company, parents returns the ancestor chain from Group HQ to the matched company.

Filter compatibility by format: the countries, regions, and tiers filters require format: list and return HTTP 400 (FILTER_NOT_VALID_FOR_TREE) when used with format: tree (including the default when format is omitted). The max_tier filter works with both tree and list and can be used to limit tree depth.

Security

authorization

Bodyapplication/jsonrequired

Hierarchy Request

filtersobject

Optional filters applied to the hierarchy results. countries, regions, and tiers require format: list and are rejected with HTTP 400 (FILTER_NOT_VALID_FOR_TREE) when used with format: tree. max_tier works with both tree and list.

Example:

{
  "countries": [
    "BR"
  ],
  "regions": [
    "EMEA"
  ]
}

formatstring

Controls the response shape: tree (nested) or list (flat). Defaults to tree.

The countries, regions, and tiers filters require format: list; sending any of them with format: tree (including the default when format is omitted) returns HTTP 400 (FILTER_NOT_VALID_FOR_TREE). The max_tier filter works with both formats and can be used to limit tree depth.

Default:"tree"

Enum:"tree""list"

Example:"list"

hierarchyobjectrequired

Identifies a company by ID or domain (mutually exclusive).

Example:

{
  "id": "1698C53EBC888758570396E0334965C1"
}

modestringrequired

Controls which part of the corporate hierarchy to return.

full — returns the entire tree rooted at the Group HQ, regardless of which company was matched. Every node in the corporate family is included.
children — returns a subtree rooted at the matched company, including all of its subsidiaries and their descendants.
parents — returns only the ancestor chain from the Group HQ down to the matched company (no siblings or cousins).

Enum:"full""children""parents"

Example:"full"

selected_fieldsArray of strings

Optional field override. When provided, only these fields (plus always-present selected) are returned.

Default:["id","name","domain","domain_normalized","company_level","parent_id"]

Items Enum:"id""name""domain""domain_normalized""company_level""global_hq_id""global_hq_name""corporate_parent_id""corporate_parent_name""domestic_parent_id"

Example:

[
  "id",
  "name",
  "domain",
  "company_level"
]

sortArray of objects

Optional list of sort directives applied to the hierarchy results.

POST

/data-api/v2/companies/hierarchy

curl -i -X POST \
  https://api.hginsights.com/data-api/v2/companies/hierarchy \
  -H 'Authorization: Bearer <YOUR_API_KEY_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filters": {
      "countries": [
        "BR"
      ],
      "regions": [
        "EMEA"
      ]
    },
    "format": "list",
    "hierarchy": {
      "id": "1698C53EBC888758570396E0334965C1"
    },
    "mode": "full",
    "selected_fields": [
      "id",
      "name",
      "domain",
      "company_level"
    ]
  }'

Responses

Hierarchy Response

Bodyapplication/json

countinteger

Total number of entities in the hierarchy (DB row count, capped at 1200).

Example:110

hierarchyobject or null

Root node of the hierarchy tree, or null if the company was not found.

Example:

{
  "children": [],
  "company_level": "Group HQ",
  "id": "1698C53EBC888758570396E0334965C1",
  "name": "Walmart Inc.",
  "parent_id": null,
  "selected": false
}

metaobject

Metadata about the hierarchy results.

Response

{
  "count": 110,
  "hierarchy": {
    "children": [],
    "company_level": "Group HQ",
    "id": "1698C53EBC888758570396E0334965C1",
    "name": "Walmart Inc.",
    "parent_id": null,
    "selected": false
  }
}