Kyb api evidence states: handle missing ownership without false fails

A kyb api should treat missing ownership as a reviewable evidence state, not as an automatic failed business. That is the implementation decision for product, compliance and risk teams after recent ownership-reporting and registry changes. A legal entity can be correctly identified while its beneficial owners remain unavailable, unverified, stale or contradicted by another source. Collapsing those conditions into one status makes the result faster to display but harder to defend.

The same distinction matters for know your business kyb onboarding in the US. Domestic companies are no longer expected to supply federal beneficial ownership reports under the reset federal regime, while state registries still vary in the company fields they expose. A workflow that expects every US company search to return the same ownership payload will misread normal source limitations as risk events. A workflow that records the limitation can ask a narrower question: do we need a certified document, a customer attestation, a structure chart, a reviewer, or a lower-risk identity-only check?

The current competing pages for “kyb api” mainly answer how to call endpoints, search by name or registration number, create a case, retrieve ownership trees, screen individuals or collect documents. Those are useful integration details. The enterprise question they leave unanswered is what the API contract should return when the legal entity matches but the ownership evidence is missing, source-restricted or inconsistent. This article answers that operational question with a state model, a worked example and a decision table.

The US change is not that legal entity checks became unnecessary. It is that one hoped-for central ownership signal is no longer a dependable expectation for domestic companies. The federal position now exempts US-created entities and their beneficial owners from the federal ownership-reporting requirement, while foreign entities registered to do business in the US remain subject to narrower rules and deadlines. That pushes API design back towards evidence selection: state registry identity, customer-provided ownership information, documents, sanctions or watchlist screening, and reviewer certification need to stay separate.

The customer due diligence framework also points towards separation rather than a single KYB result. For covered financial institutions, beneficial-owner identification and verification can be triggered at account opening, when facts call prior information into question, or when risk-based ongoing procedures require it. Where previous information is reused, confirmation or certification should be recorded. Even outside regulated banking, that is a useful design pattern: the system should remember whether ownership was newly verified, reconfirmed, left unsupported, or reopened because new facts made it unreliable.

The UK illustrates a different but related problem. Role-holder identity verification is becoming a registry-linked fact, with directors, people with significant control and authorised agents in scope, personal codes linked to roles, consequences for non-compliance, and a recently updated in-person identity route with a 21-day completion window after booking. That does not make UK identity verification equivalent to UBO verification. It gives a KYB workflow another evidence layer: a person may be verified for a registry role while the ownership chain, authority to bind the company and financial risk still require their own evidence.

Design the response around the question a reviewer must answer, not around the marketing label on the check. At minimum, split the result into entity identity, registry status, ownership, role-holder identity, documents, screening and monitoring. Each module should have its own status and limitation. The status says what happened. The limitation says why the status is not a complete compliance conclusion.

For company identity, strong states are usually straightforward: matched, corrected, ambiguous, not found or source unavailable. For ownership, the states need more care. “Unavailable” means the source used does not expose the field, the jurisdiction requires a different access route, or the provider cannot retrieve it at that tier. “Unsupported” means the applicant’s ownership claim has not been evidenced. “Contradicted” means an observed source conflicts with the applicant or another source. “Stale” means a previously supported value has aged past the review rule or changed since approval.

This is where API ergonomics matter. Some developer documentation exposes country or state parameters, asynchronous retrieval, pagination, case creation, ownership endpoints, audit trails, documents and webhooks. Those capabilities are valuable, but they should not hide source quality. A helpful response does not merely say that the KYB check is pending or complete; it tells the consuming system whether the entity match is safe to use, which fields are missing, which fields came from a document, which came from a registry, and which need human review.

For CompanyProof, the closest product fit is claim-level evidence: verify a selected company fact, keep the observed value and source context, and treat unsupported or stale facts as distinct outcomes rather than silent failures. That framing is also useful when another KYB platform performs the broader onboarding workflow, because the downstream system still needs to know what it may safely rely on.

• Return module-level states: entity_identity, registry_status, ownership, role_holder_identity, documents, screening and monitoring.
• Use separate verdicts: verified, corrected, unsupported, unavailable, contradicted, stale and manual_review.
• Store the selected legal entity, jurisdiction, registration number, source record, retrieval time and source update or filing date where available.
• Do not overwrite a verified company identity because ownership evidence is missing; route the ownership gap to the right next action.

This example is hypothetical. The applicant is “North Harbour Robotics LLC”, a fictional Delaware limited liability company applying to a US B2B payments platform on 5 October 2026. The applicant provides a legal name, Delaware registration number, tax identifier, website, one managing member and a structure chart showing two individual owners. The product team wants to approve low-value payouts only after it has checked entity existence, sanctions screening and beneficial-owner evidence.

