Unwrap Ownership - Kyckr Developer Portal

UBO Verify automates the analysis of corporate ownership structures, retrieving Enhanced Profiles across jurisdictions and calculating beneficial ownership at each layer of the tree. What would take analysts hours to piece together manually is resolved in minutes.

How it works

UBO Verify works by iteratively retrieving Enhanced Profiles for each entity in the ownership structure of the root company, tracing shareholders layer by layer until it reaches individuals or terminates for a documented reason. The process follows three steps:

Search for the root company

Use Company Search to locate the entity and obtain its codeField and jurisdiction ISO. If the search response includes a registrationAuthorityCodeField, note this value — it is required when ordering the UBO report for certain jurisdictions (e.g. Germany, Canada).

Request an ownership tree

Submit the root company’s code, country ISO, and your cost parameters. Kyckr will begin retrieving Enhanced Profiles for each shareholder layer and return an orderIdField for polling.

Poll for results

Retrieve the ownership tree using the order ID. While the analysis is in progress, the response returns IN_PROGRESS. Once complete, the tree, UBO list, coverage metrics, and any recommended next actions are returned.

Request an ownership tree

curl --location \
  'XXXX/create/GB/09657876?uboThreshold=25&maxCreditCost=50&maxLayers=5' \
  --header 'Authorization: {{apiKey}}'

Parameters

Parameter	Type	Required	Description
`CompanyCode`	path	Yes	The `codeField` of the root entity, obtained from Company Search
`CountryIso`	path	Yes	Two-letter ISO country code for the root entity’s jurisdiction
`regAuth`	query	Conditional	Required when the search returns a `registrationAuthorityCodeField` (e.g. for DE, CA)
`maxCreditCost`	query	Yes	Maximum credits to spend on this request. Must be a positive integer
`uboThreshold`	query	No	Ownership percentage required to qualify as a UBO. Defaults to 25. Accepts 1–100
`maxLayers`	query	No	Maximum ownership layers to unwrap. Minimum value: 3
`continuationKeys`	query	No	One or more continuation keys to resolve previously ambiguous entity matches

Response

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

Use the orderIdField to retrieve results.

Retrieve the ownership tree

Poll the list endpoint with the orderIdField until statusField is no longer IN_PROGRESS.

curl --location \
  'XXXX/list/2614793' \
  --header 'Authorization: {{apiKey}}'

Processing time depends on the depth and complexity of the ownership structure. Shallow trees with a small number of corporate shareholders complete quickly; deep, multi-jurisdiction structures take longer as each layer requires a live Enhanced Profile retrieval.

Ownership tree status values

Status	Description
`IN_PROGRESS`	Analysis is running. Continue polling
`SUCCESS`	Ownership tree completed
`COMPANY_NOT_FOUND`	The root company could not be located
`NO_SHAREHOLDERS`	The root company has no shareholder data available
`REGISTRY_NOT_AVAILABLE`	The relevant registry was unavailable at the time of the request
`INSUFFICIENT_CREDITS`	Insufficient credits to retrieve the root company’s Enhanced Profile
`INSUFFICIENT_MAX_CREDIT_COST`	The `maxCreditCost` was reached before the root profile could be retrieved
`INSUFFICIENT_MAX_LAYERS`	The configured layer limit was reached
`ORDER_NOT_FOUND`	The specified order ID does not exist
`SERVICE_UNAVAILABLE`	UBO Verify is temporarily unavailable

Understanding the response

A completed ownership tree response contains several distinct sections. The following example illustrates the key fields:

{
  "ownershipTreeField": {
    "idField": "2700226",
    "nameField": "HAND MADE HAIR LTD",
    "statusField": "SUCCESS",
    "uboThresholdField": 25,
    "nodesField": [...],
    "ultimateBeneficialOwnersField": [
      {
        "idField": "907bae93-f2d4-4c8c-95b2-f10fe9c89f2f",
        "nameField": "JOSHUA JOHN WOOD",
        "percentageField": "46.14",
        "entityTypeField": "PERSON"
      }
    ]
  },
  "uboAnalysisField": {
    "statusField": "INCOMPLETE_REQUIRED_PROFILES",
    "metricsField": {
      "uboCoverageField": 46.14,
      "shareholdingCoverageField": 100.0,
      "unpurchasedTotalField": 24.06
    },
    "requiredProfilesField": [...],
    "potentialBeneficialOwnersField": [...]
  }
}

Nodes

The nodesField array contains every entity in the ownership tree. Each node represents either a company or a person, with edges describing the shareholding relationship to the node below it.

