# Submit entity hierarchy research request

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

> Tag: Entity hierarchy

Submit a corporate hierarchy research request for an entity. Research typically takes 10-20 minutes.

If research is already in progress for this entity, the existing request is returned instead of creating a duplicate.

After submission, poll the GET endpoint every 5-10 seconds until `status` is `completed`.

## Request

### Path parameters

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

### Example request

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

## Responses

### 202 — Accepted - Research request submitted

- `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": "in_progress",
  "data": null,
  "last_researched_at": null,
  "request_id": "req_31ktmKZbyd9zqFCNxlwhc",
  "message": "Research submitted. Expected completion in 10-20 minutes."
}
```

### 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"
  }
}
```