---
title: "Company hierarchy"
description: "POST /v1/company/hierarchy — immediate and ultimate parent, plus a capped subsidiary list."
canonical: "https://kingminos.com/docs/api/company-hierarchy/"
sourceKind: "source-mdx"
---

import TryItLink from '../../../../components/docs/TryItLink.astro';
import CapabilityPricing from '../../../../components/docs/CapabilityPricing.astro';
import Credits from '../../../../components/docs/Credits.astro';

`POST https://api.kingminos.com/v1/company/hierarchy`

<TryItLink method="POST" path="/v1/company/hierarchy" />

One decision: who owns this company, and who sits under it. Send a company subject: `domain`, `website`, `email`, or `name`. Optional `country` scopes registry reads.

```bash
curl 'https://api.kingminos.com/v1/company/hierarchy' \
  -H 'Authorization: Bearer <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "domain": "lidl.com",
    "name": "Lidl US",
    "external_ref": "account-demo-1"
  }'
```

## What comes back

The envelope is schema version `2`. Automations branch on these layers:

| Layer | Fields | Use |
| --- | --- | --- |
| Control | `answer.outcome`, `es_decision`, `answer.confidence` | Whether to trust the family. |
| Parents | `result.immediate_parent_*`, `result.ultimate_parent_*` | Roll-up targets. |
| Tree | `result.subsidiaries`, `result.hierarchy_depth`, `result.truncated` | Subsidiary list (capped). |
| Identifiers | `result.zoominfo_company_id`, `result.wikidata_id`, `result.lei`, `result.identifiers` | CRM and enrichment keys. |
| Audit | `result.sources`, `trace` when `X-Router-Explain: full` | Humans and logs. |

`answer.outcome` on this capability is `subsidiary`, `ultimate_parent`, or `no_decision`. There is no `standalone` outcome — a clean subject with no parent and no subsidiaries is `no_decision`.

| Result | `answer.outcome` | Meaning |
| --- | --- | --- |
| The subject has a known parent | `subsidiary` | Immediate and/or ultimate parent fields are populated. |
| The subject is the top of the tree | `ultimate_parent` | No parent above the matched unit. |
| Not enough hierarchy data | `no_decision` | Miss, timeout, or empty tree. |

`result.subsidiaries[]` entries carry `name`, `domain`, `zoominfo_company_id`, and `wikidata_id` when the source supplies them. `result.family_tree_size` is the raw node count before truncation (`null` on `speed`). `result.truncated` is `true` when the subsidiary list was capped.

You are only charged when a parent answer is delivered. A miss, timeout, or error bills **0**. Business misses stay HTTP `200`.

## Paths and price

Omit `routing.path` to use `balance`. A top-level `path` / `preset` is the same as `routing.path` / `routing.preset`; nested wins when both are sent.

| `path` | What it does | Credit cap | Credits on a delivered answer |
| --- | --- | --- | --- |
| `speed` | Public registry data only. | 0 | 0 |
| `balance` (default) | `speed` plus a corporate-hierarchy lookup on a full match. | 1 | 0–1 |
| `accuracy` | Same billing as `balance` with a higher-confidence ladder. | 1 | 0–1 |

`coverage` is not supported — `400 invalid_routing`.

**Aliases:** `value`, `fast` and `auto` mean `balance`.

Default paths run on KingMinos keys. Vendor fields such as `result.zoominfo_company_id` appear on the answer when the source returns them — connect [Vendor keys](/docs/api/credentials/) when you rely on BYOK for stampable company ids.

## Input

The body accepts nullable `name`, `domain`, `website`, `email`, and `country`, plus:

- `external_ref` — client correlation key, echoed on the run.
- `routing` — `path`, optional `only`, `ignore`, `max_provider_credits`.
- `schema_version` — pin `"2"` or omit.
- `dry_run` — accepted; writers stay skipped.

## Explain and cache

Prefer `X-Router-Explain: minimal` on CRM callouts — it is an alias of the clean envelope. Use `full` when you need `trace.attempts`.

`Idempotency-Key` replays a completed run. Rotating that header is what forces a new decision; explain flags do not.

Not in `openapi.es.yaml` — Salesforce External Services does not import this capability.

## Errors

`400` with one of:

- `validation_failed`
- `domain_website_mismatch`
- `invalid_routing` (including `coverage` on this capability)
- `invalid_compliance`
- `invalid_explain`
- `invalid_schema` / `unsupported_schema`

`401` unauthorized. `403` scope denied. `429` rate or budget limits — the run was not started.