Field	Description
`levelField`	Depth in the ownership tree. Level 1 is the root company
`entityField.idField`	Unique node identifier, consistent across polling requests
`entityField.typeField`	`COMPANY`, `PERSON`, or `OTHER`
`entityField.nameField`	Entity name
`entityField.countryISOField`	Jurisdiction of the entity
`entityField.companyCodeField`	Company registration number (companies only)
`entityField.addressField`	Registered address, when available from Enhanced Profile data
`edgesField`	Shareholding relationships connecting this node to its parent

Edges

Each edge records the shareholding relationship between a parent entity and a child shareholder.

Field	Description
`nodeIdField`	The ID of the shareholder node
`typeField`	Always `SHAREHOLDER`
`percentageField`	Percentage ownership held at this edge
`nameField`	Shareholder name as recorded in the parent company’s declarations
`addressField`	Shareholder address as recorded in the parent company’s declarations
`isCircularField`	`true` if circular ownership is detected
`shareholdingsField`	Breakdown of individual shareholding entries, including jointly held shares

The nameField and addressField on an edge reflect how the parent company recorded that shareholder — which may differ from the entity’s canonical name and address. Comparing edge.nameField against node.entity.nameField helps you identify name variations and verify that the resolved entity is the correct match.

Jointly held shares

In jurisdictions such as Australia and New Zealand, shares may be held jointly. The shareholdingsField on an edge captures this:

"shareholdingsField": [
  {
    "isJointlyHeldField": true,
    "jointHoldingGroupIdField": "64cb8fb8-0d07-4546-a92d-b200cd60a91c",
    "percentageField": 17.13
  },
  {
    "isJointlyHeldField": false,
    "percentageField": 0.02
  }
]

Entries sharing a jointHoldingGroupIdField belong to the same jointly held block.

Analysis insights

The uboAnalysisField provides a structured assessment of your UBO discovery, including coverage metrics, recommended next steps, and detection of potential consolidated ownership.

Analysis status

The statusField in uboAnalysisField tells you immediately whether the investigation is complete and, if not, what is preventing it.

Status	Meaning
`COMPLETE_UBO_IDENTIFIED`	All UBOs above the threshold have been identified
`COMPLETE_BELOW_THRESHOLD`	Analysis is complete, but no entities reached the UBO threshold
`INCOMPLETE_REQUIRED_PROFILES`	Additional Enhanced Profiles need to be purchased to continue
`INCOMPLETE_NO_SHAREHOLDERS`	The root company has no shareholder data available
`INCOMPLETE_BLOCKING_RFNC`	One or more nodes have reasons for non-continuation that require action
`INCOMPLETE_CIRCULAR_OWNERSHIP`	A circular ownership structure has been detected
`INDETERMINATE_CORRUPT_DATA`	Shareholder data from the registry is corrupt
`INDETERMINATE_INSUFFICIENT_DATA`	Shareholding coverage is below the required threshold for conclusive analysis
`PLC_NO_SHAREHOLDERS_EXPECTED`	The root entity is a public company; absence of shareholder data is expected
`UNKNOWN`	Fallback value — should not occur in practice

When statusField indicates an incomplete analysis, blockingReasonField provides additional context explaining specifically what is preventing completion.

Coverage metrics

The metricsField quantifies how complete your analysis is:

"metricsField": {
  "uboCoverageField": 46.14,
  "shareholdingCoverageField": 100.0,
  "unpurchasedTotalField": 24.06
}

Metric	Description
`uboCoverageField`	Percentage of root company ownership traced to identified UBOs
`shareholdingCoverageField`	Percentage of the ownership tree that has been explored. For a conclusive analysis, this should exceed `100 - uboThreshold`
`unpurchasedTotalField`	Percentage of ownership held by entities for which no Enhanced Profile has been purchased

Interpreting the metrics:

If shareholdingCoverageField is 100% but uboCoverageField is low, the entire tree has been explored but many branches end at companies without Enhanced Profiles. Use requiredProfilesField to identify which profiles to purchase next.
If unpurchasedTotalField is high, there is a clear gap to close. Each profile purchase reduces this value and is likely to improve uboCoverageField.

Required profile recommendations

When further investigation is possible, requiredProfilesField provides a ranked list of the entities whose Enhanced Profiles would have the greatest impact on your UBO coverage:

"requiredProfilesField": [
  {
    "entityIdField": "9c1b25c1-6a63-427f-8154-05c03a1dbf24",
    "entityNameField": "INDEX VENTURES IX (JERSEY) L.P.",
    "companyCodeField": "REG123"
  }
]

Use the entityIdField to locate the node in nodesField and the companyCodeField to retrieve its Enhanced Profile directly if needed.

Potential beneficial owners

