Entity Hierarchy API

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:

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.

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:

{
  "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 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