UBO Verify – Release Note

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.

Previously, if no unique company register identifiers were present in the shareholder information, the algorithm would match on name similarity across a global index of company data (using root jurisdiction to improve effectiveness). Although effective in most scenarios, edge cases – such as jurisdictions with identical, or similar, company suffixes – could halt the discovery process.

Now, the algorithm requires address-based confirmation before auto-selecting company matches. When confidence is insufficient, the user receives candidate options (with addresses) which they can select from to continue the investigation - increasing the likelihood of further automated UBO discovery and avoiding a potentially incorrect match.

This is particularly valuable for data sources like UK Companies House, where shareholder declarations contain only company names without jurisdiction indicators.

• Improved entity resolution: Name-only matching no longer resolves cases automatically
• Explicit low-confidence handling: COMPANY_NOT_FOUND status with candidates and continuation keys
• Address-based verification: Data models allow users to 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 ALGORITHM resolved or USER_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 purchase for maximum coverage improvement?

You'll see quantified metrics for UBO coverage and shareholding coverage, understand exactly what percentage of ownership remains unpurchased, 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 unpurchased ownership percentages
• Prioritized recommendations: Ranked list of profiles to purchase 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:

{
  "uboAnalysisField": {
    "statusField": "INCOMPLETE_REQUIRED_PROFILES",
    "blockingReasonField": "NO_SHAREHOLDERS (FR)"
  }
}

Status values:

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.

For more information, see the below section – 'Potential beneficial owners'

Coverage metrics

Quantify your analysis quality with precise metrics.

The metricsField in uboAnalysisField provides objective measurements of how complete your UBO analysis is:

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

Metric definitions:

Practical interpretations:

• 100% shareholdingCoverage + low uboCoverage: You've explored the entire tree but many branches end at companies without enhanced profiles. Use requiredProfilesField to prioritize purchases.
• High unpurchasedTotal: Clear gap to fill. Each profile purchase 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.

{
  "edgesField": [
    {
      "nodeIdField": "dcc4311c-d1dd-4fe1-9fd6-178f691c2160",
      "typeField": "SHAREHOLDER",
      "percentageField": 11.22,
      "nameField": "ESSO UK LIMITED",
      "addressField": "Ermyn House, Ermyn Way, Leatherhead, Surrey, KT22 8UX",
      "shareholdingsField": [
        {
          "isJointlyHeldField": false,
          "percentageField": 11.22
        }
      ]
    }
  ]
}

How to use edge-level data:

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"

The edge-level 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.

The requiredProfilesField array in uboAnalysisField tells you exactly which companies need enhanced profile data, ranked by potential impact:

{
  "uboAnalysisField": {
    "requiredProfilesField": [
      {
        "entityIdField": "9c1b25c1-6a63-427f-8154-05c03a1dbf24",
        "entityNameField": "INDEX VENTURES IX (JERSEY) L.P.",
        "companyCodeField": "REG123"
      },
      {
        "entityIdField": "df324799-07dd-4b6a-b400-698626aa15ac",
        "entityNameField": "PACIFIC HOLDINGS LIMITED"
      }
    ]
  }
}

Potential beneficial owners

Detect hidden consolidated ownership through name matching, and/or unpurchased profiles.

Some beneficial owners appear under multiple name variations—"John Smith" and "J. Smith" might be the same person. The potentialBeneficialOwnersField in uboAnalysisField helps to identify these potential matches:

{
  "uboAnalysisField": {
    "potentialBeneficialOwnersField": [
      {
        "canonicalNameField": "JONATHAN DAVIES",
        "totalOwnershipField": 29.62,
        "isFuzzyGroupField": true,
        "membersField": [
          {
            "nameField": "Jonathan Gray Davies",
            "ownershipField": 5.56
          },
          {
            "nameField": "JONATHAN GRAY DAVIES",
            "ownershipField": 0.0
          },
          {
            "nameField": "J. Davies",
            "ownershipField": 24.06
          }
        ]
      },
      {
        "canonicalNameField": "THOMAS WALKER",
        "totalOwnershipField": 30.94,
        "isFuzzyGroupField": false
      }
    ]
  }
}

How grouping works:

• 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

Use case: In the example above, if "Jonathan Gray Davies" and "J. Davies" are the same person, their combined 29.62% ownership would exceed a 25% UBO threshold—flagging them for verification even though each individual entry is below threshold.