The potentialBeneficialOwnersField surfaces cases where the same individual may appear under multiple name variations across different shareholder declarations. Where combined ownership across those variations exceeds the UBO threshold, the system flags this for review.

"potentialBeneficialOwnersField": [
  {
    "canonicalNameField": "JONATHAN DAVIES",
    "totalOwnershipField": 29.62,
    "isFuzzyGroupField": true,
    "membersField": [
      { "nameField": "Jonathan Gray Davies", "ownershipField": 5.56 },
      { "nameField": "J. Davies", "ownershipField": 24.06 }
    ]
  }
]

Field	Description
`canonicalNameField`	Representative name chosen for the group
`totalOwnershipField`	Combined ownership percentage across all group members
`isFuzzyGroupField`	`true` if members were grouped by name similarity; `false` if exact name matches
`membersField`	Individual entries contributing to the group

Fuzzy grouping is based on first name and last name similarity and is conservative by design. You should verify potential UBO matches through additional due diligence before treating them as confirmed.

Entity resolution

UBO Verify matches company names from shareholder declarations against registered entities globally. Version 2 introduces a stricter resolution algorithm that requires address-based or jurisdiction-specific confirmation before automatically selecting a company match. This means you may encounter more situations requiring manual input — but each resolution will be a high-confidence, verifiable match rather than a potentially incorrect automatic one.

Automatic resolution

When the algorithm can confidently identify a unique matching entity, it resolves the node automatically. This is indicated in the node’s entitySelectionMetadataField:

"entitySelectionMetadataField": {
  "sourceField": "ALGORITHM"
}

Ambiguous matches and continuation keys

When the algorithm cannot resolve a match with sufficient confidence — for example, when multiple companies share the same name in the same jurisdiction — it returns a COMPANY_NOT_FOUND reason for non-continuation and provides candidate options:

"reasonForNonContinuationField": {
  "typeField": "COMPANY_NOT_FOUND",
  "detailsField": "Multiple matches with the same name in the same jurisdiction",
  "candidatesField": [
    {
      "companyNameField": "ACME HOLDINGS LTD",
      "companyIdField": "12345678",
      "countryIsoField": "GB",
      "addressField": "123 Business Park, London",
      "continuationKeyField": "ba26a0bb-f632-4421-8092-58ed3a76d3be"
    },
    {
      "companyNameField": "ACME HOLDINGS LIMITED",
      "companyIdField": "87654321",
      "countryIsoField": "GB",
      "addressField": "456 Industrial Estate, Manchester",
      "continuationKeyField": "cd38b1cc-g743-5532-9193-69fe4b87e4cf"
    }
  ]
}

To continue the investigation, review the candidates and pass the continuationKeyField of the correct entity in a new create request:

curl --location \
  'XXXX/create/GB/12345678?continuationKeys=ba26a0bb-f632-4421-8092-58ed3a76d3be' \
  --header 'Authorization: {{apiKey}}'

After selection, the resolved node is marked with USER_SELECTED:

"entitySelectionMetadataField": {
  "sourceField": "USER_SELECTED",
  "continuationKeyField": "ba26a0bb-f632-4421-8092-58ed3a76d3be",
  "dateSelectedField": "2026-01-15T10:45:00.0000000Z"
}

If there are multiple unresolved nodes in the tree, there may be multiple continuation keys. You can pass them as a comma-separated list in a single request.

Only one candidate can be selected per ambiguous node. If you later determine the selection was incorrect, you will need to submit a new create request with a different continuation key.

Audit trail

Every ownership tree maintains a complete record of how it was built and how it has evolved through continuations.

Continuation selection history

The selectedCandidatesField documents every manual disambiguation decision made during the investigation:

"selectedCandidatesField": [
  {
    "parentNodeIdField": "2e777682-3efc-478f-8472-fd78efb7f60e",
    "candidateField": {
      "companyNameField": "ACME HOLDINGS LTD",
      "companyIdField": "12345678",
      "continuationKeyField": "ba26a0bb-f632-4421-8092-58ed3a76d3be"
    },
    "nodeIdField": "dac4985e-501d-41f7-933b-44c0b8de0f54",
    "dateSelectedField": "2026-01-15T10:45:00.0000000Z",
    "orderIdField": "331999"
  }
]

Version history

The previousVersionsField records the chain of order IDs that preceded the current tree:

{
  "idField": "331997",
  "previousVersionsField": ["332003", "331999"]
}

This allows you to trace every continuation decision back to the initial request, providing a full audit trail for compliance and review purposes.

Reasons for non-continuation

When the ownership tree algorithm cannot continue down a branch, it returns a reasonForNonContinuationField on the relevant node. Any layers already discovered are always returned.

