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-chain JSON as returned by the registry provider
`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": "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
`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
`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`)

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

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

{
  "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:

{
  "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:

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

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

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

​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

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