# Get entity hierarchy research

`GET /v1/entity/{entity_id}/hierarchy`

> Tag: Entity hierarchy

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.

## Request

### Path parameters

- `entity_id` (string, required) — The SIQ entity ID (e.g., "siq_303bOyvScnpCchGvOckDr")

### Example request

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

## Responses

### 200 — OK - Returns hierarchy research in any state

- `entity_id` (string, required) — The SIQ entity ID that was researched
- `status` (string (enum), required) — Current status of the research
- `data` (oneOf<object | null>) — Hierarchy data (null if not completed)
  - `entities` (array<object>) — All entities in the corporate structure
    - `id` (string) — Internal entity identifier used in relationships
    - `name` (string) — Legal entity name
    - `country_code` (string) — ISO 3166-1 alpha-2 country code
    - `jurisdiction` (string) — Full jurisdiction name
    - `organization_type` (string (enum)) — Type of organization
    - `is_publicly_traded` (boolean) — Whether the entity is publicly traded
  - `relationships` (array<object>) — All relationships between entities
    - `id` (string) — Relationship identifier
    - `from` (string) — ID of the parent/controlling entity
    - `to` (string) — ID of the subsidiary/controlled entity
    - `relationship_type` (string (enum)) — Type of relationship
    - `ownership_percentage` (number) — Ownership percentage if known
    - `established_date` (string) — 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_chain` (array<object>) — Direct ownership path from target entity to ultimate parent
    - `entity_id` (string) — Entity ID at this level
    - `parent_id` (string) — Parent entity ID
    - `relationship_type` (string) — Type of relationship to parent
    - `ownership_percentage` (number) — Ownership percentage if known
  - `evidence` (array<string>) — URLs of evidence sources used in research
  - `summary_short` (string) — Brief summary of the ownership structure (1-2 sentences)
  - `summary_long` (string) — Detailed summary of the ownership structure and corporate history
  - `mermaid_diagram` (string) — Mermaid diagram code for visualizing the hierarchy
  - `target_entity` (object) — The entity that was researched
    - `id` (string)
    - `name` (string)
  - `ultimate_parent` (object) — The ultimate controlling entity (null if none found)
    - `id` (string)
    - `name` (string)
- `last_researched_at` (string) — ISO 8601 timestamp of when research was completed
- `request_id` (string) — Request ID for tracking
- `message` (string) — Optional message with additional context

```json
{
  "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"
}
```

### 400 — Bad Request - Invalid entity ID format

- `error` (object) — An error object.
  - `message` (string) — The error message
  - `type` (string) — The error code

```json
{
  "error": {
    "message": "Bad request",
    "type": "bad_request"
  }
}
```

### 401 — Unauthorized

- `message` (string) — The error object.
- `request_id` (string) — The request ID for the error.

```json
{
  "message": "No API key found in request",
  "request_id": "d6ed1709fa87777bb373fd60a810e717"
}
```

### 500 — Internal Server Error

- `error` (object) — An error object.
  - `message` (string) — The error message
  - `type` (string) — The error code

```json
{
  "error": {
    "message": "An unexpected error occurred.",
    "type": "api_error"
  }
}
```