UBO Verify

What is UBO Verify?

UBO Verify automates the analysis of corporate ownership structures and calculates ultimate beneficial ownership at the click of a button, meaning accurate UBO identification in minutes not hours. The UBO Verify API and portal application are a tool which sits on top of the Kyckr registry network, retrieving profile information across jurisdictions and automatically analysing it to calculate ownership.

This guide covers the core request/poll workflow, jointly held shares, reasons for non-continuation, and continuation keys. For the ownership-analysis fields (uboAnalysisField coverage metrics and required-profile recommendations), the full entity-resolution audit trail (entitySelectionMetadataField, selectedCandidatesField, previousVersionsField), representative (director and officer) edges, and potential beneficial owner detection, see the Unwrap Ownership reference and the UBO Verify release note.

Search

The first step is to search the registry to find the entity. The search response will confirm whether the entity is active and provide a unique identifier for that company in codeField . The codeField can then be used to unwrap an ownership structure alongside the jurisdiction ISO of where that entity is based. Search guide

About the registration authority returned from search

In some jurisdictions, the search will return additional fields for registration authority: registrationAuthorityField and registrationAuthorityCodeField If the registration authority is specified in the search response, pass the value of the Registration Authority Code as a parameter to order a UBO Report. Passing the registrationAuthorityField helps to find and order shareholder profiles for the company of interest. If search does not return a registration authority field, it is not necessary to provide a registration authority in a UBO request.

Request a report

To order a UBO report from Kyckr using Registry data, the following variables are needed:

Path parameters	Description
CompanyCode	Code field of the primary entity - obtained using search
CountryIso	2 digit ISO code representing the jurisdiction of the primary entity
Query Parameters
regAuth	Required if the search response returns a registration authority, e.g. CA, DE
maxCreditCost	Specify the maximum credits to spend on this transaction.
uboThreshold	(Optional, if not provided defaults to 25) - can be set to any value between 1 and 100. Select a UBO threshold to determine the percentage ownership required for an entity to qualify as a UBO of the root company in the final calculation.
maxLayers	(Optional, minimum value 3) Restricts the number of layers that are unwraped

Request ownership tree API reference

Example create request for a UBO ownership tree report

curl --location 'https://rest.kyckr.com/core/uboverify/create/GB/09657876?uboThreshold=25&maxCreditCost=50&maxLayers=5' \
--header 'Authorization: {{apiKey}}'

Response

{
    "ownershipTreeField": {
        "statusField": "SUCCESS",
        "orderIdField": "2614793"
    },
    "responseCodeField": "201"
}

In the response, there will be a unique order id in the orderIdField.

Download the UBO ownership tree report

Once the call to create the ownership tree is made, the report can be retrieved by polling the request ownership tree endpoint with the order id. As this service is processing multiple entities (potentially across multiple registries), the time to make a complete report is dependent on the complexity of the ownership structure. Retrieve ownership tree API reference

Example poll request to download an UBO ownership tree report

curl --location 'https://rest.kyckr.com/core/uboverify/list/2614793'
--header 'Authorization: {{apiKey}}'

Pending response

While the report is being prepared, the status will return as "statusField": "IN_PROGRESS".

Example pending response

{
    "ownershipTreeField": {
        "idField": "1337531",
        "nodesField": [],
        "ultimateBeneficialOwnersField": [],
        "statusField": "IN_PROGRESS",
        "uboThresholdField": 25.0,
        "maxCreditCostField": 25,
        "dateCreatedField": "2024-01-17T13:55:57.9340317Z",
        "totalCreditsSpentField": 0,
        "unwrapFeeField": 0,
        "countryISOField": "GB",
        "companyCodeField": "11590614",
        "continuationKeysUsedField": []
    },
    "responseCodeField": "200"
}

Status Field Values

The statusField in the response indicates the current state of the ownership tree request:

Status	Description
SUCCESS	Ownership tree completed successfully
IN_PROGRESS	Report is being prepared, continue polling
COMPANY_NOT_FOUND	- Company could not be found - Company name matches were lower than the matching threshold - Enhanced profile failed - Multiple matches with the same name in multiple jurisdictions - Multiple matches with the same name in the same jurisdiction - Invalid Registration Authority - Possible TRUST / TRUSTEE
NO_SHAREHOLDERS	Enhanced profile does not have shareholder data available to display ownership
REGISTRY_NOT_AVAILABLE	Registry down or not available at this time
INSUFFICIENT_CREDITS	Not enough credits to complete the enhanced profile
INSUFFICIENT_MAX_CREDIT_COST	Maximum credit cost reached for the node to be searched
INSUFFICIENT_MAX_LAYERS	Maximum number of ownership layers reached
ORDER_NOT_FOUND	The specified order ID could not be found
SERVICE_UNAVAILABLE	UBO Verify service is currently unavailable

