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	Expected-data payload you passed on creation (used for cross-validation)
`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-chain JSON as returned by the registry provider
`warnings`	Structured warnings / log entries scoped to this registry check

`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": "GB123456789",
  "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": "info@acme.example",
  "phone": "+44 20 7000 0000",
  "legal_entity_identifier": "529900XXXXXXXXXXXXX",
  "location_of_registration": "London",
  "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
`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
`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`)

{
  "uuid": "...",
  "name": "Jane Doe",
  "designation": "Director",
  "role": "director",
  "nationality": "GBR",
  "is_active": true,
  "kyc_status": "Approved",
  "kyc_session_url": "https://verify.didit.me/..."
}

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

{
  "uuid": "...",
  "name": "John Smith",
  "first_name": "John",
  "last_name": "Smith",
  "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 carries both the legacy flat shape and the new two-bucket shape (registry + submitted), plus a high-level UBO KYC summary.

{
  "status": "Approved",
  "node_id": "feature_kyb_key_people",

  "officers": [ ...legacy flat registry officers... ],
  "beneficial_owners": [ ...legacy flat registry UBOs... ],

  "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": []
}

Legacy vs new shape. The flat officers / beneficial_owners arrays are retained for backward compatibility one more release. New integrations should consume the two-bucket shape:

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:

{
  "uuid": "...",
  "entity_type": "person",
  "name": "Alice Chen",
  "first_name": "Alice",
  "last_name": "Chen",
  "email": "alice@acme.example",
  "role": "ubo",
  "ownership_percent": 35.0,
  "nationality": "ESP",
  "position": "CEO",
  "date_of_birth": "1985-03-15",
  "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:

{
  "status": "Approved",
  "node_id": "feature_kyb_documents",
  "items": [
    {
      "uuid": "...",
      "document_type": "certificate_of_incorporation",
      "status": "Approved",
      "file_url": "https://didit-storage.s3...",
      "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), 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

`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",
  "search_reference": "aml_...",
  "is_ongoing_monitoring_enabled": true,
  "hits": []
}

When total_hits > 0, each hit includes match score, risk score, watchlist source, and hit details. 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.

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

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

`aml_screenings[]`

Shared feature arrays

Workflow-driven field filtering

Next steps

Statuses

Risk assessment

AML report

Key people

Documents

Retrieve session

Getting Started

Features

Business Profiles

Reference

Console

​Top-level structure

​Shared top-level fields

​registry_checks[]

​company block

​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[]

​aml_screenings[]

​Shared feature arrays

​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

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

`aml_screenings[]`

Shared feature arrays

Workflow-driven field filtering

Next steps