Type	Description	Recommended action
`COMPANY_NOT_FOUND`	The entity could not be uniquely resolved. May include candidates if partial matches were found	Review `candidatesField` and continue using the appropriate continuation key
`INSUFFICIENT_MAX_CREDIT_COST`	The `maxCreditCost` limit was reached before this node could be retrieved	Resubmit with a higher `maxCreditCost`. Previously purchased profiles within the 24-hour window are reused
`REGISTRY_NOT_AVAILABLE`	The registry was temporarily unavailable	Retry after a short delay. If the issue persists, contact support
`NO_SHAREHOLDERS`	The Enhanced Profile for this entity contains no shareholder data	Manual research required. The registry may not publish shareholding information for this entity
`INSUFFICIENT_CREDITS`	The account has insufficient credits	Contact your account manager
`DESERIALIZATION_ERROR_ENHANCED_PROFILE`	A technical error occurred processing the Enhanced Profile response	Retry. If the error persists, contact support with the order ID
`SERVER_ERROR`	The Enhanced Profile API returned an HTTP 500 error	Retry after a short delay
`UNSUPPORTED_JURISDICTION`	The entity’s jurisdiction is not supported by UBO Verify	Manual research required. See Supported jurisdictions
`INSUFFICIENT_MAX_LAYERS`	The configured `maxLayers` depth was reached	Increase `maxLayers` if deeper analysis is required
`SHAREHOLDING_TOO_LOW`	A shareholder has a recorded ownership percentage of exactly 0%	Review whether this is a data quality issue. This branch cannot be automatically continued
`INVALID_REGAUTH`	The `regAuth` parameter provided is invalid	Verify that the `regAuth` value matches the `registrationAuthorityCodeField` returned by search
`POSSIBLE_PLC`	The company name format suggests a publicly listed company	Verify whether the entity is publicly traded. PLCs are typically excluded from UBO analysis requirements

Cached Enhanced Profiles

Enhanced Profiles purchased as part of a UBO Verify request are cached for 24 hours. If you resubmit a request — for example, with a higher maxCreditCost or an additional continuation key — profiles retrieved within that window are reused, avoiding duplicate purchases. After 24 hours, all underlying profiles are refreshed to ensure reporting accuracy.

Response codes

Create endpoint

Code	Message	Description
201	SUCCESS	Ownership tree request accepted
403	You have insufficient permissions to access UBO Verify	UBO Verify is not enabled on your account
404	Resource not found	Missing ISO or company code
107	MaxCreditCost is required	The `maxCreditCost` parameter was not provided
107	Invalid jurisdiction	The `CountryIso` provided is not valid
105	Company not found	The `CompanyCode` provided could not be found or is not in the correct format
107	MaxCreditCost must be an integer greater than 0	Invalid `maxCreditCost` value
107	UboThreshold must be a whole number between 0 - 100	Invalid `uboThreshold` value

List endpoint

Code	Message	Description
200	—	Successful retrieval (covers in-progress and completed states)
403	Service unavailable	UBO Verify is temporarily unavailable
403	Order not found	The UBO Verify feature is not enabled, or the order ID is invalid

Company Search

Find the root entity and retrieve its codeField before requesting an ownership tree

Enhanced Profile

Retrieve full company profiles including representatives and shareholders

UBO Verify API Reference

Full request and response schema for the UBO Verify endpoints

UBO Verify Release Note

Summary of all changes introduced in v2

Documentation Index

​How it works

​Request an ownership tree

​Parameters

​Response

​Retrieve the ownership tree

​Ownership tree status values

​Understanding the response

​Nodes

​Edges

​Jointly held shares

​Analysis insights

​Analysis status

​Coverage metrics

​Required profile recommendations

​Potential beneficial owners

​Entity resolution

​Automatic resolution

​Ambiguous matches and continuation keys

​Audit trail

​Continuation selection history

​Version history

​Reasons for non-continuation

​Cached Enhanced Profiles

​Response codes

​Create endpoint

​List endpoint

Company Search

Enhanced Profile

UBO Verify API Reference

UBO Verify Release Note

How it works

Request an ownership tree

Parameters

Response

Retrieve the ownership tree

Ownership tree status values

Understanding the response

Nodes

Edges

Jointly held shares

Analysis insights

Analysis status

Coverage metrics

Required profile recommendations

Potential beneficial owners

Entity resolution

Automatic resolution

Ambiguous matches and continuation keys

Audit trail

Continuation selection history

Version history

Reasons for non-continuation

Cached Enhanced Profiles

Response codes

Create endpoint

List endpoint