What information is returned by UBO Verify?

List of UBOs: Structured data format from a given root company.
Shareholder Information: Clear details to build a full ownership structure.
Node ID: A unique ID of the shareholder, traceable throughout the nodes.
Type: The type of shareholder (PERSON, COMPANY, or OTHER).
Edge Percentage: The percentage ownership of the entity shareholder.
Roll-up Percentage: The calculated percentage owned of the root company.
Enhanced Profiles: A URL link for each company in the ownership structure.
Company Code: The company number.
Registration Authority: The registry from which the information is retrieved.
Accompanying PDF Report: A downloadable report available via a URL link.

Reasons for non continuation

It is not always possible to find the UBO using registry data. For example, a shareholding company may exist under the exact same name in two different countries or the next level of ownership is in a country that doesn’t have director and shareholder information available at the registry. When the ownership tree analysis cannot continue, a reasonForNonContinuationField object is returned containing a typeField that indicates why the process stopped. Any layers of ownership already discovered will also be returned. The following table describes each reason for non continuation (RFNC) type and the recommended action:

RFNC Type	Description	Recommended Action
COMPANY_NOT_FOUND	The target company could not be located in the registry. This occurs when: Company name matches were below the matching threshold, Multiple matches exist with the same name in the same jurisdiction, Multiple matches exist with the same name in multiple jurisdictions, The company is possibly a Trust/Trustee	If `candidatesField` is populated with potential matches (up to 10 candidates), review the list and select the correct entity using its continuation key. If no candidates are provided, verify the company details and search criteria.
LOW_CONFIDENCE_MATCH	A single matching company was found, but confidence is insufficient to continue automatically. The candidates are returned for explicit selection.	Review the `candidatesField` and continue using the correct entity’s continuation key.
INSUFFICIENT_MAX_CREDIT_COST	The analysis stopped because the maximum allowed credit cost (`maxCreditCost` parameter) was exceeded before completing the ownership tree.	Increase the `maxCreditCost` parameter in a new request to allow the algorithm to retrieve additional Enhanced Profiles and continue deeper into the ownership structure. Previously retrieved profiles (within 24 hours) will be reused.
REGISTRY_NOT_AVAILABLE	The registry was temporarily unavailable when attempting to retrieve the Enhanced Profile. Maps to V1 Enhanced Profile response code 104.	Retry the request after a short delay. If the issue persists, check the registry status or contact support.
NO_SHAREHOLDERS	The Enhanced Profile for this company does not contain shareholder data, or the ownership percentage is null or an empty string (not 0). Registry data may not include shareholding information for this entity.	Manual research required. The company may be privately held with no public shareholder records, or the registry may not provide this data. Consider alternative data sources or manual verification.
INSUFFICIENT_CREDITS	The account has no credits available to order the next Enhanced Profile. Note: This should rarely occur as billing is now in arrears.	Contact your account manager to review credit allocation. Historically relevant; modern implementations use arrears billing.
DESERIALIZATION_ERROR_ENHANCED_PROFILE	An error occurred while processing the data returned from the V1 Enhanced Profile call. This indicates a technical issue with parsing the registry response.	This is a system error. Retry the request. If the error persists, contact Kyckr support with the order ID for investigation.
SERVER_ERROR	The V1 Enhanced Profile API returned an HTTP 500 error, indicating a server-side issue when retrieving company data.	This is a temporary server error. Retry the request after a short delay. If the issue persists, contact Kyckr support.
UNSUPPORTED_JURISDICTION	The registry ISO code for the shareholder’s jurisdiction is not in the list of supported registries for UBO Verify.	Manual research required for entities in this jurisdiction. Check the supported jurisdictions list to confirm registry coverage.
INSUFFICIENT_MAX_LAYERS	The analysis reached the maximum configured depth (`maxLayers` parameter) before identifying all UBOs.	Increase the `maxLayers` parameter if you need to unwrap deeper ownership structures. Consider whether additional layers are necessary for your compliance requirements.
SHAREHOLDING_TOO_LOW	A shareholder in the ownership chain has a recorded percentage too low to continue analysis of that branch.	Review the ownership structure to determine whether the shareholding is accurate or a data quality issue. This branch cannot be automatically continued.
INVALID_REGAUTH	The registration authority provided in the request is invalid. The V1 Enhanced Profile call returned code 106.	Verify the `regAuth` parameter matches the registration authority returned in the search response (`registrationAuthorityCodeField`). Only provide this parameter if returned by search.
POSSIBLE_PLC	The company was not found in the registry, and the company name format suggests it may be a publicly listed company (PLC).	Verify whether this is a publicly traded entity. PLCs may not require UBO analysis as ownership is typically publicly disclosed through stock exchanges.

