Overview
This release contains major improvements to UBO Verify, Kyckr’s cross-border ownership discovery tool. UBO Verify gives you more accurate ownership discovery, complete transparency into matching decisions, and clear next steps when the algorithm needs your input. Taken together, these enhancements reduce manual research time for analysts, provide stronger audit documentation, and help you achieve higher UBO discovery rates with less guesswork.Improved entity resolution
UBO Verify uses a proprietary algorithm to match entity names in the shareholder list of the root company you are verifying with registered companies globally. An entity is resolved automatically only when the algorithm finds a single, unambiguous match. Where the shareholder record includes a usable address, the match is made within a jurisdiction derived from that address; where it does not, the match is made on the company name alone. Each automatically resolved entity now records the basis of its match inmatchVerificationField, so you can see how strong the evidence was.
Where matches compete, or a single match is too close to call, nothing is auto-selected — you receive candidate options (with addresses) to choose from, and your selection is recorded for audit. This increases the likelihood of further automated discovery while avoiding a potentially incorrect match.
This is particularly valuable for data sources like UK Companies House, where shareholder declarations often contain only company names without jurisdiction indicators. A name-only match cannot exclude a matching company in another jurisdiction, so matchVerificationField lets you flag those weaker matches for closer review.
- Match basis recorded:
matchVerificationFielddistinguishes a name-only match (NAME_ONLY) from a name match within a derived jurisdiction (NAME_AND_JURISDICTION) - Explicit low-confidence handling: a
LOW_CONFIDENCE_MATCHreason when a single match has insufficient confidence, andCOMPANY_NOT_FOUNDwhen no match is found or multiple companies share the same name — both return candidates with continuation keys - Address context for verification: compare parent-recorded shareholder addresses against resolved entity addresses
Full audit trail for every resolution decision
Each entity in your ownership tree now documents exactly how it was matched (algorithm or user-selected), preserves the original shareholder information from the root company’s declarations, and maintains a complete version history across order IDs. This means review teams and auditors can trace every decision in your ownership investigation - understanding not just the final structure, but the evidence and logic behind each entity resolution. Whether you’re responding to compliance queries, onboarding new team members to ongoing investigations, or supporting escalations, the complete context is preserved and accessible.- Entity selection metadata: See whether each entity was
ALGORITHMresolved orUSER_SELECTED - Edge-level context: Shareholder names and addresses as recorded by the parent company
- Version history: Full audit trail of continuation decisions across order IDs
Intelligent guidance on what to do next
New status fields and metrics eliminate guesswork from your UBO investigations. The system now tells you immediately where you stand: Are UBOs identified? Is coverage incomplete? Which profiles should you order for maximum coverage improvement? You’ll see quantified metrics for UBO coverage and shareholding coverage, understand exactly what percentage of ownership remains unordered, and receive prioritized recommendations on which entities to investigate next. The system also uses fuzzy name matching to surface potential consolidated ownership - for instance, when the same beneficial owner appears with slight name variations across different entities’ shareholder declarations - helping you identify UBOs that might otherwise remain hidden.- Status at a glance: Know immediately if UBOs are identified, coverage is incomplete, or action is required at each step (e.g. if credit spend limited by the user)
- Quantified metrics: UBO coverage, shareholding coverage, and unordered ownership percentages
- Prioritized recommendations: Ranked list of profiles to order for maximum coverage improvement (e.g. where paused due to credit spend or user entity selection required)
- Potential UBO detection: Fuzzy name matching surfaces hidden consolidated ownership (e.g. where shareholder names vary across entity declarations)
What stays the same
The ownership graph structure and API compatibility remain unchanged, ensuring seamless integration with your existing workflows.Key improvements
Analysis status
Know immediately whether you’ve fully identified beneficial owners and what action you need to take. Full analysis details at top level:
The
blockingReasonField provides additional context when the status indicates an incomplete analysis, helping you understand what’s preventing completion.
UBO discovery levels
We now distinguish between confirmed UBOs (at or above threshold), and potential UBOs. Potential UBOs consist of two types:- Additional discovery could increase the holdings over the threshold.
- Name variations could be hiding aggregrate ownership over the threshold.
Coverage metrics
Quantify your analysis quality with precise metrics. ThemetricsField in uboAnalysisField provides objective measurements of how complete your UBO analysis is:
Practical interpretations:
- 100% shareholdingCoverage + low uboCoverage: You’ve explored the entire tree but many branches end at companies without enhanced profiles. Use
requiredProfilesFieldto prioritize orders. - High unpurchasedTotal: Clear gap to fill. Each profile order will reduce this value and likely improve uboCoverage.
Shareholder name and address on edges
Edges now include the shareholder name and address as recorded in the company extract. This provides critical transparency for understanding name variations and verifying entity matches.
Multi-parent scenarios:
When the same entity appears as a shareholder in multiple share structures, each entry may record the name differently:
- Entity A records: “ESSO UK LIMITED”
- Entity B records: “ESSO (UK) LTD”
- Resolved entity canonical name: “ESSO UK LIMITED”
nameField preserves each entity’s original shareholder name, enabling you to see exactly what data was used for matching decisions.
Required profile recommendations
Stop guessing which entities to unwrap next. We prioritize them for you. TherequiredProfilesField array in uboAnalysisField tells you exactly which companies need enhanced profile data, ranked by potential impact:
Potential beneficial owners
Detect hidden consolidated ownership through name matching, and/or unordered profiles. Some beneficial owners appear under multiple name variations—“John Smith” and “J. Smith” might be the same person. ThepotentialBeneficialOwnersField in uboAnalysisField helps to identify these potential matches:
isFuzzyGroupField: true– Members identified through name similarity (first name + last name matching)isFuzzyGroupField: false– Exact name matches or single-member group (no matching needed)canonicalNameField– Representative name chosen for the group (normalized)totalOwnershipField– Sum of all members’ ownership percentages
Entity resolution & continuation tracking
Track exactly how each entity was resolved and maintain a complete audit trail of your ownership tree’s evolution through continuations. When UBO Verify encounters ambiguous company matches (multiple companies with the same name), you use continuation keys to specify which entity to include. These new fields document those decisions and track how your ownership tree has evolved over time.Improved entity resolution algorithm
The entity resolution algorithm resolves an entity automatically only when it finds a single, unambiguous match. Where the shareholder record carries a usable address, the match is made within a jurisdiction derived from that address; otherwise it is made on the company name alone. Each automatic resolution records the basis of its match inmatchVerificationField:
NAME_ONLY— matched on company name alone, with no jurisdiction filter applied. This is the weakest basis: a name search does not cover every jurisdiction and company names are not globally unique, so a matching entity in another jurisdiction cannot be excluded. It warrants closer review.NAME_AND_JURISDICTION— matched on company name within a jurisdiction derived from the shareholder address. A stronger basis, though the jurisdiction is a best-effort derivation rather than a verified address match.
- A single match with insufficient confidence returns a
LOW_CONFIDENCE_MATCHreason. - No match — or several companies sharing the same name — returns a
COMPANY_NOT_FOUNDreason. - Both surface candidate options with continuation keys for explicit selection.
USER_SELECTED entries in entitySelectionMetadataField wherever you resolve one of these manually — each a verified choice.
COMPANY_NOT_FOUND handling
When the algorithm cannot confidently resolve an entity, it returns aCOMPANY_NOT_FOUND reason with candidate details:
- Review the
candidatesFieldarray - each candidate includes address for verification - Compare addresses against known shareholder records or other due diligence sources
- Select the correct candidate by including its
continuationKeyFieldin your next request - The selected entity will appear with
sourceField: "USER_SELECTED"inentitySelectionMetadataField
Entity addresses
All entities in the ownership tree now include their legal or registered address when available from Enhanced Profile data:addressField helps you quickly identify specific entities and provides additional context for company verification without needing to fetch the full Enhanced Profile.
Entity selection metadata
Every node now documents how that entity was selected with theentitySelectionMetadataField. An algorithm-resolved node records when it was resolved in dateSelectedField and the basis of its match in matchVerificationField:
Note: When the algorithm encounters a
LOW_CONFIDENCE_MATCH status (due to insufficient confidence for automatic resolution), it will stop and provide candidate options with continuation keys. After you select a candidate using the continuation key, that entity will appear with sourceField: "USER_SELECTED" in the entitySelectionMetadataField.
Continuation selection history
TheselectedCandidatesField provides a complete audit trail of every continuation decision:
- Parent node: Where in the tree multiple candidates appeared (
parentNodeIdField) - Selected candidate: Which specific company you chose from the options (
candidateField) - Resulting node: The node ID that was created from this selection (
nodeIdField) - When selected: Timestamp of the decision (
dateSelectedField) - Which version: The order ID when this selection was made (
orderIdField)
Ownership tree version history
ThepreviousVersionsField tracks the evolution of your ownership tree through multiple continuations:
- Initial UBO request creates order ID
331999 - Encounter ambiguous match, select continuation → creates order ID
332003 - Select another continuation → creates current order ID
331997 - Current tree’s
previousVersionsFieldshows:["332003", "331999"]
Complete example
Here’s how all the entity resolution fields work together in a real ownership tree:- The root company (level 1) was automatically resolved (
sourceField: "ALGORITHM") - The level 2 company was manually selected via continuation (
sourceField: "USER_SELECTED") - The
selectedCandidatesFieldshows which candidate was chosen and when - The
previousVersionsFieldshows two prior versions before reaching the current state - Both entities include their registered addresses for easy identification
End-to-end workflow: Resolving a COMPANY_NOT_FOUND
This example shows the complete workflow from encountering a low-confidence match to resolving it with user selection. Step 1: Initial request returns COMPANY_NOT_FOUND- Your records show the shareholder is at “123 Business Park, London”
- First candidate matches - use its continuation key
USER_SELECTED source, providing a complete audit trail of who made the decision, when, and why.
Migration notes
All new fields are backwards compatible additions. Existing API integrations will continue to work without modification.Analysis fields
- The
uboAnalysisFieldis recommended to guide the UBO discovery process to the required goal, limited only by registry data. - Existing
ultimateBeneficialOwnersFieldstructure is unchanged; new fields extend the schema - All existing request parameters and response fields remain unchanged
Entity resolution fields
- The
addressFieldis added to entity and edge objects when address data is available from Enhanced Profiles - The
entitySelectionMetadataFieldappears on nodes to document how entities were resolved- Only present for entities that were explicitly resolved (either by algorithm or user selection)
- Contains
sourceField(ALGORITHM or USER_SELECTED) with optional continuation details
- The
selectedCandidatesFieldis populated only when continuations have been used- Provides audit trail of which candidates were selected during disambiguation
- The
previousVersionsFieldis populated only when the current tree is a continuation of prior versions- Shows the order ID chain leading to the current ownership tree state