> ## 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. # KYB Response Schema > Annotated KYB decision payload: registry checks, key people, UBO KYC summaries, documents, AML screenings, and shared fields. Pay-per-call $2.00 KYB. This page documents the full payload returned by [`GET /v3/session/{id}/decision/`](/sessions-api/retrieve-session) for a Business Verification (KYB) session. The endpoint is unified — when you pass a business `session_id`, the response carries `session_kind: "business"` and the business-specific feature arrays below. ## Top-level structure ```json theme={null} { "session_id": "bs_01H...", "session_kind": "business", "session_number": 89, "session_url": "https://verify.didit.me/...", "status": "APPROVED", "workflow_id": "wf_kyb_standard", "features": ["KYB_REGISTRY", "KYB_COMPANY_AML", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE"], "vendor_data": "biz-acme-001", "metadata": { }, "callback": null, "registry_checks": [ ... ], "aml_screenings": [ ... ], "document_verifications": [ ... ], "key_people_checks": [ ... ], "phone_verifications": null, "email_verifications": null, "questionnaire_responses": null, "ip_analyses": null, "reviews": [ ], "contact_details": { ... }, "expected_details": null, "created_at": "...", "expires_at": "..." } ``` All feature arrays are multi-instance — each item represents one node in a graph workflow. Null means the feature was not present in this session's workflow. ## Shared top-level fields | Field | Type | Description | | -------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `session_id` | UUID | Unique session identifier | | `session_kind` | enum | Always `"business"` for KYB sessions | | `session_number` | int | Sequential number within the application | | `session_url` | URL | Hosted verification link | | `status` | enum | Overall session status (see [statuses](/business-verification/statuses)) | | `workflow_id` | UUID | Workflow that drove this session | | `features` | array of strings | Feature identifiers the workflow ran (e.g. `KYB_REGISTRY`, `AML`, `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE`, `PHONE`, `EMAIL`) | | `vendor_data` | string | Your identifier for the business | | `metadata` | object | Free-form JSON you attached at session creation | | `callback` | URL or null | Optional post-verification redirect URL | | `contact_details` | object or null | `{ email, email_lang, send_notification_emails, phone }` — set when the flow includes email/phone notifications | | `expected_details` | object or null | Business expected-data payload you passed on creation: `company_name`, `registry_country` (`XX` or `XX-YY` with the state for state-level registries, e.g. `US-CA`), `registration_number` | | `reviews` | array | Latest reviewer notes on the session | | `created_at`, `expires_at` | ISO timestamps | — | ## `registry_checks[]` Each item is one company registry check (typically one per session; multiple in graph workflows with recursive corporate UBO KYB). ```json theme={null} { "status": "Approved", "node_id": "feature_kyb_registry", "data_resolved": true, "company": { ...see below... }, "ownership_structure": { }, "warnings": [] } ``` | Field | Description | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `status` | Feature lifecycle status (`Approved`, `Declined`, `In Review`, `Not Finished`, `Resub Requested`) | | `node_id` | Graph node identifier for this check | | `data_resolved` | `true` when registry data has finished loading or the user provided the data manually | | `company` | Full registry payload — see **`company` block** below | | `ownership_structure` | Raw ownership-chain JSON as returned by the registry provider | | `warnings` | Structured warnings / log entries scoped to this registry check. See [Business Verification warnings](/business-verification/warnings). | ### `company` block The nested company object is the full view of the legal entity as derived from the registry (and optionally user-edited): ```json theme={null} { "uuid": "...", "node_id": "feature_kyb_registry", "status": "Approved", "registry_status": "active", "data_resolved": true, "company_name": "Acme Corporation Limited", "registration_number": "12345678", "country_code": "GBR", "company_type": "Private Limited", "incorporation_date": "2010-05-14", "registered_address": "1 Main Street, London EC1A 1AA, United Kingdom", "tax_number": "SAMPLE-TAX-12345", "risk_level": "LOW", "verification_status": "verified", "is_from_registry": true, "fetch_status": "resolved", "alternative_names": ["Acme Ltd"], "nature_of_business": "Software publishing", "registered_capital": "100000 GBP", "website": "https://acme.example", "email": "alex.sample@example.com", "phone": "+15550101000", "legal_entity_identifier": "529900XXXXXXXXXXXXX", "location_of_registration": "London", "vat_number": "GB123456789", "vat_validation_status": "not_applicable", "vat_validated_name": null, "vat_validated_address": null, "vat_checked_at": null, "financial_summary": { }, "officers": [ ... ], "beneficial_owners": [ ... ], "addresses": [ ... ], "industries": [ ... ], "accounts": [ ... ], "registry_data": { }, "user_provided_data": { }, "confirmed_by_user_at": "2026-04-16T10:10:00Z", "last_console_edit_at": null, "is_editable": false } ``` | Field | Description | | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `registry_status` | Provider-reported status (`active`, `dissolved`, `struck_off`, `inactive`, etc.). See [statuses](/business-verification/statuses#registry-status-from-the-provider) | | `is_from_registry` | `true` when data came from an official registry; `false` for manual entry | | `fetch_status` | `pending`, `resolved`, or `failed` — registry lookup state | | `verification_status` | `verified`, `failed`, or `unknown` | | `is_editable` | `true` while registry-sourced data can still be edited by the end user | | `registry_data` / `user_provided_data` | Raw JSON for registry-returned vs user-entered fields (useful for audit diffing) | | `confirmed_by_user_at` | Timestamp when the end user confirmed / edited the registry data | | `vat_number` | VAT number as submitted, when collected | | `vat_validation_status` | Result of the EU VIES check: `valid`, `invalid`, `could_not_validate`, or `not_applicable` (non-EU companies, or no VAT number provided). See [VAT validation](/business-verification/company-data#vat-validation-vies) | | `vat_validated_name` / `vat_validated_address` | Trader name and address registered with VIES, when the member state discloses them | | `vat_checked_at` | Timestamp of the VIES check; `null` when no check ran | | `officers[]` | Officers with embedded KYC enrichment (see below) | | `beneficial_owners[]` | UBOs with embedded KYC enrichment (see below) | | `addresses`, `industries`, `accounts` | Extracted from `registry_data` when available | ### Officer item shape (inside `company.officers`) ```json theme={null} { "uuid": "...", "name": "Jane Doe", "designation": "Director", "role": "director", "nationality": "USA", "is_active": true, "kyc_status": "Approved", "kyc_session_url": "https://verify.didit.me/..." } ``` ### Beneficial owner item shape (inside `company.beneficial_owners`) ```json theme={null} { "uuid": "...", "name": "John Smith", "first_name": "John", "last_name": "Doe", "entity_type": "person", "roles": ["ubo"], "ownership_min_shares": 40, "ownership_max_shares": 40, "is_active": true, "kyc_status": "Pending", "kyc_session_url": "https://verify.didit.me/...", "effective_ownership_percent": 40.0 } ``` `kyc_status` uses a B2C-safe projection: `Approved`, `Declined`, or `Pending` (full session states collapse to `Pending` until the KYC finishes). ## `key_people_checks[]` This is the **aggregate check** over all officers and UBOs for the session. It exposes two buckets so the console can render "extracted from the registry" side-by-side with "submitted by the business", plus a high-level UBO KYC summary. ```json theme={null} { "status": "Approved", "node_id": "feature_kyb_key_people", "registry": { "officers": [ ...registry-derived officers... ], "beneficial_owners": [ ...registry-derived UBOs... ] }, "submitted": { "parties": [ ...user-submitted key-people records... ] }, "ubo_kyc_summary": { "total": 2, "approved": 1, "flagged": 0, "pending": 1 }, "warnings": [] } ``` * **`registry.officers` / `registry.beneficial_owners`** — parties extracted from the registry check. * **`submitted.parties`** — parties the business admin explicitly added during the Key People flow (records with `source = "USER"`). ### `registry.officers[]` / `registry.beneficial_owners[]` Same item shapes as `company.officers` / `company.beneficial_owners` above (B2C-safe KYC enrichment). ### `submitted.parties[]` User-submitted parties carry their KYC or child-KYB linkage: ```json theme={null} { "uuid": "...", "entity_type": "person", "name": "Alice Chen", "first_name": "John", "last_name": "Doe", "email": "alex.sample@example.com", "role": "ubo", "ownership_percent": 35.0, "nationality": "USA", "position": "CEO", "date_of_birth": "1990-01-01", "phone_number": "+34612345678", "source": "USER", "requires_verification": true, "is_skipped": false, "kyc_session_id": "sess-xyz...", "kyc_session_status": "Not Started", "kyc_session_url": "https://verify.didit.me/...", "custom_fields": { } } ``` Corporate parties (`entity_type: "company"`) additionally carry `company_name`, `registration_number`, and `kyb_sub_session_id` / `kyb_sub_session_status` when nested KYB is enabled for corporate UBOs. ### `ubo_kyc_summary` Aggregate UBO KYC progress — useful for a single dashboard card: | Field | Meaning | | ---------- | ---------------------------------------------------- | | `total` | Number of active UBOs that have a linked KYC session | | `approved` | UBOs whose KYC session is `APPROVED` | | `flagged` | UBOs whose KYC session is `DECLINED` or `IN_REVIEW` | | `pending` | Everyone else (not yet finished) | Returns `null` when no UBOs have linked KYC sessions. ## `document_verifications[]` Documents grouped by node: ```json theme={null} { "status": "Approved", "node_id": "feature_kyb_documents", "items": [ { "uuid": "...", "document_type": "certificate_of_incorporation", "status": "Approved", "file_url": "https://didit-storage.s3...", "document_metadata": { "file_size": 246810, "content_type": "application/pdf", "creation_date": "2024-05-15", "modified_date": "2024-05-15", "overlay_manipulation": null }, "ocr_data": { "company_name": "Acme Corporation Limited", "registration_number": "12345678", "incorporation_date": "2010-05-14" } } ], "groups": { "legal_presence": { "approved": 1, "pending": 0, "missing": 0 }, "ownership_structure": { "approved": 1, "pending": 0, "missing": 0 } }, "required_groups": ["legal_presence", "ownership_structure"], "warnings": [] } ``` | Field | Description | | ----------------- | ---------------------------------------------------------------------------------------------------------------------- | | `items[]` | Individual document rows — each has its own `status`, `file_url` (signed), `document_metadata`, and OCR extract | | `groups` | Per-group progress counters — matches the [four KYB document groups](/business-verification/documents#document-groups) | | `required_groups` | Groups your workflow marked as required; gate session approval on all being satisfied | ### Corporate document metadata For PDF corporate documents, `items[].document_metadata.overlay_manipulation` can include forensic evidence for suspected overlay-text editing. When present, it includes: | Field | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `detected` | Whether overlay-text manipulation evidence was detected | | `analyzed` | Whether the PDF could be analyzed | | `signals` | Forensic signals that fired, such as `duplicate_font_subset` or `glyph_fragmentation` | | `manipulated_regions` | PDF page-coordinate rectangles around suspected edited text: `page`, `x`, `y`, `width`, `height`, `page_width`, `page_height` | The field is `null` when no overlay evidence was found, when the document is not a PDF, or when the PDF could not be analyzed. ## `aml_screenings[]` Company-level and (when the workflow wires them) person-level AML screenings. ```json theme={null} { "node_id": "feature_kyb_company_aml", "status": "Approved", "total_hits": 0, "score": 0, "entity_type": "COMPANY", "screened_data": { "company_name": "Acme Corporation Limited", "country_code": "GBR" }, "is_ongoing_monitoring_enabled": true, "next_ongoing_monitoring_bill_date": "2027-04-16", "hits": [], "warnings": [] } ``` When `total_hits > 0`, each hit includes match score, risk score, watchlist sources, and a per-hit `review_status` you can update via the update-aml-hit-status endpoint. See [AML Screening report](/core-technology/aml-screening/report-aml-screening) for the hit structure. ## Shared feature arrays `phone_verifications`, `email_verifications`, `questionnaire_responses`, `ip_analyses` use the same per-item shapes as user (KYC) sessions. They're `null` when the workflow doesn't include them. See the [KYC response](/sessions-api/retrieve-session) for item schemas. ## Warning feature groups Business Verification warnings are grouped by the feature that produced them: * `KYB_REGISTRY` for registry availability, ownership, company activity, and country-restriction issues. * `KYB_DOCUMENTS` for corporate document extraction, cross-check, metadata, manipulation, subtype, age, and attempt-limit issues. * `AML` for company AML screening matches or missing screening data. * `KYB_KEY_PEOPLE` for person-level issues tied to directors, officers, UBOs, or representatives. * `PHONE` for phone-number risk, duplication, blocklist, and verification-code attempt issues. * `EMAIL` for email risk, deliverability, duplication, blocklist, and verification-code attempt issues. * `QUESTIONNAIRE` for custom status rules driven by questionnaire answers. * `LOCATION` for Device & IP Analysis, private-network, IP blocklist, device blocklist, and duplicate device/IP issues. See [Business Verification warnings](/business-verification/warnings) for the full list of warning codes. ## Workflow-driven field filtering Workflows can limit which nested fields appear on each feature item via `response_attributes`. Fields always included regardless: `status`, `warnings`, `node_id`. All other fields are nullified when not in the allow-list — the key stays in the response for schema stability. ## Next steps What each status value means. How `risk_level` is computed. Full AML hit payload reference. How parties flow from registry vs user submission into `registry` / `submitted` buckets. Document groups, OCR, and cross-reference. Full endpoint reference including example responses.