Estimate credit cost for Company Hierarchy

Request

Returns the estimated credit cost for a Company Hierarchy request without consuming any credits or returning data. Use the same parameters as the /hierarchy endpoint.

Security

authorization

Bodyapplication/jsonrequired

Hierarchy estimate 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/estimate

curl -i -X POST \
  https://api.hginsights.com/data-api/v2/companies/hierarchy/estimate \
  -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

Estimate response

Bodyapplication/json

available_creditsintegerrequired

Credits available in the org's active consumption cycle.

Example:1000

credits_estimatenumber, (double)required

Estimated number of credits required to fulfill the hierarchy request.

Example:110

sufficient_creditsbooleanrequired

Whether the org has enough credits to cover the estimate.

Example:true

Response

{
  "available_credits": 1000,
  "credits_estimate": 110,
  "sufficient_credits": true
}