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