Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.didit.me/llms.txt

Use this file to discover all available pages before exploring further.

Identifying who ultimately owns and controls a company is the heart of KYB. Didit pulls the ownership structure from the registry where available, lets the business admin confirm and extend it in the hosted flow, and then runs role-aware verification on each key person.

​
Beneficial owners (UBOs)

An Ultimate Beneficial Owner (UBO) is a natural person who ultimately owns or controls a legal entity. UBOs surface in the session decision under key_people_checks[].registry.beneficial_owners[] (registry-derived) and key_people_checks[].submitted.parties[] (user-submitted), with any other role such as shareholder or director in the same list.

​
Data collected for each key person

The hosted flow collects a default set of fields plus any workflow-configured custom fields. The defaults:
FieldPersonCompany
name or first_name + last_name✅ required✅ required (company_name)
email✅ required✅ required
nationality / country✅ required✅ required
role (one or more per party)✅ required✅ required
ownership_percent / voting_percent (per role)optionaloptional
date_of_birthoptional—
phone_numberoptional—
position (free-text job title)optional—
registration_number—optional
entity_typepersoncompany
entity_type is set automatically based on whether the party is a natural person or a corporate entity.

​
Custom fields

Workflows can require additional fields per person or per company — any number of them. They’re configured in the Business Console on the KYB workflow and end up in the custom_fields object on each party in the decision response. Use custom fields for things like source-of-wealth declarations, tax residency, internal client IDs, or industry-specific disclosures.

​
Corporate shareholders and nested ownership

When a shareholder is itself a company (not a natural person), Didit records:
  • Company name and registration number.
  • Ownership percentage held by that corporate shareholder.
  • Country of incorporation.
This lets you trace the chain through multiple layers to the ultimate natural persons.

​
Nested KYB for corporate UBOs

When the workflow enables nested KYB for corporate UBOs, each corporate party triggers its own child KYB sub-session — the company verifies under the same process you run at the top level, and its result feeds back into the parent. Off by default; opt in per workflow.

​
Ownership thresholds

Most jurisdictions classify UBOs at 25% or more. The threshold is configurable per workflow:
JurisdictionTypical UBO threshold
EU (AMLD)25% ownership or control
UK25% shares or voting rights
USA (CTA)25% ownership or substantial control
Singapore25% shares or voting power
Set it from Workflows → [KYB workflow] → Risk → UBO threshold. Your workflow can also flag or route for review when no UBO meets the threshold (common with widely-held public companies).

​
Voting vs economic rights

Ownership disclosures distinguish two kinds of control:
RightWhat it means
Economic (ownership) %Share of the company’s economic value / dividend rights
Voting %Share of voting power on shareholder resolutions
These are usually equal but can diverge when a company issues dual-class shares or preferred equity. Didit records both. Rules and thresholds can check either — most jurisdictions require UBO disclosure when either crosses 25%.

​
Effective ownership through a chain

When ownership runs through a corporate shareholder, effective ownership of a downstream natural person is computed by multiplying percentages along the chain.

​
Example — 3-layer chain

Acme Corp (target)
  └─ 60% → Acme Holdings Ltd
              └─ 75% → Jane Doe (natural person)
  └─ 40% → John Smith (natural person)
Computed UBOs:
  • Jane Doe — effective ownership of Acme Corp = 60% × 75% = 45% (UBO).
  • John Smith — effective ownership of Acme Corp = 40% (UBO).
With a 25% UBO threshold, both Jane and John are disclosed. With a 50% threshold, no UBO meets the cut — Didit flags this as a transparency concern.

​
How role settings drive verification

Each role is individually configured per KYB workflow: enabled or disabled, whether it requires KYC, which KYC workflow to use for that role, and whether the end user can choose to skip it. When a key person is submitted:
  1. Didit checks the submitted party’s roles against the workflow’s role settings.
  2. For roles marked as requiring verification, a child verification session is started:
    • Person parties → child User Verification (KYC) session, using either the role-specific KYC workflow or the default.
    • Corporate UBOs (when nested KYB is enabled) → child Business Verification (KYB) sub-session.
  3. For roles marked as skippable, the end user sees a “skip verification” option and can opt out; skipped parties are recorded but don’t block the parent session.
  4. Parties below the workflow’s ownership threshold don’t trigger individual verification even if the role would otherwise require it.
Configure everything from Workflows → [KYB workflow] → Key People in the Business Console.

​
Registry vs user-submitted reconciliation

The response surfaces both sources side-by-side under key_people_checks[]:
  • registry.officers[] and registry.beneficial_owners[] — what the provider disclosed.
  • submitted.parties[] — what the business admin explicitly submitted through the flow, with source: "USER".
Analysts compare the two buckets visually in the console to spot missing UBOs, extra undisclosed parties, or ownership percentages that don’t line up. There’s no automated diff endpoint — you can reconcile on your side by matching on name, role, and ownership where applicable.

​
AML screening

Every identified key person is automatically screened against global AML watchlists, both from the registry side and the submitted side. See Business AML screening for how company-level and person-level AML checks combine.

​
Next steps

Key people

The Key People flow end-to-end.

Officers & representatives

Governance roles inside the key-people model.

Risk assessment

How ownership complexity rolls into risk level.