Note: Fuzzy matching is conservative and based on first name + last name similarity. You should verify these matches through additional due diligence before concluding they're the same individual.

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 has been enhanced to require address-based or jurisdiction-specific confirmation before automatically selecting a company match. This change means you may encounter more situations requiring manual confirmation, but it significantly reduces false positives.

What changed:

• Address-based confirmation: Resolution now requires address-based or jurisdiction-specific confirmation before auto-selecting a company
• Geocoding: ISO country codes are derived using geocoding instead of heuristic string parsing, improving accuracy
• PSC address fallback: For UK/GB companies, PSC (People with Significant Control) addresses are used as a fallback when geocoding primary addresses
• Legal suffix signals: Country-specific legal suffixes (e.g., PTE LTD, PTY LTD, B.V.) are used as additional confidence signals in the matching process
• Low-confidence handling: Low-confidence matches are no longer silently accepted

What happens instead:

If a single match is found but confidence is insufficient, the algorithm:

1. Stops the automatic resolution
2. Returns a structured LOW_CONFIDENCE_MATCH status
3. Provides candidate options with continuation keys for explicit user selection

This approach avoids false positives while still allowing user-driven continuation through continuation keys. You'll see more USER_SELECTED entries in entitySelectionMetadataField as a result, but each selection will be a user verified, high-confidence match.

COMPANY_NOT_FOUND handling

When the algorithm cannot confidently resolve an entity, it returns a COMPANY_NOT_FOUND reason with candidate details:

{
  "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"
      }
    ]
  }
}

Resolving low-confidence matches:

1. Review the candidatesField array - each candidate includes address for verification
2. Compare addresses against known shareholder records or other due diligence sources
3. Select the correct candidate by including its continuationKeyField in your next request
4. The selected entity will appear with sourceField: "USER_SELECTED" in entitySelectionMetadataField

Entity addresses

All entities in the ownership tree now include their legal or registered address when available from Enhanced Profile data:

{
  "nodesField": [
    {
      "levelField": 2,
      "entityField": {
        "idField": "dac4985e-501d-41f7-933b-44c0b8de0f54",
        "typeField": "COMPANY",
        "nameField": "WOLTERS KLUWER HOLDINGS (UK) LIMITED",
        "countryISOField": "GB",
        "companyCodeField": "01329311",
        "addressField": "145 London Road, Kingston Upon Thames, Surrey, KT2 6SR"
      }
    }
  ]
}

The 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 the entitySelectionMetadataField:

{
  "nodesField": [
    {
      "levelField": 2,
      "entityField": {
        "idField": "dac4985e-501d-41f7-933b-44c0b8de0f54",
        "nameField": "WOLTERS KLUWER HOLDINGS (UK) LIMITED"
      },
      "entitySelectionMetadataField": {
        "sourceField": "USER_SELECTED",
        "continuationKeyField": "15ce9621-87f9-49b5-bac2-6497b2c38cd9",
        "dateSelectedField": "2026-01-14T07:49:43.2377905Z"
      }
    }
  ]
}

Selection source types:

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

The selectedCandidatesField provides a complete audit trail of every continuation decision:

{
  "ownershipTreeField": {
    "selectedCandidatesField": [
      {
        "parentNodeIdField": "2e777682-3efc-478f-8472-fd78efb7f60e",
        "candidateField": {
          "companyNameField": "WOLTERS KLUWER HOLDINGS (UK) LIMITED",
          "companyIdField": "01329311",
          "countryIsoField": "GB",
          "addressField": "145 LONDON ROAD, KINGSTON UPON THAMES, SURREY",
          "continuationKeyField": "15ce9621-87f9-49b5-bac2-6497b2c38cd9"
        },
        "nodeIdField": "dac4985e-501d-41f7-933b-44c0b8de0f54",
        "dateSelectedField": "2026-01-14T07:49:43.2377905Z",
        "orderIdField": "332003"
      }
    ]
  }
}

What this tells you:

• 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)

This creates a complete decision log showing exactly which companies were chosen when multiple matches existed.

Ownership tree version history

The previousVersionsField tracks the evolution of your ownership tree through multiple continuations:

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

How version chains work:

1. Initial UBO request creates order ID 331999
2. Encounter ambiguous match, select continuation → creates order ID 332003
3. Select another continuation → creates current order ID 331997
4. Current tree's previousVersionsField shows: ["332003", "331999"]

Example workflow:

# Initial request encounters ambiguity
curl -X GET "https://rest.kyckr.com/core/uboverify/create/GB/12345678?maxCreditCost=100"
# Returns order 331999 with candidate options

# Continue with selected candidate
curl -X GET "https://rest.kyckr.com/core/uboverify/create/GB/12345678?continuationKeys=15ce9621-87f9-49b5-bac2-6497b2c38cd9"
# Returns order 332003, previousVersionsField: ["331999"]

# Continue again with another candidate
curl -X GET "https://rest.kyckr.com/core/uboverify/create/GB/12345678?continuationKeys=812a3543-2e95-4bda-a357-88b023392f28"
# Returns order 331997, previousVersionsField: ["332003", "331999"]

Complete example

Here's how all the entity resolution fields work together in a real ownership tree:

{
  "ownershipTreeField": {
    "idField": "331997",
    "nameField": "D. Schwarz Beteiligungs-KG",
    "nodesField": [
      {
        "levelField": 1,
        "entityField": {
          "idField": "9f1044f1-93ce-4c8c-85fc-f051eebefe15",
          "typeField": "COMPANY",
          "nameField": "D. Schwarz Beteiligungs-KG",
          "addressField": "Rötelstr. 35, 74172 Neckarsulm, Germany",
          "countryISOField": "DE",
          "companyCodeField": "HRA 736370"
        },
        "entitySelectionMetadataField": {
          "sourceField": "ALGORITHM"
        }
      },
      {
        "levelField": 2,
        "entityField": {
          "idField": "dac4985e-501d-41f7-933b-44c0b8de0f54",
          "typeField": "COMPANY",
          "nameField": "WOLTERS KLUWER HOLDINGS (UK) LIMITED",
          "addressField": "145 London Road, Kingston Upon Thames, Surrey, KT2 6SR",
          "countryISOField": "GB",
          "companyCodeField": "01329311"
        },
        "entitySelectionMetadataField": {
          "sourceField": "USER_SELECTED",
          "continuationKeyField": "15ce9621-87f9-49b5-bac2-6497b2c38cd9",
          "dateSelectedField": "2026-01-14T07:49:43.2377905Z"
        }
      }
    ],
    "selectedCandidatesField": [
      {
        "parentNodeIdField": "9f1044f1-93ce-4c8c-85fc-f051eebefe15",
        "candidateField": {
          "companyNameField": "WOLTERS KLUWER HOLDINGS (UK) LIMITED",
          "companyIdField": "01329311",
          "continuationKeyField": "15ce9621-87f9-49b5-bac2-6497b2c38cd9"
        },
        "nodeIdField": "dac4985e-501d-41f7-933b-44c0b8de0f54",
        "orderIdField": "332003"
      }
    ],
    "previousVersionsField": ["332003", "331999"]
  }
}

In this example:

• The root company (level 1) was automatically resolved (sourceField: "ALGORITHM")
• The level 2 company was manually selected via continuation (sourceField: "USER_SELECTED")
• The selectedCandidatesField shows which candidate was chosen and when
• The previousVersionsField shows 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

curl -X GET "https://rest.kyckr.com/core/uboverify/create/GB/12345678?maxCreditCost=100"

Response (order 331999):

{
  "ownershipTreeField": {
    "idField": "331999",
    "nodesField": [
      {
        "levelField": 2,
        "entityField": {
          "nameField": "ACME HOLDINGS LTD",
          "reasonForNonContinuationField": {
            "typeField": "COMPANY_NOT_FOUND",
            "detailsField": "Multiple matches with the same name in the same jurisdiction",
            "candidatesField": [
              {
                "companyNameField": "ACME HOLDINGS LTD",
                "addressField": "123 Business Park, London",
                "continuationKeyField": "ba26a0bb-f632-4421-8092-58ed3a76d3be"
              },
              {
                "companyNameField": "ACME HOLDINGS LIMITED",
                "addressField": "456 Industrial Estate, Manchester",
                "continuationKeyField": "cd38b1cc-g743-5532-9193-69fe4b87e4cf"
              }
            ]
          }
        }
      }
    ]
  }
}

Step 2: User reviews candidate addresses

Compare the candidate addresses against your source data:

• Your records show the shareholder is at "123 Business Park, London"
• First candidate matches - use its continuation key

Step 3: Continue with selected candidate

curl -X GET "https://rest.kyckr.com/core/uboverify/create/GB/12345678?continuationKeys=ba26a0bb-f632-4421-8092-58ed3a76d3be"

