Entity hierarchy

Get entity hierarchy research

GET /v1/entity/{entity_id}/hierarchy

View as markdown Open in ChatGPT Open in Claude

Retrieve corporate hierarchy research for an entity: ownership chains, parent companies, and the ultimate controlling entity.

Returns 200 for all states; check the status field:

not_started: no research exists yet. Submit a request with the POST endpoint.
in_progress: research is running. Poll this endpoint every 5-10 seconds.
completed: full hierarchy data available in data.
failed: research encountered an error; see message.

First-time research typically takes 10-20 minutes.

Path parameters

entity_idstring required
The SIQ entity ID (e.g., "siq_303bOyvScnpCchGvOckDr")

Responses

200 OK - Returns hierarchy research in any state

entity_idstring required
The SIQ entity ID that was researched
statusstring (enum) required
not_startedin_progresscompletedfailed
Current status of the research
dataoneOf<object | null>
Hierarchy data (null if not completed)
Show 9 nested fieldsHide nested fields
- entitiesarray<object>
  All entities in the corporate structure
  Show 6 nested fieldsHide nested fields
  idstring
  Internal entity identifier used in relationships
  namestring
  Legal entity name
  country_codestring
  ISO 3166-1 alpha-2 country code
  jurisdictionstring
  Full jurisdiction name
  organization_typestring (enum)
  businessgovernmentnonprofitindividual
  Type of organization
  is_publicly_tradedboolean
  Whether the entity is publicly traded
- relationshipsarray<object>
  All relationships between entities
  Show 6 nested fieldsHide nested fields
  idstring
  Relationship identifier
  fromstring
  ID of the parent/controlling entity
  tostring
  ID of the subsidiary/controlled entity
  relationship_typestring (enum)
  ownsmajority_ownsminority_ownsholding_companygovernment_ownsparent_ofsubsidiary_of
  Type of relationship
  ownership_percentagenumber
  Ownership percentage if known
  established_datestring
  Date the relationship was established, as a partial ISO 8601 date — "YYYY", "YYYY-MM", or "YYYY-MM-DD", as precisely as the sources evidence it.
- ownership_chainarray<object>
  Direct ownership path from target entity to ultimate parent
  Show 4 nested fieldsHide nested fields
  entity_idstring
  Entity ID at this level
  parent_idstring
  Parent entity ID
  relationship_typestring
  Type of relationship to parent
  ownership_percentagenumber
  Ownership percentage if known
- evidencearray<string>
  URLs of evidence sources used in research
- summary_shortstring
  Brief summary of the ownership structure (1-2 sentences)
- summary_longstring
  Detailed summary of the ownership structure and corporate history
- mermaid_diagramstring
  Mermaid diagram code for visualizing the hierarchy
- target_entityobject
  The entity that was researched
  Show 2 nested fieldsHide nested fields
  idstring
  namestring
- ultimate_parentobject
  The ultimate controlling entity (null if none found)
  Show 2 nested fieldsHide nested fields
  idstring
  namestring
last_researched_atstring
ISO 8601 timestamp of when research was completed
request_idstring
Request ID for tracking
messagestring
Optional message with additional context

400 Bad Request - Invalid entity ID format

errorobject
An error object.
Show 2 nested fieldsHide nested fields
- messagestring
  The error message
- typestring
  The error code

401 Unauthorized

messagestring
The error object.
request_idstring
The request ID for the error.

500 Internal Server Error

errorobject
An error object.
Show 2 nested fieldsHide nested fields
- messagestring
  The error message
- typestring
  The error code

Example request

cURL

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

Example response

Completed research with full hierarchy data (MG Motor UK example)200

