Obtaining Case Result
This guide explains how to obtain case results via the API.
A case may contain one or more conversations (dialogs). While you can retrieve results for an individual conversation using the Get Conversation Result endpoint, you can also obtain results for the entire case.
The case result includes:
- detailed information about the company
- results for each completed conversation within the case.
To retrieve the case result, call GET /api/v1/cases/{case_id}/result passing case_id of the case. If the result is not ready yet, you will receive the following response:
{
"case_id": "...",
"status": "not_ready"
}You can continue polling every few seconds until the results are ready. Once they are available, the response will look like this:
{
"case_id": "3475db67-9c9b-4832-a665-3f9ce1e9994e",
"status": "ready",
"result": {
"conversation_results": [
{
"case_id": "3475db67-9c9b-4832-a665-3f9ce1e9994e",
"conversation_id": "17fc24aa-cfe7-4aff-8fb1-fe65cee35443",
"web_report_link": "...",
"pdf_report_link": "...",
"client_documents": [
{
"document_id": "166086d9-807a-4b24-af22-821f5840f473",
"document_type": "official_registers",
"document_name": "Confirmation statement with updates dated 2026-02-09",
"rejected": false,
"translated": false,
"download_link": "...",
"original_files": [
{
"filename": "Confirmation_statement_with_updates_dated_2026_02_09.pdf",
"source_url": "https://find-and-update.company-information.service.gov.uk/company/12345678/filing-history/MzUwMzg2MDAxMmFkaXF6a2N4/document?format=pdf"
}
],
"extracted_data": {},
"entity_id": "a2b2eaae-0ca1-44ac-b0f5-59ee1ec6f5eb"
}
],
"conversation_log": [],
"main_entity_id": null,
"legal_entities": null
},
{
"case_id": "3475db67-9c9b-4832-a665-3f9ce1e9994e",
"conversation_id": "43f8bdca-704b-4ac5-b1f6-1153aa653682",
"web_report_link": "...",
"pdf_report_link": "...",
"client_documents": [
{
"document_id": "2072ae42-4b29-4ffe-9ede-669161f47e11",
"document_type": "business_license",
"document_name": "Business License",
"rejected": false,
"translated": false,
"download_link": "...",
"original_files": [],
"extracted_data": {},
"entity_id": "48fc795a-0dc9-4b43-ba97-d45a8731dd70"
}
],
"conversation_log": [],
"main_entity_id": null,
"legal_entities": null
}
],
"main_entity_id": "a2b2eaae-0ca1-44ac-b0f5-59ee1ec6f5eb",
"account_owner_entity_ids": [
"60de5a4d-cf49-4031-96ff-2195a9623331"
],
"legal_entities": [
{
"entity_id": "a2b2eaae-0ca1-44ac-b0f5-59ee1ec6f5eb",
"entity_details": {
"type": "company",
"entity_id": "a2b2eaae-0ca1-44ac-b0f5-59ee1ec6f5eb",
"company_full_name": "...",
"legal_type": null,
"incorporation_date": "2021-01-01",
"company_status": "Active",
"company_country_code": "GB",
"company_website": {
"url": "https://example.com/"
},
"company_email": "[email protected]",
"company_reg_number": "12345678",
"tax_residency_country_code": "GB",
"tax_residence_number": "12345678",
"vat_number": "GB12345678",
"legal_address": {
"street_address": "...",
"city": "...",
"postcode": "...",
"country_code": "GB",
"state_or_province": "..."
},
"legal_address_translated": {
"street_address": "...",
"city": "...",
"postcode": "...",
"country_code": "GB",
"state_or_province": "..."
},
"operational_address": {
"street_address": "...",
"city": "...",
"postcode": "...",
"country_code": "GB",
"state_or_province": "..."
},
"operational_address_translated": {
"street_address": "...",
"city": "...",
"postcode": "...",
"country_code": "GB",
"state_or_province": "..."
},
"registered_industry_codes": [
{
"classification": "UKSIC2007",
"code": "01120"
},
{
"classification": "NACE",
"code": "A1.1.2"
}
],
"auto_assigned_industry_codes": [
{
"classification": "UKSIC2007",
"code": "01120"
},
{
"classification": "NACE",
"code": "A1.1.2"
}
],
"shareholders": [
{
"entity_id": "c769bdf6-4a68-4463-b0a8-51cfccaef0c0",
"ownership": {
"range": [
0.25,
0.5
]
}
},
{
"entity_id": "60de5a4d-cf49-4031-96ff-2195a9623331",
"ownership": {
"fraction": 0.7
}
}
],
"ultimate_beneficiary_owners": [
{
"person_entity_id": "60de5a4d-cf49-4031-96ff-2195a9623331",
"effective_ownership": {
"fraction": 0.7
}
},
{
"person_entity_id": "36d3a5d9-50bd-4799-ab4c-5be7b79307a5",
"effective_ownership": {
"range": [
0.25,
0.5
]
}
}
],
"directors": [
{
"person_entity_id": "60de5a4d-cf49-4031-96ff-2195a9623331",
"nominal": false
}
],
"is_license_required": false,
"counterparties": [
{
"entity_id": "c769bdf6-4a68-4463-b0a8-51cfccaef0c0",
"nature_of_relationship": "...",
"counterparty_role": [
"customer",
"supplier"
]
}
],
"additional_details": [
{
"item_id": "some_custom_id",
"value": "Some value"
}
]
}
},
{
"entity_id": "c769bdf6-4a68-4463-b0a8-51cfccaef0c0",
"entity_details": {
"type": "company",
"entity_id": "c769bdf6-4a68-4463-b0a8-51cfccaef0c0",
"company_full_name": "...",
"legal_type": null,
"incorporation_date": "2015-02-12",
"company_status": "...",
"company_country_code": "GB",
"company_website": {
"url": "..."
},
"company_email": null,
"company_reg_number": "...",
"tax_residency_country_code": "GB",
"tax_residence_number": "...",
"vat_number": "...",
"legal_address": {
"street_address": "...",
"city": "...",
"postcode": "...",
"country_code": "GB",
"state_or_province": "..."
},
"legal_address_translated": {
"street_address": "...",
"city": "...",
"postcode": "...",
"country_code": "GB",
"state_or_province": "..."
},
"operational_address": {
"street_address": "...",
"city": "...",
"postcode": "...",
"country_code": "GB",
"state_or_province": "..."
},
"operational_address_translated": {
"street_address": "...",
"city": "...",
"postcode": "...",
"country_code": "GB",
"state_or_province": "..."
},
"registered_industry_codes": [],
"auto_assigned_industry_codes": [],
"shareholders": [
{
"entity_id": "36d3a5d9-50bd-4799-ab4c-5be7b79307a5",
"ownership": {
"fraction": 1.0
}
}
],
"ultimate_beneficiary_owners": [
{
"person_entity_id": "36d3a5d9-50bd-4799-ab4c-5be7b79307a5",
"effective_ownership": {
"fraction": 1.0
}
}
],
"directors": [],
"is_license_required": null,
"counterparties": [],
"additional_details": []
}
},
{
"entity_id": "36d3a5d9-50bd-4799-ab4c-5be7b79307a5",
"entity_details": {
"type": "person",
"entity_id": "36d3a5d9-50bd-4799-ab4c-5be7b79307a5",
"first_name": "...",
"last_name": "...",
"date_of_birth": "1985-04",
"id_number": null,
"citizenship_country_code": "GB",
"residency_country_code": "GB",
"tax_residency_country_code": null,
"tax_residence_number": null,
"is_us_person": null,
"is_pep_self_assessment": null,
"email": null,
"phone": null,
"residential_address": null,
"residential_address_translated": null,
"linkedin_profile": null,
"identity_verification_external_user_id": null,
"identity_verification_applicant_id": null,
"additional_details": []
}
},
{
"entity_id": "60de5a4d-cf49-4031-96ff-2195a9623331",
"entity_details": {
"type": "person",
"entity_id": "60de5a4d-cf49-4031-96ff-2195a9623331",
"first_name": "...",
"last_name": "...",
"date_of_birth": "1990-01",
"id_number": "...",
"citizenship_country_code": "GB",
"residency_country_code": "GB",
"tax_residency_country_code": "GB",
"tax_residence_number": "...",
"is_us_person": false,
"is_pep_self_assessment": false,
"email": "...",
"phone": "+1234567890",
"residential_address": {
"street_address": "...",
"city": "...",
"postcode": "...",
"country_code": "GB",
"state_or_province": "..."
},
"residential_address_translated": {
"street_address": "...",
"city": "...",
"postcode": "...",
"country_code": "GB",
"state_or_province": "..."
},
"linkedin_profile": "https://www.linkedin.com/in/test/",
"identity_verification_external_user_id": null,
"identity_verification_applicant_id": null,
"additional_details": [
{
"item_id": "some_custom_id",
"value": "Some value"
}
]
}
}
],
"business_description_summary": "...",
"questionnaire": null,
"scoring": {
"score": 132,
"risk_level": "High Risk"
},
"documents": [],
"risk_assessment_report_pdf_link": null
}
}The case result object contains:
legal_entities- all known legal entities within the case - companies (shareholding companies, counterparties) or stakeholders/persons (beneficiaries, directors, account owners). Each legal entity has an ID which is used to reference this entity from other places (like list of beneficiaries contains links to person entities by ID).business_description_summary- Summary of the business description derived from the dialog with the account owner.questionnaire- Selected answers to the questionnaire, if it was filledmain_entity_id- identifies the legal entity which represents the onboarding company.account_owner_entity_ids- identifies the legal entity which represents the account owner person.conversation_results- an array containing the results of individual conversations (dialogs) within the case. Each conversation result contains:- the list of documents uploaded within the case (and each documents references the legal entity which this document was requested for);
- the conversation log.
Shareholding structure
The shareholding structure is returned flat, not nested: every company and person appears exactly once in legal_entities with its own entity_id, and the links between them are expressed as references. Each company's shareholders list points at its direct owners by entity_id, and ownership is that owner's stake in that company — either an exact fraction or a range when the register only publishes a band. You walk the structure by following those references from main_entity_id outwards.
Intermediate holding companies are returned as entities in their own right, with their own shareholders, so the whole chain is visible rather than only its ends. In the example above the main company is owned by a person directly and by another company, whose own shareholder is a second person. Each company also carries ultimate_beneficiary_owners: the natural persons at the end of the chain, where effective_ownership is their stake in that company through all paths combined (the shares multiplied along each path, then summed). A person owning through two branches appears once, with the stakes added together. Where a chain cannot be followed further — a company outside the covered register, or one whose ownership is not published — that company is still listed as a shareholder, simply with no shareholders of its own.
Source of the shareholding data
Where shareholdings come from a company's filings in an official register, the filing itself is returned in the conversation's client_documents as a document of type official_registers, with entity_id pointing at the company whose ownership it evidences — so a resolved chain yields one document per company. Its document_name identifies the filing, and download_link returns the file we used.
Each entry in that document's original_files may also carry a source_url: a permanent public link to the same filing on the register's own website (if available), openable in a browser without our API and without authentication. This lets any reported percentage be traced back to the document it was read from. source_url is null for documents that did not come from a register, such as files provided by the user.
For a full and up-to-date specification of the results object, please refer to the Get Case Result endpoint documentation.
Updated 30 days ago