Entity Hierarchy API

Trace ownership upward from an entity: who owns it, through which intermediate holding companies, and who ultimately controls it. AI agents research the chain 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}/ultimate-parent. If research is already running for that entity, the existing request is returned instead of a duplicate.
2. Poll GET /v1/entity/{entity_id}/ultimate-parent 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/ultimate-parent' \
  --header 'apikey: YOUR_API_KEY'

What you get

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

• entities: every organization in the chain, 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 chain plus a mermaid_diagram. See the API reference for the complete schema. The path /v1/entity/{entity_id}/hierarchy is a live alias of the same endpoint.

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 every entity in a chain up to its parent for territory planning and deduplication