# Entity Hierarchy API

AI-researched corporate hierarchy for any resolved entity. Ownership chains, parent companies, and the ultimate controlling entity, with evidence sources.

Map the full corporate structure behind an entity: who owns it, through which
intermediate holding companies, and who ultimately controls it. AI agents research the
structure from registries, filings, and public sources, and return it with evidence URLs.

## How it works

Hierarchy research is asynchronous and keyed by the SIQ entity ID from
[entity resolution](/docs/apis/entity-resolution):

1. **Submit** research with `POST /v1/entity/{entity_id}/hierarchy`. If research is already
   running for that entity, the existing request is returned instead of a duplicate.
2. **Poll** `GET /v1/entity/{entity_id}/hierarchy` every 5-10 seconds. The `status` field moves
   from `not_started` or `in_progress` to `completed` (or `failed`).
3. **Read** the completed structure from `data`.

First-time research typically takes 10-20 minutes. Completed research is cached, so
subsequent GETs return instantly.

```bash
curl --request POST \
  --url 'https://api.savvyiq.ai/v1/entity/siq_303bOyvScnpCchGvOckDr/hierarchy' \
  --header 'apikey: YOUR_API_KEY'
```

## What you get

A completed response contains the whole structure, not just the immediate parent:

- **`entities`** — every organization in the structure, with jurisdiction, organization type,
  and whether it is publicly traded
- **`relationships`** — who owns whom, the relationship type (`owns`, `majority_owns`,
  `holding_company`, `government_owns`, ...), and ownership percentages where known
- **`ownership_chain`** — the direct path from the target entity up to the ultimate parent
- **`ultimate_parent`** — the entity in ultimate control
- **`summary_short`** / **`summary_long`** — plain-English explanations of the structure
- **`evidence`** — source URLs backing the research
- **`mermaid_diagram`** — ready-to-render diagram code for visualizing the structure

## Example

MG Motor UK Ltd resolves through four ownership levels to a Chinese state agency:

```json
{
  "entity_id": "siq_303bOyvScnpCchGvOckDr",
  "status": "completed",
  "data": {
    "target_entity": { "id": "e1", "name": "MG MOTOR UK LTD" },
    "ultimate_parent": {
      "id": "e6",
      "name": "Shanghai State-owned Assets Supervision and Administration Commission (Shanghai SASAC)"
    },
    "ownership_chain": [
      { "entity_id": "e1", "parent_id": "e2", "relationship_type": "owns", "ownership_percentage": null },
      { "entity_id": "e2", "parent_id": "e4", "relationship_type": "holding_company", "ownership_percentage": null },
      { "entity_id": "e4", "parent_id": "e5", "relationship_type": "majority_owns", "ownership_percentage": 62.69 },
      { "entity_id": "e5", "parent_id": "e6", "relationship_type": "government_owns", "ownership_percentage": null }
    ],
    "summary_short": "MG Motor UK Ltd is a subsidiary of SAIC Motor Corporation Limited, which holds a 62.69% majority stake. Ultimate control lies with Shanghai Automotive Industry Corporation (Group), overseen by the Shanghai State-owned Assets Supervision and Administration Commission.",
    "evidence": [
      "https://find-and-update.company-information.service.gov.uk/company/05779958",
      "https://en.wikipedia.org/wiki/SAIC_Motor"
    ],
    "...": "..."
  },
  "last_researched_at": "2025-10-14T21:37:51.095Z",
  "request_id": "req_31ktmKZbyd9zqFCNxlwhc"
}
```

The full response also includes every entity and relationship in the structure plus a
`mermaid_diagram` — see the
[API reference](/docs/reference/entity-hierarchy/get-v1-entity-entity-id-hierarchy/) for the
complete schema.

## Common uses

- **KYB and compliance** — trace beneficial ownership through holding companies and
  identify state-owned or government-controlled entities
- **Risk assessment** — understand who ultimately stands behind a counterparty
- **Account intelligence** — roll subsidiaries up to the parent for territory planning and
  deduplication