{
  "entity_id": "siq_303bOyvScnpCchGvOckDr",
  "status": "completed",
  "data": {
    "entities": [
      {
        "id": "e1",
        "name": "MG MOTOR UK LTD",
        "country_code": "GB",
        "jurisdiction": "England and Wales",
        "organization_type": "business",
        "is_publicly_traded": false
      },
      {
        "id": "e2",
        "name": "SAIC MOTOR UK HOLDING CO., LTD.",
        "country_code": "GB",
        "jurisdiction": "England and Wales",
        "organization_type": "business",
        "is_publicly_traded": false
      },
      {
        "id": "e3",
        "name": "SAIC MOTOR INTERNATIONAL UK LTD",
        "country_code": "GB",
        "jurisdiction": "England and Wales",
        "organization_type": "business",
        "is_publicly_traded": false
      },
      {
        "id": "e4",
        "name": "SAIC Motor Corporation Limited",
        "country_code": "CN",
        "jurisdiction": "People's Republic of China",
        "organization_type": "business",
        "is_publicly_traded": true
      },
      {
        "id": "e5",
        "name": "Shanghai Automotive Industry Corporation (Group)",
        "country_code": "CN",
        "jurisdiction": "People's Republic of China",
        "organization_type": "business",
        "is_publicly_traded": false
      },
      {
        "id": "e6",
        "name": "Shanghai State-owned Assets Supervision and Administration Commission (Shanghai SASAC)",
        "country_code": "CN",
        "jurisdiction": "Shanghai Municipality, People's Republic of China",
        "organization_type": "government",
        "is_publicly_traded": false
      },
      {
        "id": "e7",
        "name": "MG Sales Centre Limited",
        "country_code": "GB",
        "jurisdiction": "England and Wales",
        "organization_type": "business",
        "is_publicly_traded": false
      }
    ],
    "relationships": [
      {
        "id": "r1",
        "to": "e1",
        "from": "e2",
        "established_date": "2005-02-15",
        "relationship_type": "owns",
        "ownership_percentage": null
      },
      {
        "id": "r2",
        "to": "e7",
        "from": "e1",
        "established_date": "2018",
        "relationship_type": "owns",
        "ownership_percentage": null
      },
      {
        "id": "r3",
        "to": "e2",
        "from": "e4",
        "established_date": null,
        "relationship_type": "holding_company",
        "ownership_percentage": null
      },
      {
        "id": "r4",
        "to": "e3",
        "from": "e4",
        "established_date": null,
        "relationship_type": "owns",
        "ownership_percentage": null
      },
      {
        "id": "r5",
        "to": "e4",
        "from": "e5",
        "established_date": null,
        "relationship_type": "majority_owns",
        "ownership_percentage": 62.69
      },
      {
        "id": "r6",
        "to": "e5",
        "from": "e6",
        "established_date": null,
        "relationship_type": "government_owns",
        "ownership_percentage": null
      }
    ],
    "evidence": [
      "http://companycheck.co.uk/company/05779958/MG-MOTOR-UK-LTD",
      "https://en.wikipedia.org/wiki/MG_Cars",
      "https://en.wikipedia.org/wiki/MG_Motor",
      "https://en.wikipedia.org/wiki/SAIC_Motor",
      "https://find-and-update.company-information.service.gov.uk/company/05586826",
      "https://find-and-update.company-information.service.gov.uk/company/05779958",
      "https://www.saicmotor.com/english/images/investor_relations/annual_report/2024/5/31/DE63B019CA9A441FA0801360B6121A6E.pdf"
    ],
    "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.",
    "summary_long": "MG Motor UK Ltd is a private limited company operating in the retail automotive sector, specifically the sale of new cars and light motor vehicles. Its immediate parent company is SAIC Motor UK Holding Co., LTD. The ownership structure extends beyond SAIC Motor UK Holding Co., LTD. SAIC Motor Corporation Limited holds a 62.69% majority stake in Shanghai Automotive Industry Corporation (Group). This indicates an indirect ownership of MG Motor UK LTD by SAIC Motor Corporation Limited through its control of SAIC Motor UK Holding Co., LTD. The ultimate controlling entity is the Shanghai Automotive Industry Corporation (Group), which is under the oversight of the Shanghai State-owned Assets Supervision and Administration Commission (SASAC). SASAC, a government agency directly under the Municipal Government of Shanghai, is authorized to supervise municipal state-owned assets.",
    "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
      }
    ],
    "target_entity": {
      "id": "e1",
      "name": "MG MOTOR UK LTD"
    },
    "ultimate_parent": {
      "id": "e6",
      "name": "Shanghai State-owned Assets Supervision and Administration Commission (Shanghai SASAC)"
    },
    "mermaid_diagram": "graph TD\n  e2[SAIC MOTOR UK HOLDING CO., LTD.]-->|2005-02-15|e1[MG MOTOR UK LTD]\n  e1[MG MOTOR UK LTD]-->|2018|e7[MG Sales Centre Limited]\n  e4[SAIC Motor Corporation Limited]-->e2[SAIC MOTOR UK HOLDING CO., LTD.]\n  e4[SAIC Motor Corporation Limited]-->e3[SAIC MOTOR INTERNATIONAL UK LTD]\n  e5[Shanghai Automotive Industry Corporation Group]-->|62.69%|e4[SAIC Motor Corporation Limited]\n  e6[Shanghai State-owned Assets Supervision and Administration Commission Shanghai SASAC]-->e5[Shanghai Automotive Industry Corporation Group]"
  },
  "last_researched_at": "2025-10-14T21:37:51.095Z",
  "request_id": "req_31ktmKZbyd9zqFCNxlwhc"
}

Research currently running

{
  "entity_id": "siq_303bOyvScnpCchGvOckDr",
  "status": "in_progress",
  "data": null,
  "last_researched_at": null,
  "request_id": "req_31ktmKZbyd9zqFCNxlwhc"
}

No research exists yet

{
  "entity_id": "siq_303bOyvScnpCchGvOckDr",
  "status": "not_started",
  "data": null,
  "last_researched_at": null,
  "request_id": "req_31ktmKZbyd9zqFCNxlwhc"
}

Research failed

{
  "entity_id": "siq_303bOyvScnpCchGvOckDr",
  "status": "failed",
  "data": null,
  "last_researched_at": null,
  "request_id": "req_31ktmKZbyd9zqFCNxlwhc",
  "message": "Research failed due to insufficient data sources"
}