> For the complete documentation index, see [llms.txt](https://help.delpha.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.delpha.io/delpha-api-and-mcp/api/ultimate-parent.md).

# Ultimate Parent

Resolve the ultimate parent of a company through corporate-hierarchy reasoning. Submit a company (name + website, optional country); the API returns a job\_id you poll until the result is ready. The response includes the ultimate corporate parent, the full ownership chain (intermediate holding entities), the ultimate financial parent when it differs from the corporate parent, GLEIF Legal Entity Identifier (LEI) data for every entity, and the LLM's reasoning + cited source URL.

## Submit an ultimate-parent resolution job

> Submit a company (name + website, optional country) for ultimate-parent resolution. Returns a job ID for tracking the process.

```json
{"openapi":"3.1.0","info":{"title":"Delpha Data Quality API","version":"1.0.0"},"tags":[{"name":"Ultimate Parent","description":"Resolve the ultimate parent of a company through corporate-hierarchy reasoning. Submit a company (name + website, optional country); the API returns a job_id you poll until the result is ready. The response includes the ultimate corporate parent, the full ownership chain (intermediate holding entities), the ultimate financial parent when it differs from the corporate parent, GLEIF Legal Entity Identifier (LEI) data for every entity, and the LLM's reasoning + cited source URL."}],"servers":[{"url":"https://api.delpha.io","description":"Production API server"}],"security":[{"oauth2":["api/access"]}],"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"OAuth2 client credentials flow for API access","flows":{"clientCredentials":{"tokenUrl":"https://secure.delpha.io/oauth2/token","scopes":{"api/access":"Access to the public API"}}}}},"schemas":{"UltimateSubmitInput":{"properties":{"company_name":{"type":"string","minLength":1,"title":"Company Name","description":"The company whose ultimate parent we want to resolve. Free-form name as it appears commercially or legally."},"website":{"type":"string","minLength":1,"title":"Website","description":"The company's primary website. Used by the LLM to ground the search and resolve ambiguity. URL scheme will be added automatically if missing."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Optional country to disambiguate when the website's jurisdiction is unclear (e.g., generic .com domains). Free-form name; not constrained to ISO codes."}},"additionalProperties":false,"type":"object","required":["company_name","website"],"title":"UltimateSubmitInput","description":"Payload to submit a new ultimate-parent resolution job."},"UltimateSubmitOutput":{"properties":{"job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Id","description":"The job ID. Required if status_code <= 300."},"message":{"type":"string","title":"Message","description":"The message to return"},"status":{"type":"string","enum":["SUCCESS","ERROR"],"title":"Status","description":"The status of the process"},"status_code":{"type":"integer","title":"Status Code","description":"The HTTP status code to return"}},"type":"object","required":["message","status","status_code"],"title":"UltimateSubmitOutput","description":"Response after submitting an ultimate-parent resolution job."}}},"paths":{"/v1/ultimate":{"post":{"tags":["Ultimate Parent"],"summary":"Submit an ultimate-parent resolution job","description":"Submit a company (name + website, optional country) for ultimate-parent resolution. Returns a job ID for tracking the process.","operationId":"submitUltimateParent","requestBody":{"description":"\n\n**Validation Rules:**\n\n- `company_name` must be a non-empty string.\n- `website` must be a non-empty string (URL scheme will be added automatically if missing).\n- `country` is optional but recommended for accuracy when the website doesn't reveal jurisdiction (e.g., generic `.com` without a regional TLD).\n- Any field other than `company_name`, `website`, or `country` is rejected with HTTP 422 (`extra=\"forbid\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UltimateSubmitInput"}}},"required":true},"responses":{"202":{"description":"Job submitted to get-ultimate-queue","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UltimateSubmitOutput"}}}},"400":{"description":"company_name: Field required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UltimateSubmitOutput"}}}},"401":{"description":"Authentication failed - invalid or missing OAuth 2.0 token","content":{"application/json":{"schema":{"properties":{"message":{"type":"string"}},"type":"object"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UltimateSubmitOutput"}}}},"502":{"description":"Failed to enqueue job: ...","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UltimateSubmitOutput"}}}}}}}}}
```

## Get ultimate-parent job status

> Retrieve the result and status of a previously submitted ultimate-parent resolution job.

```json
{"openapi":"3.1.0","info":{"title":"Delpha Data Quality API","version":"1.0.0"},"tags":[{"name":"Ultimate Parent","description":"Resolve the ultimate parent of a company through corporate-hierarchy reasoning. Submit a company (name + website, optional country); the API returns a job_id you poll until the result is ready. The response includes the ultimate corporate parent, the full ownership chain (intermediate holding entities), the ultimate financial parent when it differs from the corporate parent, GLEIF Legal Entity Identifier (LEI) data for every entity, and the LLM's reasoning + cited source URL."}],"servers":[{"url":"https://api.delpha.io","description":"Production API server"}],"security":[{"oauth2":["api/access"]}],"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"OAuth2 client credentials flow for API access","flows":{"clientCredentials":{"tokenUrl":"https://secure.delpha.io/oauth2/token","scopes":{"api/access":"Access to the public API"}}}}},"schemas":{"UltimatePullOutput":{"properties":{"job_id":{"type":"string","title":"Job Id","description":"The job ID echoed back from the request."},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"A human-readable message describing the current state or outcome of the job."},"status":{"type":"string","enum":["SUCCESS","ERROR"],"title":"Status","description":"The status of the process. Note: SUCCESS at status_code=202 means 'still running'."},"status_code":{"type":"integer","title":"Status Code","description":"The HTTP status code representing the job's current state."},"result":{"anyOf":[{"$ref":"#/components/schemas/UltimateResult"},{"type":"null"}],"description":"The corporate hierarchy resolution. Present only when status_code == 200."}},"type":"object","required":["job_id","status","status_code"],"title":"UltimatePullOutput","description":"Response after retrieving the status and result of an ultimate-parent job."},"UltimateResult":{"properties":{"ultimate_parent":{"$ref":"#/components/schemas/CompanyEntity","description":"The ultimate (corporate) parent of the requested company."},"relationship_type":{"anyOf":[{"$ref":"#/components/schemas/RelationshipType"},{"type":"null"}],"description":"How the requested company relates to the ultimate parent."},"confidence":{"type":"number","maximum":1,"minimum":0,"title":"Confidence","description":"LLM-reported confidence score in the resolved ultimate parent, from 0 to 1."},"ownership_chain":{"items":{"$ref":"#/components/schemas/CompanyEntity"},"type":"array","title":"Ownership Chain","description":"Ordered chain from the requested company up to the ultimate parent. Empty if the requested company IS the ultimate parent. May contain intermediate holding entities; the entity with `is_ultimate_financial_parent=True` (if any) is also exposed at top level as `ultimate_financial_parent` for convenience."},"ultimate_financial_parent":{"anyOf":[{"$ref":"#/components/schemas/CompanyEntity"},{"type":"null"}],"description":"Populated only when the ultimate financial parent differs from the ultimate corporate parent (e.g., the corporate parent is a holding company but a fund up the chain is the actual financial owner). When populated, this is the same object as the chain entity whose `is_ultimate_financial_parent` is True."},"comment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comment","description":"LLM's textual reasoning for the resolved hierarchy. Useful for verification / auditability."},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url","description":"A URL the LLM cited as the basis for its conclusion (typically the parent's IR page or annual report)."},"subsidiary_commercial_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subsidiary Commercial Name","description":"The LLM's normalized commercial name for the queried (input) company. Useful when callers pass a fuzzy or legal name and want to see how the model resolved it."},"ultimate_parent_source_level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ultimate Parent Source Level","description":"The authority level of the evidence the LLM relied on for the ultimate-parent conclusion (e.g., 'Securities Filing', 'Annual Report', 'Press Release')."},"evidence_summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Evidence Summary","description":"One-line trace summarizing the LLM's reasoning steps (identity verification, chain traversal, discard logic, GTM selection). Useful for audit and debugging."},"is_self_ultimate":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Self Ultimate","description":"True when the queried company is its own ultimate parent (no further hierarchy above it)."}},"type":"object","required":["ultimate_parent","confidence"],"title":"UltimateResult","description":"The corporate hierarchy resolution: ultimate parent, ownership chain, and supporting evidence."},"CompanyEntity":{"properties":{"legal_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Legal Name","description":"The official legal name of the entity."},"commercial_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Commercial Name","description":"The commonly-used commercial / trade name."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"The country where the entity is headquartered or registered."},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website","description":"The entity's primary website URL."},"website_validated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Website Validated","description":"True if the website was reachable and resolved cleanly during normalization."},"lei_data":{"anyOf":[{"$ref":"#/components/schemas/LeiData"},{"type":"null"}],"description":"GLEIF Legal Entity Identifier metadata. Null if no match was found at >=80 fuzzy-match score."},"is_ultimate_financial_parent":{"type":"boolean","title":"Is Ultimate Financial Parent","description":"True for the chain entity that the LLM identified as the ultimate financial parent (when it differs from the ultimate corporate parent).","default":false},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type","description":"The entity's legal form / classification as identified by the LLM (e.g., 'Corporation', 'Holding Shell/Foundation', 'Trust')."},"ownership_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ownership Status","description":"Free-form ownership status of the entity as reported by the LLM (e.g., 'Unknown', 'Active')."},"is_discarded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Discarded","description":"True when the LLM excluded this entity from the strategic operating chain (e.g., passive holding companies above an operating conglomerate). Lets callers distinguish operating links from holding overlays."},"comment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comment","description":"Per-entity annotation from the LLM (e.g., 'Target operating entity', 'Passive holding for control purposes')."}},"type":"object","title":"CompanyEntity","description":"A single entity in the corporate hierarchy — used for the ultimate parent and each link of the ownership chain."},"LeiData":{"properties":{"lei_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lei Number","description":"The 20-character LEI identifier."},"lei_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lei Source","description":"The source of the LEI lookup (typically 'GLEIF')."},"legal_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Legal Name","description":"The official legal name as registered with the LEI authority."},"headquarters_address":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"string"},{"type":"null"}],"title":"Headquarters Address","description":"Headquarters postal address from the LEI registry. May be a structured dict or a formatted string."},"legal_jurisdiction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Legal Jurisdiction","description":"Legal jurisdiction (ISO 3166-1 alpha-2 country code)."},"legal_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Legal Id","description":"National legal identifier (e.g., SIREN in France)."},"registered_at":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"string"},{"type":"null"}],"title":"Registered At","description":"Registration authority data from the LEI registry. May be a structured dict with code/jurisdictions or an ISO date string."}},"type":"object","title":"LeiData","description":"GLEIF Legal Entity Identifier metadata, populated by a follow-up GLEIF lookup."},"RelationshipType":{"type":"string","enum":["Wholly Owned","Member Firm/Franchise","Portfolio Company","Brand/Division","Independent","Joint Venture"],"title":"RelationshipType","description":"How the requested company relates to its ultimate parent."}}},"paths":{"/v1/ultimate/{job_id}":{"get":{"tags":["Ultimate Parent"],"summary":"Get ultimate-parent job status","description":"Retrieve the result and status of a previously submitted ultimate-parent resolution job.","operationId":"getUltimateParentResult","responses":{"200":{"description":"Job succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UltimatePullOutput"}}}},"202":{"description":"Job is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UltimatePullOutput"}}}},"400":{"description":"Missing job_id in path parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UltimatePullOutput"}}}},"401":{"description":"Authentication failed - invalid or missing OAuth 2.0 token","content":{"application/json":{"schema":{"properties":{"message":{"type":"string"}},"type":"object"}}}},"500":{"description":"Lambda crashed or failed after retries before writing result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UltimatePullOutput"}}}},"502":{"description":"UPSTREAM_SCHEMA_DRIFT: row contains no ultimate_parent_legal_name ...","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UltimatePullOutput"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.delpha.io/delpha-api-and-mcp/api/ultimate-parent.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.