Entity hierarchy

Submit entity hierarchy research request

POST /v1/entity/{entity_id}/hierarchy

View as markdown Open in ChatGPT Open in Claude

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.

Path parameters

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

Responses

202 Accepted - Research request submitted

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)
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 POST \
  --url 'https://api.savvyiq.ai/v1/entity/siq_303bOyvScnpCchGvOckDr/hierarchy' \
  --header 'apikey: YOUR_API_KEY'

Example response

New research request submitted202

{
  "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."
}

Research already in progress (deduplication)

{
  "entity_id": "siq_303bOyvScnpCchGvOckDr",
  "status": "in_progress",
  "data": null,
  "last_researched_at": null,
  "request_id": "req_31ktmKZbyd9zqFCNxlwhc",
  "message": "Research already in progress"
}