> ## 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.
# Key People (UBOs, Officers, Directors)
> Officers, directors, UBOs, and beneficial owners on a Didit Business entity — each one verifiable through KYC as a User entity. Pay-per-call $2.00.
Every Business entity has **key people** — the natural persons legally responsible for or beneficially owning the company. Didit identifies them during KYB and lets you link each one to a User entity for individual KYC.
## Who counts as a key person
| Role | Description |
| ----------------------------------- | ------------------------------------------------------------------------------ |
| **Director** | Named in registry as a company director |
| **Officer** | Secretary, representative, or other registered officer |
| **Shareholder** | Registered shareholder (corporate or individual) |
| **UBO (Ultimate Beneficial Owner)** | Individual who ultimately owns or controls 10/25/50%+ (threshold configurable) |
| **Authorized signatory** | Person empowered to act on behalf of the company |
See the [KYB Officers](/business-verification/officers) and [Ownership](/business-verification/ownership) pages for the full role taxonomy and ownership-chain computation.
## How key people attach to a Business
During KYB, Didit queries the company registry and extracts all listed officers and shareholders. Each person becomes a **key-people record** linked to the Business Verification (KYB) session.
Workflows can include a "Key People" step where the business admin adds people not present in the registry (e.g. UBOs identified by corporate declaration).
The Business's key-people list is the union of registry-extracted and user-added parties, de-duplicated by identity.
Each key person has a `source` field:
* `REGISTRY` — extracted from an official registry.
* `USER` — added by the business admin during the KYB flow.
## Linking a key person to a User entity
When KYC is required for a key person (typically UBOs and directors), the party can be linked to a User entity:
```mermaid theme={null}
flowchart LR
B[Business: biz-acme]
P1[Key Person: Jane Doe, Director]
P2[Key Person: John Smith, UBO 40%]
U1[User: user-jane]
U2[User: user-john]
P1 --> B
P2 --> B
P1 -.linked.-> U1
P2 -.linked.-> U2
```
The link is created when:
* A User Verification (KYC) session runs for the party using the same `vendor_data` as the User entity.
* An analyst manually associates a business party with an existing User.
Once linked, the User's KYC status propagates to the key people view on the Business.
## Inspecting key people
From the Business detail page in the console, the **Key People** tab shows:
* Every party's name, role, ownership %, source (registry vs user-added)
* KYC status of linked Users
* AML screening status per person
* Associated documents (director ID, UBO declaration)
Programmatically, key people surface inside the `key_people_checks[]` array of the Business Verification (KYB) session decision, split into two buckets:
```json theme={null}
"key_people_checks": [
{
"status": "Approved",
"node_id": "feature_kyb_key_people",
"registry": {
"officers": [
{ "uuid": "...", "name": "Jane Doe", "role": "director", "kyc_status": "Approved", "kyc_session_url": "..." }
],
"beneficial_owners": [
{ "uuid": "...", "name": "John Smith", "roles": ["ubo"], "ownership_min_shares": 40, "kyc_status": "Pending" }
]
},
"submitted": {
"parties": [
{ "uuid": "...", "entity_type": "person", "name": "Alice Chen", "role": "ubo", "ownership_percent": 35.0, "source": "USER", "requires_verification": true, "kyc_session_status": "Not Started", "kyc_session_url": "..." }
]
},
"ubo_kyc_summary": { "total": 2, "approved": 1, "flagged": 0, "pending": 1 }
}
]
```
* **`registry.officers` / `registry.beneficial_owners`** — parties discovered via the registry check.
* **`submitted.parties`** — parties the business admin added during the Key People flow (`source: USER`).
* **`ubo_kyc_summary`** — aggregate UBO KYC progress.
Legacy flat `officers[]` and `beneficial_owners[]` arrays remain on the response for backward compatibility one more release. New integrations should consume the two-bucket shape above. See the full [KYB response schema](/business-verification/response-schema#key_people_checks) for every field.
## Corporate shareholders
When a shareholder is itself a company (not a person), Didit recursively explores the ownership chain to identify the ultimate beneficial owners. Corporate parties can optionally trigger child Business Verification (KYB) sessions.
See [Ownership structure](/business-verification/ownership) for a worked example of multi-layer ownership chains.
## Key people webhooks
Changes to key people surface through the parent session events:
* `data.updated` (with `session_kind: "business"`) — session data including key people was updated.
* `status.updated` (with `session_kind: "business"`) — the session status changed as a result.
See [KYB webhooks](/business-verification/webhooks) for payloads.
## Next steps
Director identification and role taxonomy.
UBO, corporate shareholders, and chain computation.
The KYB step that collects key people.