Understanding the reasonForNonContinuationField

When continuation is blocked, the response includes a reasonForNonContinuationField object with the following structure:

typeField: The RFNC type from the table above (e.g., “COMPANY_NOT_FOUND”)
detailsField: A human-readable explanation of why the analysis stopped
candidatesField: An array of potential matches for selection. Populated for LOW_CONFIDENCE_MATCH, and for COMPANY_NOT_FOUND when multiple same-name matches exist

Continuation keys

A continuation key is used to continue unwrapping an ownership structure that has stopped due to a Reason for Non Continuation. For example, if the UBO search algorithm finds two companies with the same name in different countries, the reason for non-continuation would be: “Multiple matches with the same name in multiple jurisdictions.”

Example reason for non continuation response

"reasonForNonContinuationField": {
    "detailsField": "Multiple matches with the same name in multiple jurisdictions",
    "typeField": "COMPANY_NOT_FOUND",
    "candidatesField": [
        {
            "addressField": "Lutterstr.",
            "companyIdField": "HRB 30017",
            "companyNameField": "Dr. August Oetker Finanzierungs- und Beteiligungs-GmbH",
            "countryIsoField": "DE",
            "registrationAuthorityField": "Bielefeld",
            "continuationKeyField": "a66610c8-0cce-4343-a1b4-ace05362b5c8"
        },
        {
            "addressField": "Lutterstrasse 14, Bielefeld, D-33617",
            "companyIdField": "0630898292",
            "companyNameField": "Dr. August Oetker Finanzierungs- und Beteiligungs-GmbH",
            "countryIsoField": "BE",
            "continuationKeyField": "4291146e-17ef-4152-ae3f-059a37324897"
        }
    ... rest of response ...

As per the above example, there is a continuation key for each match, allowing an end user to manually select the correct company. Only one candidate from the candidatesField can be selected.

How to continue a UBO discovery using a continuation key

Use the original UBO create request and add the continuation key as a parameter. If there are more than one reasons for non continuation, there may be multiple continuation keys.

Example request with continuation key

curl --location 'https://rest.kyckr.com/core/uboverify/create/GB/04293376?continuationKeys=a66610c8-0cce-4343-a1b4-ace05362b5c8'
--header 'Authorization: {{apiKey}}'

Jointly held ownership

In jurisdictions such as Australia and New Zealand, shareholding can be shared. To highlight jointly owned shares there is a flag, linked ID and breakdown of shareholding in the nodes EDGE to display this.

Example jointly held shares

"edgesField": [
    {
        "nodeIdField": "7255f0c6-e911-4161-8afc-a49065fe6e7a",
        "typeField": "SHAREHOLDER",
        "percentageField": 100.00,
        "isCircularField": false,
        "shareholdingsField": [
            {
                "isJointlyHeldField": true,
                "jointHoldingGroupIdField": "64cb8fb8-0d07-4546-a92d-b200cd60a91c",
                "percentageField": 17.13
            },
            {
                "isJointlyHeldField": true,
                "jointHoldingGroupIdField": "e79ac474-bf07-473d-856d-78090c995dc1",
                "percentageField": 82.85
            },
            {
                "isJointlyHeldField": false,
                "percentageField": 0.02
            }
        ]
    },
    {
        "nodeIdField": "2a4083cb-bc50-4fd5-b65e-04d3c1801bef",
        "typeField": "SHAREHOLDER",
        "percentageField": 99.98,
        "isCircularField": false,
        "shareholdingsField": [
            {
                "isJointlyHeldField": true,
                "jointHoldingGroupIdField": "64cb8fb8-0d07-4546-a92d-b200cd60a91c",
                "percentageField": 17.13
            },
            {
                "isJointlyHeldField": true,
                "jointHoldingGroupIdField": "e79ac474-bf07-473d-856d-78090c995dc1",
                "percentageField": 82.85
            }
    ... rest of response ...

Cached Enhanced Profiles

Any Enhanced Profiles that have been ordered are reused by the Kyckr UBO Search algorithm for up to 24 hours.

When requesting a UBO ownership tree for a company, if there is a recently ordered Enhanced Profile, it will be reused.
If the UBO ownership tree is re-requested, previously ordered Enhanced Profiles (within the last 24 hours) will be reused, avoiding duplicate orders. This commonly occurs when rerunning the request with additional credits.

Example: Reuse of existing Enhanced Profile

An Enhanced Profile has been ordered for company A, but the shareholders for that company are not individuals. In this case, when ordering a UBO Verify Ownership Tree report, the original Enhanced Profile for company A is reused, so long as it has been ordered within a 24 hour window.

Example: Reuse of cached data in a 24 hour window

A company’s ownership tree is requested with maxCreditCost set to 6, and two of the companies in the tree (A, B) have had their ownership structure unwrapped. When the algorithm tries to unwrap (C) it has to stop with the reasonForNonContinuation being INSUFFICIENT_CREDITS. To complete the ownership tree with more credits, a second call to request ownership tree is placed. During the second call, the ownership tree is evaluated again. Profiles for (A and B) have already been ordered, so they are reused. Only the enhanced profile for company (C) will be ordered on the second run as all the data is relatively fresh.

Example: Refreshing after 24 hour window has elapsed

Consider the case above, where only companies (A and B) have been unwrapped, and more credits are required to complete the ownership tree report. If the second call to request ownership tree occurs after 24 hours, the underlying enhanced profile data for (A, B and C) are refreshed to ensure reporting accuracy.

Response Codes

CREATE

Success/Error	Code	Message
Successful transaction	201	SUCCESS
UBO account toggle OFF	403	You have insufficient permissions to access UBO Verify
Missing ISO / CODE	404	Resource not found
Missing maxCreditCost param	107	MaxCreditCost is required
Invalid ISO	107	Invalid jurisdiction.
Invalid CODE	105	Company not found.
Code pre-check failed	105	Company not found. Company number not valid format.
Invalid maxCreditCost	107	MaxCreditCost must be an integer greater than 0
Invalid uboThreshold	107	UboThreshold must be a whole number between 0 - 100

LIST

Success/Error	Code	Message
Not enough credits	200	Company Ownership Tree not generated - Root profile not generated due to insufficient credits.
MaxCreditCost to low to run first enhanced profile	200	Company Ownership Tree not generated - Root profile not generated due to insufficient credits.
Transaction in progress	200	Company Ownership Tree generation in progress
Transaction completed	200	UBO Response
Registry not available (EP 104)	200	Company Ownership Tree not generated - Registry not available at this time.
Service down	403	Service unavailable
UBO account toggle OFF	403	Order not found
Invalid orderID	403	You have insufficient permissions to access UBO Verify

Getting Started

Core Features

Registry Extracts and Filings

What is UBO Verify?

Search

About the registration authority returned from search

Request a report

Example create request for a UBO ownership tree report

Response

Download the UBO ownership tree report

Example poll request to download an UBO ownership tree report

Pending response

Example pending response

Status Field Values

What information is returned by UBO Verify?

Reasons for non continuation

Understanding the reasonForNonContinuationField

Continuation keys

Example reason for non continuation response

How to continue a UBO discovery using a continuation key

Example request with continuation key

Jointly held ownership

Example jointly held shares

Cached Enhanced Profiles

Example: Reuse of existing Enhanced Profile

Example: Reuse of cached data in a 24 hour window

Example: Refreshing after 24 hour window has elapsed

Response Codes

CREATE

LIST

​What is UBO Verify?

​Search

​About the registration authority returned from search

​Request a report

​Example create request for a UBO ownership tree report

​Response

​Download the UBO ownership tree report

​Example poll request to download an UBO ownership tree report

​Pending response

​Example pending response

​Status Field Values

​What information is returned by UBO Verify?

​Reasons for non continuation

​Understanding the reasonForNonContinuationField

​Continuation keys

​Example reason for non continuation response

​How to continue a UBO discovery using a continuation key

​Example request with continuation key

​Jointly held ownership

​Example jointly held shares

​Cached Enhanced Profiles

​Example: Reuse of existing Enhanced Profile

​Example: Reuse of cached data in a 24 hour window

​Example: Refreshing after 24 hour window has elapsed

​Response Codes

​CREATE

​LIST

What is UBO Verify?

Search

About the registration authority returned from search

Request a report

Example create request for a UBO ownership tree report

Response

Download the UBO ownership tree report

Example poll request to download an UBO ownership tree report

Pending response

Example pending response

Status Field Values

What information is returned by UBO Verify?

Reasons for non continuation

Understanding the reasonForNonContinuationField

Continuation keys

Example reason for non continuation response

How to continue a UBO discovery using a continuation key

Example request with continuation key

Jointly held ownership

Example jointly held shares

Cached Enhanced Profiles

Example: Reuse of existing Enhanced Profile

Example: Reuse of cached data in a 24 hour window

Example: Refreshing after 24 hour window has elapsed

Response Codes

CREATE

LIST