The first API step should resolve the legal entity against the relevant state source, not against the country code alone. A US company search that omits the state can select the wrong record or fail to retrieve the intended registry. If the name and registration number match the Delaware record, the entity_identity module can return verified. If the state record does not expose beneficial owners, the ownership module should return unavailable_source_field, not failed_company. That tells the workflow to collect a signed structure chart, operating agreement extract or other policy-approved document.

The second step compares the applicant’s ownership statement with the collected document. If the document supports both named owners and the ownership threshold in policy, the ownership_claim module may become supported_document, while the ownership_source module still says registry_unavailable. If the document names one person and the applicant names another, the state becomes contradicted and the case should pause. If the document is not supplied, the state remains unsupported_applicant_claim. Those are different risks and deserve different user messages.

The third step monitors the facts that can change. The entity status, registered name and registration number can be rechecked through a registry route. The beneficial-owner claim may need periodic recertification, document refresh or event-based review because the registry did not supply the field. A previous clean answer should therefore carry its evidence class: registry-observed, document-supported, applicant-certified, reviewer-approved or not established. That prevents a future reader from treating a signed structure chart as if it were an independently verified public ownership record.

Use ubo verification as a claim workflow rather than a single field lookup. The API should first identify the legal entity, then ask whether the ownership claim has been established to the standard needed for this decision. The standard may differ for a low-risk supplier, a regulated account, a credit exposure and a high-risk cross-border payment. The engineering contract should make that policy difference visible rather than burying it inside a provider status.

A reliable checklist starts before the request. Define the countries, US states, entity types and risk tiers your workflow actually accepts. Then test representative cases: active and inactive entities, similar names, entities with no public owners, applicant-provided owners, corporate owners, foreign registrants, protected personal data and stale filings. The aim is not to make every answer automatic; it is to know which answer is automatic and which answer is a controlled exception.

When the API returns, preserve both retrieval and verification. Retrieval says what the source or provider returned at a time. Verification says whether that value supports the specific claim in the application. A missing ownership array may be successful retrieval from a limited source. A contradictory owner name is a verification problem. A timeout or unavailable source is an operational problem. A stale document is a freshness problem. Treating all four as “failed KYB” makes triage slower and user experience worse.

• Require jurisdiction and, for US searches, state-level routing where the source model needs it.
• Prefer registration number plus legal name over name-only matching when the applicant can provide it.
• Expose why ownership is absent: not published, restricted, not covered, timed out, not supplied, or contradicted.
• Keep applicant-certified ownership separate from registry-observed ownership and document-supported ownership.
• Record the reviewer, policy version and next review trigger when a manual decision completes the case.

The practical action is to make each exception actionable. A KYB system should tell the next service whether to continue, collect more evidence, pause approval or reopen a completed review. The table below is deliberately conservative: it describes evidence handling, not legal advice or a complete compliance decision.

Use the pattern before negotiating provider-specific labels. One provider may call a result unknown, another pending, another not found and another manual review. Your internal state model should translate those labels into business actions that remain stable when providers, jurisdictions or regulations change.

• Matched entity, missing public ownership: proceed only for decisions that do not require ownership; collect documents or certification for ownership-dependent decisions.
• Matched entity, applicant ownership unsupported: do not reject automatically; request the required ownership evidence and set a response deadline.
• Matched entity, contradictory ownership evidence: pause the case, preserve both values and assign a reviewer before approval.
• Ambiguous entity match: do not run ownership or screening as if the entity were selected; ask for registration number, state or additional identifiers.
• Stale ownership evidence: reopen the ownership module, not the entire customer record, unless policy says the stale fact affects the whole relationship.

A useful API contract has two layers. The external layer accepts the provider response and records the source context. The internal layer translates that response into stable business states. For each module, store the state, observed value, evidence class, source type, retrieved_at timestamp, source_date or filing_date if available, freshness rule, limitation and next action. That gives compliance a review trail and gives product a predictable user journey.

This contract also protects against over-claiming. A business can be registered, active and correctly matched without being safe to pay. A director can be identity-verified for a registry role without proving beneficial ownership. A signed ownership chart can support a policy decision without becoming a public registry fact. A watchlist screen can be clear at a point in time without proving future risk. Good KYB architecture keeps those answers connected but not merged.

The final implementation step is monitoring. Recheck registry identity where the source supports it; recertify ownership where the evidence is applicant-provided; re-run screening under the policy schedule; and reopen a case when a material change appears. The outcome should be specific. If the registration number changed, fix the entity match. If a role-holder verification deadline was missed, route the role issue. If ownership became unsupported, reopen the ownership module. Precision is the point of the evidence-state model.