Response (order 332003):

{
  "ownershipTreeField": {
    "idField": "332003",
    "nodesField": [
      {
        "levelField": 2,
        "entityField": {
          "nameField": "ACME HOLDINGS LTD",
          "addressField": "123 Business Park, London"
        },
        "entitySelectionMetadataField": {
          "sourceField": "USER_SELECTED",
          "continuationKeyField": "ba26a0bb-f632-4421-8092-58ed3a76d3be",
          "dateSelectedField": "2026-01-15T10:45:00.0000000Z"
        }
      }
    ],
    "selectedCandidatesField": [
      {
        "candidateField": {
          "companyNameField": "ACME HOLDINGS LTD",
          "continuationKeyField": "ba26a0bb-f632-4421-8092-58ed3a76d3be"
        },
        "orderIdField": "331999"
      }
    ],
    "previousVersionsField": ["331999"]
  }
}

Result: The entity now appears with 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 uboAnalysisField is recommended to guide the UBO discovery process to the required goal, limited only by registry data.
• Existing ultimateBeneficialOwnersField structure is unchanged; new fields extend the schema
• All existing request parameters and response fields remain unchanged

Entity resolution fields

• The addressField is added to entity and edge objects when address data is available from Enhanced Profiles
• The entitySelectionMetadataField appears 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 selectedCandidatesField is populated only when continuations have been used
  • Provides audit trail of which candidates were selected during disambiguation
• The previousVersionsField is populated only when the current tree is a continuation of prior versions
  • Shows the order ID chain leading to the current ownership tree state

Adoption timeline

If you're not yet using these features, your responses will look exactly as before—you can adopt these enhancements at your own pace. All fields are designed to enhance existing functionality without breaking changes.

Example response

Here's what a complete response looks like with analysis insights:

{
  "ownershipTreeField": {
    "idField": "2700226",
    "nameField": "HAND MADE HAIR LTD",
    "addressField": "Unit 1, Example Business Park, London, GB",
    "statusField": "SUCCESS",
    "uboThresholdField": 25,
    "nodesField": [
      {
        "levelField": 1,
        "entityField": {
          "idField": "0c7f23d9-30ca-41bb-8733-31d0180bbc8a",
          "typeField": "COMPANY",
          "nameField": "HAND MADE HAIR LTD",
          "countryISOField": "GB",
          "companyCodeField": "09439563"
        },
        "edgesField": [
          {
            "nodeIdField": "907bae93-f2d4-4c8c-95b2-f10fe9c89f2f",
            "typeField": "SHAREHOLDER",
            "percentageField": 46.14
          }
        ]
      },
      {
        "levelField": 2,
        "entityField": {
          "idField": "907bae93-f2d4-4c8c-95b2-f10fe9c89f2f",
          "typeField": "PERSON",
          "nameField": "JOSHUA JOHN WOOD",
          "countryISOField": "GB"
        },
        "edgesField": []
      }
    ],
    "ultimateBeneficialOwnersField": [
      {
        "idField": "907bae93-f2d4-4c8c-95b2-f10fe9c89f2f",
        "nameField": "JOSHUA JOHN WOOD",
        "percentageField": "46.14",
        "entityTypeField": "PERSON"
      }
    ]
  },
  "uboAnalysisField": {
    "statusField": "INCOMPLETE_REQUIRED_PROFILES",
    "blockingReasonField": "",
    "metricsField": {
      "uboCoverageField": 46.14,
      "shareholdingCoverageField": 100.0,
      "unpurchasedTotalField": 24.06
    },
    "requiredProfilesField": [
      {
        "entityIdField": "5ac26d8e-0ade-4c28-9a3d-f490a07adfad",
        "entityNameField": "INDEX VENTURES IX (JERSEY) L.P.",
        "companyCodeField": "REG123"
      }
    ],
    "potentialBeneficialOwnersField": [
      {
        "canonicalNameField": "JONATHAN DAVIES",
        "totalOwnershipField": 29.62,
        "isFuzzyGroupField": true,
        "membersField": [
          {
            "nameField": "Jonathan Gray Davies",
            "ownershipField": 5.56
          },
          {
            "nameField": "Jonathan Davies",
            "ownershipField": 24.06
          }
        ]
      }
    ]
  }
}

Additional resources

• Company V1 API Reference
• UBO Verify Guide