KYB Response Schema

This page documents the full payload returned by GET /v3/session/{id}/decision/ 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

{
  "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)
`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).

{
  "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 snapshot kept for reviewers. Its shape differs by registry source and is not a stable contract: read `company.beneficial_owners` and `company.ownership` instead
`warnings`	Structured warnings / log entries scoped to this registry check. See 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):

{
  "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": "GB980780684",
  "vat_validation_status": "format_valid",
  "vat_validated_number": "GB980780684",
  "vat_validation_source": "format_rules",
  "vat_validated_name": null,
  "vat_validated_address": null,
  "vat_checked_at": "2026-04-16T10:10:00Z",
  "financial_summary": { },
  "officers": [ ... ],
  "beneficial_owners": [ ... ],
  "addresses": [
    {
      "type": "registered",
      "address": "1 Main Street, London EC1A 1AA, United Kingdom",
      "street": "1 Main Street",
      "city": "London",
      "postal_code": "EC1A 1AA",
      "region": null,
      "country_code": "GB",
      "description": null
    }
  ],
  "industries": [
    { "code": "58290", "description": "Other software publishing", "scheme": "UK SIC 2007", "is_primary": true }
  ],
  "accounts": { ... },
  "ownership": {
    "status": "delivered",
    "tier_requested": "ubo",
    "tier_delivered": "ubo",
    "unavailable_reason": null,
    "direct_ownership_complete": true,
    "unresolved": []
  },
  "registry_tier": "ubo",
  "registry_tier_delivered": "ubo",
  "registry_ownership_status": "delivered",
  "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
`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`	Raw record returned by the registry source, kept for reviewers. Its shape differs by country and source and is not a stable contract: read the canonical fields instead
`user_provided_data`	The fields the end user entered or edited (useful for audit diffing against the registry values)
`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 validating the VAT number, or the `tax_number` when there is none: `valid`, `invalid`, `format_valid`, `invalid_format`, `could_not_validate`, or `not_applicable`. See VAT and tax ID validation
`vat_validated_number` / `vat_validation_source`	The number that was checked, as the source knows it, and the source that decided the status (an official registry, or `format_rules`)
`vat_validated_name` / `vat_validated_address`	Name and address registered with the source, when it discloses them
`vat_checked_at`	Timestamp of the check; `null` when no check ran
`officers[]`	Officers with embedded KYC enrichment (see below)
`beneficial_owners[]`	UBOs with embedded KYC enrichment (see below)
`addresses[]`	Every address the registry states, in the canonical address shape below. `null` when it states none
`industries[]`	The activities the registry classifies the company under, in the canonical industry shape below. `null` when it states none
`accounts`	Corporate filing dates when reported: `last_annual_return_date` and `last_agm_date`. These describe filings and meetings, not financial statements
`ownership`	The outcome of the ownership (Shareholders / UBO) tier, in the canonical shape below
`registry_tier` / `registry_tier_delivered` / `registry_ownership_status`	The tier ordered, the tier delivered (and billed), and the ownership outcome. The same values are in `ownership`

One format for every country and registry source

Didit reads company registries in many countries through several registry sources. Each source publishes its own layout, but the company block always has the same shape: the keys below are always present, with the same types, whichever country and source the company came from. A fact the registry does not publish is null; you never need to branch on the country or parse registry_data. The same shape is returned by the decision, the standalone KYB registry endpoints and the hosted verification flow. Address (each item of addresses)

Field	Description
`type`	Lower case. `registered` for the registered office; other types as the registry names them (for example `postal`, `office`). `null` when the registry does not say what the address is
`address`	The full address as one line. Always present
`street`, `city`, `postal_code`, `region`	The address in parts, when the registry publishes them
`country_code`	ISO 3166-1 alpha-2
`description`	The registry’s own label for the address, when it gives one

Industry (each item of industries)

Field	Description
`code`	Activity code as the registry prints it
`description`	Activity label, when the registry publishes one
`scheme`	Classification system, one name per system whichever source reported it (`UK SIC 2007`, `US SIC`, `NACE Rev. 2`, `NACE Rev. 2.1`, `NAF Rev. 2`, `CNAE`, `SBI`, `NOGA 2008`, `CAE Rev. 4`, `Canada SIC 1977`). Other national systems keep the registry’s own name; `null` when the registry does not name it
`is_primary`	`true` for the main activity. Exactly one entry is primary

When the registry states activities but no business description, nature_of_business is filled from the activity labels. Contact details and alternative names are populated when available, while explicit user or reviewer edits always take precedence. Ownership (ownership)

Field	Description
`status`	`delivered`, `unavailable`, `pending` (the registry is still fetching the ownership section) or `not_requested` (Basic tier)
`tier_requested` / `tier_delivered`	`basic`, `shareholders` or `ubo`. A UBO request answered with direct shareholders only is delivered, and billed, as `shareholders`
`unavailable_reason`	Why a requested ownership tier was not delivered: `no_owners_on_record`, `no_natural_person_owner`, `ownership_section_unavailable`, `company_not_found`, `ambiguous_company_match`, `missing_registration_number`, `entity_type_not_covered`, `provider_unavailable` or `other`. `null` when ownership was delivered
`direct_ownership_complete`	`true` when the direct shareholders’ stated stakes add up to 100% (within one percentage point of rounding), `false` when they do not, `null` when ownership was not delivered or a stake is not stated
`unresolved[]`	Parts of the ownership chain the registry could not resolve, as `{ reason, section }` (for example `no_group_structure_on_record` for `group_structure`: the direct owners are known, the corporate group above them is not on record)

Officer item shape (inside `company.officers`)

{
  "uuid": "...",
  "name": "Jane Doe",
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": null,
  "date_of_birth_year": 1983,
  "date_of_birth_month": 2,
  "address": "1 Example Street, London",
  "appointment_date": "2024-07-01",
  "termination_date": null,
  "designation": "Director",
  "role": "director",
  "nationality": "USA",
  "is_active": true,
  "kyc_status": "Approved",
  "kyc_session_url": "https://verify.didit.me/..."
}

date_of_birth is populated only when the registry supplies a complete date. If the registry reports only a year or month and year, use date_of_birth_year and date_of_birth_month; the missing day is never inferred. Names, birth details, address, and appointment dates remain available in both the company officer list and the Key People registry list.

Beneficial owner item shape (inside `company.beneficial_owners`)

{
  "uuid": "...",
  "name": "John Doe",
  "first_name": "John",
  "last_name": "Doe",
  "entity_type": "person",
  "date_of_birth": null,
  "country_of_birth": null,
  "email": null,
  "company_name": null,
  "registration_number": null,
  "nationality": null,
  "designation": null,
  "appointment_date": null,
  "voting_min_shares": null,
  "voting_max_shares": null,
  "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,
  "shareholding": {
    "share_class": "Ordinary",
    "number_of_shares": 40,
    "currency": "GBP",
    "nominal_value": 1,
    "total_value": null,
    "percentage": 40
  }
}

kyc_status uses a B2C-safe projection: Approved, Declined, or Pending (full session states collapse to Pending until the KYC finishes). shareholding states what the owner holds, in the same shape for every country and registry source: share_class, number_of_shares, currency, nominal_value, total_value and percentage (the exact stake, to four decimal places). It is null when the registry states no holding. A band, such as a UK PSC’s 25-50%, is not a stake: percentage is null and the band stays in ownership_min_shares / ownership_max_shares. Shareholders and UBOs are both listed in beneficial_owners; roles tells them apart.

`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.

{
  "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[]`

The registry facts match company.officers / company.beneficial_owners above. Key People additionally includes AML status and detailed verification linkage, such as kyc_session_id and verification workflow fields. The company lists retain their existing simplified KYC status and verification URL.

`submitted.parties[]`

User-submitted parties carry their KYC or child-KYB linkage:

{
  "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/...",
  "kyc_session_deleted": false,
  "custom_fields": { }
}

Corporate parties (entity_type: "company") additionally carry company_name, registration_number, and kyb_sub_session_id / kyb_sub_session_status / kyb_sub_session_deleted when nested KYB is enabled for corporate UBOs. kyc_session_deleted (and its corporate counterpart kyb_sub_session_deleted) is true when the party’s child session was deleted. A deleted child keeps whatever status it had at deletion time and can never settle, so read this flag rather than the status: the matching *_session_url is returned as null because the link no longer resolves, and the Key People check drops to In Review instead of waiting forever. Deleting a child session never counts as a pass. Exempt the party with PATCH /v3/session/{id}/kyb/parties/{party_uuid}/ to let the KYB settle.

`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:

{
  "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
`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.

{
  "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",
  "last_ongoing_screening_at": "2026-09-12T04:03:11Z",
  "last_ongoing_screening_datasets_updated_at": null,
  "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 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 for item schemas. signatures is present when the workflow has an Electronic Signature step. A business session has one item per key person who signs for the company, with signer.capacity: "company", the company name and the key person’s roles. See the Electronic Signature report.

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.
SIGNATURE for Electronic Signature declines, failed code confirmations, signer name mismatches, unverified signers, changed documents and missing field data. See Electronic Signature warnings.

See 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

Statuses

What each status value means.

Risk assessment

How risk_level is computed.

AML report

Full AML hit payload reference.

Key people

How parties flow from registry vs user submission into registry / submitted buckets.

Documents

Document groups, OCR, and cross-reference.

Retrieve session

Full endpoint reference including example responses.

Getting Started

Features

Business Profiles

Reference

Console

Top-level structure

Shared top-level fields

`registry_checks[]`

`company` block

One format for every country and registry source

Officer item shape (inside `company.officers`)

Beneficial owner item shape (inside `company.beneficial_owners`)

`key_people_checks[]`

`registry.officers[]` / `registry.beneficial_owners[]`

`submitted.parties[]`

`ubo_kyc_summary`

`document_verifications[]`

Corporate document metadata

`aml_screenings[]`

Shared feature arrays

Warning feature groups

Workflow-driven field filtering

Next steps

Statuses

Risk assessment

AML report

Key people

Documents

Retrieve session

​Top-level structure

​Shared top-level fields

​registry_checks[]

​company block

​One format for every country and registry source

​Officer item shape (inside company.officers)

​Beneficial owner item shape (inside company.beneficial_owners)

​key_people_checks[]

​registry.officers[] / registry.beneficial_owners[]

​submitted.parties[]

​ubo_kyc_summary

​document_verifications[]

​Corporate document metadata

​aml_screenings[]

​Shared feature arrays

​Warning feature groups

​Workflow-driven field filtering

​Next steps

Statuses

Risk assessment

AML report

Key people

Documents

Retrieve session

Top-level structure

Shared top-level fields

`registry_checks[]`

`company` block

One format for every country and registry source

Officer item shape (inside `company.officers`)

Beneficial owner item shape (inside `company.beneficial_owners`)

`key_people_checks[]`

`registry.officers[]` / `registry.beneficial_owners[]`

`submitted.parties[]`

`ubo_kyc_summary`

`document_verifications[]`

Corporate document metadata

`aml_screenings[]`

Shared feature arrays

Warning feature groups

Workflow-driven field filtering

Next steps