Entity hierarchy

Submit ultimate parent research request

POST /v1/entity/{entity_id}/ultimate-parent

View as markdown Open in ChatGPT Open in Claude

Submit upward ownership research for an entity: who controls it, up to the ultimate controlling 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)
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
Show 2 nested fieldsHide nested fields
- typestring
  Stable, machine-readable error code.
- messagestring
  Human-readable explanation. Do not match on this.

401 Unauthorized

errorobject
Show 2 nested fieldsHide nested fields
- typestring
  Stable, machine-readable error code.
- messagestring
  Human-readable explanation. Do not match on this.

500 Internal Server Error

errorobject
Show 2 nested fieldsHide nested fields
- typestring
  Stable, machine-readable error code.
- messagestring
  Human-readable explanation. Do not match on this.

Example request

cURL

curl --request POST \
  --url 'https://api.savvyiq.ai/v1/entity/siq_303bOyvScnpCchGvOckDr/ultimate-parent' \
  --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"
}