Data models

Overview

Every per-feature report follows the V3 serializer shape defined in service-didit-verification. The same object appears in three places, so the schema you see here is the single source of truth across them:

GET /v3/session/{sessionId}/decision/ — each feature is returned as a plural array (id_verifications[], nfc_verifications[], liveness_checks[], face_matches[], poa_verifications[], phone_verifications[], email_verifications[], aml_screenings[], ip_analyses[], database_validations[], questionnaire_responses[], and the KYB equivalents registry_checks[], document_verifications[], key_people_checks[]).
Webhook payloads (status.updated, data.updated) — same shape inside the decision envelope.
Standalone APIs — single-object responses (Face Search, Age Estimation, Biometric Authentication) reuse the same field set.

V3 introduced multi-instance workflows: every feature object carries a node_id that pins the report to the workflow graph node that produced it. V2 endpoints (singular kyc, face, aml, etc.) remain backwards-compatible but only return the first instance.

Common fields

Every report object exposes the following:

Field	Type	Description
`status`	string	Feature-level lifecycle status — one of the values in Status enum. Source: `common/config/choices.py:FeatureStatusChoices` (lines 343-348). The parent session’s top-level `status` uses the wider session enum (`StatusChoices`, lines 106-117).
`node_id`	string \| null	Workflow graph node identifier. Populated for V3 multi-instance workflows; `null` for legacy single-feature sessions.
`warnings`	array of warning objects	Risk signals filtered to this feature and `node_id`. Returned by `Session.get_logs(...)` (`sessions/models/session.py:1611`).

Media fields (portrait_image, front_image, document_file, …) are presigned URLs with a limited validity window — download them promptly rather than persisting the URL. Examples show them as https://<media-host>/....

Warning object

Returned in every warnings[] array. Schema from logs/serializers/log.py:8-65 (LogV3Serializer).

Field	Type	Nullable	Description	Example
`feature`	string (enum)	No	Which feature emitted the warning. Values from `LogWarningChoices` (`common/config/choices.py:190-204`): `ID_VERIFICATION`, `NFC`, `LIVENESS`, `FACEMATCH`, `PROOF_OF_ADDRESS`, `PHONE`, `EMAIL`, `AML`, `LOCATION`, `DATABASE_VALIDATION`, `QUESTIONNAIRE`, `KYB_REGISTRY`, `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE`.	`"ID_VERIFICATION"`
`risk`	string	No	Stable risk code (e.g. `DOCUMENT_EXPIRED`, `LOW_LIVENESS_SCORE`). Values from `logs/choices.py:RiskChoices`. Used as the key into description tables.	`"DOCUMENT_EXPIRED"`
`additional_data`	object \| null	Yes	Risk-specific context (e.g. score thresholds, matched fields). Shape varies by risk code.	`{ "score": 42.1, "threshold": 70 }`
`log_type`	string (enum)	No	One of `error`, `warning`, `information`. From `LogTypeChoices` (`common/config/choices.py:207-210`).	`"error"`
`short_description`	string	No	Human-readable label for the risk. From `logs/choices.py:RISK_SHORT_DESCRIPTIONS`.	`"Document expired"`
`long_description`	string	No	Longer human-readable explanation suitable for end-user-facing surfaces. From `logs/choices.py:RISK_LONG_DESCRIPTIONS`.	`"The document's expiration date has passed, rendering it no longer valid for use."`
`node_id`	string \| null	Yes	Workflow graph node the warning was raised against. `null` for legacy V2 logs without `node_id`.	`"first_id_verification"`

{
  "feature": "ID_VERIFICATION",
  "risk": "DOCUMENT_EXPIRED",
  "additional_data": null,
  "log_type": "error",
  "short_description": "Document expired",
  "long_description": "The document's expiration date has passed, rendering it no longer valid for use.",
  "node_id": "first_id_verification"
}

Report objects

The remaining sections cover each per-feature report object. The H3 heading text is intentionally stable so other docs can deep-link to it.

ID verification

Returned from each KYC/ID document a user submits. Appears as id_verifications[] in GET /v3/session/{sessionId}/decision/ and inside the kyc field of V2 responses. Source: kyc/serializers/kyc.py:383-414 (IDVerificationV3Serializer, extends IDVerificationV2Serializer at kyc/serializers/kyc.py:320-380).

Field	Type	Nullable	Description	Example
`status`	string	No	See Status enum.	`"Approved"`
`document_type`	string	Yes	Human-readable document class (`Passport`, `Identity Card`, `Driver's License`, `Residence Permit`, `Health Insurance Card`, `Tax Card`, `Social Security Card`, `Work Permit`, `Visa`, `Public Service Card`, `Birth Certificate`, `Firearm License`, `Other`). Source: `DOC_TYPE_MAPPING` (`common/config/choices.py:1275-1289`).	`"Passport"`
`document_subtype`	string	Yes	Document subtype code from Didit’s document registry, filtered to what the workflow’s document settings accept. Region-specific documents include the region. Full code list: Document subtypes.	`"QUEENSLAND_DRIVER_LICENSE_GENERIC"`
`document_number`	string	Yes	OCR-extracted document number.	`"AB1234567"`
`personal_number`	string	Yes	OCR-extracted personal/national identifier.	`"99999999R"`
`portrait_image`	string (URL)	Yes	Presigned URL to the face crop.	`"https://<media-host>/.../portrait.jpg?..."`
`front_image`	string (URL)	Yes	Presigned URL to the cleaned document front.	`"https://<media-host>/.../front.jpg?..."`
`front_video`	string (URL)	Yes	Presigned URL to the front capture video (when available).	`"https://<media-host>/.../front.mp4?..."`
`back_image`	string (URL)	Yes	Presigned URL to the cleaned document back.	`"https://<media-host>/.../back.jpg?..."`
`back_video`	string (URL)	Yes	Presigned URL to the back capture video.	`null`
`full_front_image`	string (URL)	Yes	Unclipped (full-frame) front capture.	`"https://<media-host>/.../full_front.jpg?..."`
`full_back_image`	string (URL)	Yes	Unclipped (full-frame) back capture.	`null`
`front_image_camera_front`	string (URL)	Yes	Front-camera image taken at the same time as the document front.	`null`
`back_image_camera_front`	string (URL)	Yes	Front-camera image taken at the same time as the document back.	`null`
`front_image_camera_front_face_match_score`	float (0-100)	Yes	Similarity between the document portrait and the front-camera capture.	`null`
`back_image_camera_front_face_match_score`	float (0-100)	Yes	Same as above but for the back capture.	`null`
`front_image_quality_score`	object	Yes	Quality metrics for the front image: scores 0-100 (`focus_score`, `brightness_score`, `resolution_score`, `overall_score`), plus `brightness_issue` (`ok`, `too_dark`, `too_bright`) and `is_document_fully_visible` (boolean).	`{ "focus_score": 91.0, "overall_score": 88.5 }`
`back_image_quality_score`	object	Yes	Same shape as `front_image_quality_score`.	`null`
`date_of_birth`	string (YYYY-MM-DD)	Yes	OCR-extracted DOB.	`"1990-05-12"`
`age`	integer	Yes	Computed age in years at extraction time.	`35`
`expiration_date`	string (YYYY-MM-DD)	Yes	Document expiration.	`"2032-05-11"`
`date_of_issue`	string (YYYY-MM-DD)	Yes	Document issue date.	`"2022-05-11"`
`issuing_state`	string (ISO 3166-1 alpha-3)	Yes	Issuing country code.	`"ESP"`
`issuing_state_name`	string	Yes	Localized issuing country name.	`"Spain"`
`first_name`	string	Yes	OCR-extracted given name(s).	`"María"`
`last_name`	string	Yes	OCR-extracted surname(s).	`"García López"`
`full_name`	string	Yes	Full normalized name (vendor-supplied).	`"María García López"`
`gender`	string	Yes	`M`, `F`, or other vendor-supplied value.	`"F"`
`address`	string	Yes	Raw OCR-extracted address line.	`"Calle Mayor 1, 28001 Madrid"`
`formatted_address`	string	Yes	Geocoded/formatted address (when parseable).	`"Calle Mayor 1, 28001 Madrid, Spain"`
`parsed_address`	object	Yes	Structured, geocoded address: `street_1`, `street_2`, `city`, `region`, `country`, `postal_code`, `address_type`, `formatted_address`, `document_location` (`{latitude, longitude}`), `raw_results`, `is_best_match`. Source: `kyc/utils/address.py:147-197`.	`{ "street_1": "Calle Mayor 1", "city": "Madrid", "postal_code": "28001", "country": "ES" }`
`place_of_birth`	string	Yes	OCR-extracted place of birth.	`"Madrid"`
`marital_status`	string	Yes	When extractable.	`null`
`nationality`	string (ISO 3166-1 alpha-3)	Yes	OCR-extracted nationality.	`"ESP"`
`extra_fields`	object	Yes	Document-type-specific fields not covered by the canonical schema (e.g. driver license categories).	`{ "DL Class": "B" }`
`mrz`	object	Yes	Parsed MRZ fields when present (`document_number`, `birth_date`, `expiry_date`, `surname`, `given_names`, …).	`{ "document_number": "AB1234567", "surname": "GARCIA", "given_names": "MARIA" }`
`extra_files`	array of strings (URL)	No	Presigned URLs to any additional uploaded files.	`[]`
`matches`	array of objects	No	Cross-session document matches. Each item: `{ session_id, session_number, vendor_data, verification_date, user_details: { name, document_type, document_number }, status, is_blocklisted, api_service, front_image_url }`. `front_image_url` is presigned.	`[]`
`verification_method`	string	No	Which ID Verification method produced this row: `document`, `id_lookup` or `wallet`. Always `document` for a photographed document, including every session created before the other methods existed.	`"id_lookup"`
`assurance`	string	No	Assurance tier derived from `verification_method`: `documentary`, `data_match` or `cryptographic`.	`"data_match"`
`wallet_provider`	string \| null	Yes	Catalog wallet id when a wallet produced this row (`mitid`, `bankid_se`, `itsme`, …). `null` otherwise.	`"mitid"`
`fallback_from`	object \| null	Yes	Why a non-document method ended the ID step: `{ method, reason, action }`. Set on the declined row when a lookup or a wallet sign-in failed and the country’s switch was `decline`. Current staging also preserves it on the resulting document verification after a fallback; confirm production rollout. `null` when no earlier non-document failure is recorded.	`{ "method": "id_lookup", "reason": "no_match", "action": "decline" }`
`id_lookup`	object \| null	Yes	Source evidence, present only when `verification_method` is `id_lookup`: `source` (the exact source queried — a government register in most countries, a credit-bureau or residential-records file in some), `checked_at`, `attempts`, `max_attempts`, `outcome` (`match`, `partial_match`, `no_match`, `provider_error`, `format_rejected`), `comparison[]` (`{ field, label, provided, record, result }`; `field` is one of `identification_number`, `full_name`, `date_of_birth`, `address`, and `result` is `match`, `partial` or `no_match`; earlier releases may include a `provider` row with `error`), `source_errors[]` (current staging: separate source diagnostics; confirm production rollout), `registry_portrait` (presigned URL, only for sources that return one) and `face_match_score`.	see below
`wallet_verification`	object \| null	Yes	Credential evidence, present only when `verification_method` is `wallet`: `provider`, `provider_name`, `issuing_authority`, `issuing_country`, `credential_type`, `level_of_assurance` (`low`, `substantial`, `high`), `verified_at`, `signature_valid`, `attributes` (what the wallet shared), `portrait` (presigned URL when the wallet shares one) and `face_match_score`.	see below
`document_liveness`	object \| null	Yes	Document-liveness scores per fraud type (`portrait_replace`, `printed_copy`, `screen_replay`), reported whether or not a warning fired. Each: `score` (0-100, higher = more likely genuine; the lowest side, which is the value the decision used), `front`, `back`, `decline_threshold`, `review_threshold`, `bucket` (`approve`, `review`, `decline`, or `null`). Thresholds and bucket are saved at evaluation time; all three are `null` when historical evaluation evidence is unavailable, while stored scores remain visible. `null` when the check did not run. See Document liveness scores. V3 only.	`{ "portrait_replace": { "score": 96.46, "bucket": "approve" } }`
`node_id`	string \| null	Yes	Workflow node identifier (V3).	`"first_id_verification"`
`warnings`	array	No	See Warning object.	`[]`

{
  "status": "Approved",
  "document_type": "Passport",
  "document_subtype": "PASSPORT_GENERIC",
  "document_number": "AB1234567",
  "personal_number": "99999999R",
  "portrait_image": "https://<media-host>/.../portrait.jpg?signature=...",
  "front_image": "https://<media-host>/.../front.jpg?signature=...",
  "front_video": null,
  "back_image": "https://<media-host>/.../back.jpg?signature=...",
  "back_video": null,
  "full_front_image": "https://<media-host>/.../full_front.jpg?signature=...",
  "full_back_image": null,
  "front_image_camera_front": null,
  "back_image_camera_front": null,
  "front_image_camera_front_face_match_score": null,
  "back_image_camera_front_face_match_score": null,
  "front_image_quality_score": {
    "focus_score": 91.0,
    "brightness_score": 88.0,
    "brightness_issue": "ok",
    "is_document_fully_visible": true,
    "resolution_score": 95.0,
    "overall_score": 88.5
  },
  "back_image_quality_score": null,
  "date_of_birth": "1990-05-12",
  "age": 35,
  "expiration_date": "2032-05-11",
  "date_of_issue": "2022-05-11",
  "issuing_state": "ESP",
  "issuing_state_name": "Spain",
  "first_name": "María",
  "last_name": "García López",
  "full_name": "María García López",
  "gender": "F",
  "address": "Calle Mayor 1, 28001 Madrid",
  "formatted_address": "Calle Mayor 1, 28001 Madrid, Spain",
  "parsed_address": { "street_1": "Calle Mayor 1", "street_2": null, "city": "Madrid", "region": "Madrid", "postal_code": "28001", "country": "ES", "address_type": "Calle" },
  "place_of_birth": "Madrid",
  "marital_status": null,
  "nationality": "ESP",
  "extra_fields": {},
  "mrz": {
    "document_number": "AB1234567",
    "surname": "GARCIA",
    "given_names": "MARIA",
    "birth_date": "900512",
    "expiry_date": "320511"
  },
  "extra_files": [],
  "matches": [],
  "node_id": "first_id_verification",
  "verification_method": "document",
  "assurance": "documentary",
  "wallet_provider": null,
  "fallback_from": null,
  "id_lookup": null,
  "wallet_verification": null,
  "document_liveness": {
    "portrait_replace": {
      "score": 96.46,
      "front": 96.46,
      "back": 98.2,
      "decline_threshold": 35,
      "review_threshold": 70,
      "bucket": "approve"
    },
    "printed_copy": {
      "score": 91.2,
      "front": 91.2,
      "back": 93.7,
      "decline_threshold": 35,
      "review_threshold": 77,
      "bucket": "approve"
    },
    "screen_replay": {
      "score": 99.9,
      "front": 99.9,
      "back": 99.5,
      "decline_threshold": 30,
      "review_threshold": 70,
      "bucket": "approve"
    }
  },
  "warnings": []
}

The same object with a non-document method. Only the method-specific keys change — everything a document read fills in is populated from the register record or the wallet attributes instead, and the keys that do not apply are null.

{
  "status": "Approved",
  "issuing_state": "ZAF",
  "first_name": "Thabo",
  "last_name": "Mokoena",
  "full_name": "Thabo Mokoena",
  "date_of_birth": "1991-06-15",
  "personal_number": "9106155043088",
  "node_id": "first_id_verification",
  "verification_method": "id_lookup",
  "assurance": "data_match",
  "wallet_provider": null,
  "fallback_from": null,
  "id_lookup": {
    "source": "Department of Home Affairs",
    "checked_at": "2026-09-04T09:12:44Z",
    "attempts": 1,
    "max_attempts": 2,
    "outcome": "match",
    "comparison": [
      { "field": "identification_number", "label": "ID number", "provided": "9106155043088", "record": "9106155043088", "result": "match" },
      { "field": "full_name", "label": "Full name", "provided": "Thabo Mokoena", "record": "Thabo Mokoena", "result": "match" },
      { "field": "date_of_birth", "label": "Date of birth", "provided": "1991-06-15", "record": "1991-06-15", "result": "match" }
    ],
    "registry_portrait": "https://<media-host>/.../registry_portrait.jpg?signature=...",
    "face_match_score": 96.4
  },
  "wallet_verification": null,
  "warnings": []
}

{
  "status": "Approved",
  "issuing_state": "DNK",
  "first_name": "Freja",
  "last_name": "Nielsen",
  "full_name": "Freja Nielsen",
  "date_of_birth": "1988-03-02",
  "node_id": "first_id_verification",
  "verification_method": "wallet",
  "assurance": "cryptographic",
  "wallet_provider": "mitid",
  "fallback_from": null,
  "id_lookup": null,
  "wallet_verification": {
    "provider": "mitid",
    "provider_name": "MitID",
    "issuing_authority": "Danish Agency for Digital Government",
    "issuing_country": "DNK",
    "credential_type": "person_identification",
    "level_of_assurance": "substantial",
    "verified_at": "2026-09-04T09:12:44Z",
    "signature_valid": true,
    "attributes": {
      "full_name": "Freja Nielsen",
      "date_of_birth": "1988-03-02",
      "cpr_alias": "b0f1c2d3-e4f5-4678-9abc-def012345678"
    },
    "portrait": null,
    "face_match_score": null
  },
  "warnings": []
}

NFC verification

Returned for each ePassport chip read against an ID document. Appears as nfc_verifications[] in GET /v3/session/{sessionId}/decision/ (one per parent KYC record). Source: kyc/serializers/epassport.py:121-139 (NFCV3Serializer, extends NFCV2Serializer at kyc/serializers/epassport.py:83-118).

Field	Type	Nullable	Description	Example
`status`	string	No	See Status enum.	`"Approved"`
`portrait_image`	string (URL)	Yes	Presigned URL to the chip-extracted face image.	`"https://<media-host>/.../nfc_portrait.jpg?..."`
`signature_image`	string (URL)	Yes	Presigned URL to the chip-extracted signature image (when stored on the chip).	`null`
`chip_data`	object	Yes	Personal data parsed from the chip’s Data Groups, flattened (`kyc/utils/epassport.py:165-212`): `dgs` (Data Groups read), `surname`, `name`, `country`, `nationality`, `birth_date` (`YYYY-MM-DD`), `expiry_date` (`YYYY-MM-DD`), `sex` (`M`/`F`), `document_type` (MRZ document code), `document_number`, `optional_data`, MRZ check digits (`birth_date_hash`, `expiry_date_hash`, `document_number_hash`, `optional_data_hash`, `final_hash`), `mrz_string`, `mrz_type` (`TD1`/`TD2`/`TD3`); plus `place_of_birth` and `address` (and `full_name` / `full_name_non_latin` for non-Latin names) when the chip carries DG11 — those keys are absent otherwise. `null` when the NFC step was skipped.	`{ "document_number": "AB1234567", "name": "MARIA" }`
`authenticity`	object	No	`{ sod_integrity, dg_integrity }`. `sod_integrity` validates that the Document Security Object (SOD) signature chains to a valid issuing-country CSCA (and the DSC is neither revoked nor expired); `dg_integrity` validates that each Data Group hashes match the SOD. Both `true` means the chip is genuine and untampered.	`{ "sod_integrity": true, "dg_integrity": true }`
`certificate_summary`	object	Yes	Summary of the document-signer certificate (`kyc/utils/epassport.py:338-348`): `issuer`, `subject`, `serial_number` (integer), `not_valid_before`, `not_valid_after` (`YYYY-MM-DD HH:MM:SS`), plus a `validation` object `{ csca_verified, dsc_revoked, dsc_expired, csca_expired }` (`kyc/views/epassport.py:86`).	`{ "issuer": "Common Name: CSCA SPAIN, Country: ES", "not_valid_after": "2031-02-18 10:21:11" }`
`node_id`	string \| null	Yes	Workflow node identifier (V3).	`"first_nfc"`
`is_nfc_skipped`	boolean	No	`true` when this NFC step was explicitly skipped instead of read; `skip_reason` says why.	`false`
`skip_reason`	string	Yes	Why the step was skipped — only set when `is_nfc_skipped` is `true`. One of `USER_SKIPPED`, `DOCUMENT_WITHOUT_CHIP`, `CHIP_CERTIFICATE_UNAVAILABLE`, `DEVICE_WITHOUT_NFC`, `INTEGRATION_WITHOUT_NFC_ACCESS`, `MRZ_KEY_UNAVAILABLE`; see Skip reasons. The decision payload also carries a session-level `nfc_skip_reason` with the same taxonomy, covering NFC steps that were bypassed before creating any report.	`null`
`warnings`	array	No	See Warning object.	`[]`

{
  "status": "Approved",
  "portrait_image": "https://<media-host>/.../nfc_portrait.jpg?signature=...",
  "signature_image": null,
  "chip_data": {
    "dgs": ["DG1", "DG2", "DG11"],
    "surname": "GARCIA LOPEZ",
    "name": "MARIA",
    "country": "ESP",
    "nationality": "ESP",
    "birth_date": "1990-05-12",
    "expiry_date": "2032-05-11",
    "sex": "F",
    "document_type": "P",
    "document_number": "AB1234567",
    "optional_data": "",
    "birth_date_hash": "4",
    "expiry_date_hash": "7",
    "document_number_hash": "3",
    "optional_data_hash": "",
    "final_hash": "8",
    "mrz_string": "P<ESPGARCIA<LOPEZ<<MARIA<<<<<<<<<<<<<<<<<<<<AB1234567ESP9005124F3205117<<<<<<<<<<<<<<08",
    "mrz_type": "TD3",
    "place_of_birth": "MADRID",
    "address": "CALLE MAYOR 1, MADRID"
  },
  "authenticity": { "sod_integrity": true, "dg_integrity": true },
  "certificate_summary": {
    "issuer": "Common Name: CSCA SPAIN, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
    "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
    "serial_number": 118120836164494130086420187336801405660,
    "not_valid_before": "2020-11-18 10:21:11",
    "not_valid_after": "2031-02-18 10:21:11",
    "validation": {
      "csca_verified": true,
      "dsc_revoked": false,
      "dsc_expired": false,
      "csca_expired": false
    }
  },
  "node_id": "first_nfc",
  "is_nfc_skipped": false,
  "skip_reason": null,
  "warnings": []
}

Liveness check

Returned per liveness session. Appears as liveness_checks[] in GET /v3/session/{sessionId}/decision/. Source: face/serializers/face.py:301-320 (LivenessV3Serializer, extends LivenessV2Serializer at face/serializers/face.py:216-298).

Field	Type	Nullable	Description	Example
`status`	string	No	See Status enum.	`"Approved"`
`method`	string (enum)	Yes	`ACTIVE_3D`, `FLASHING`, or `PASSIVE` (`LivenessMethodChoices`, `common/config/choices.py:514-517`). Passive runs when desktop sessions are allowed and the user is on a desktop.	`"PASSIVE"`
`score`	float (0-100)	Yes	Liveness confidence, rounded to 2 decimals.	`92.41`
`reference_image`	string (URL)	Yes	Presigned URL to the user’s reference face crop.	`"https://<media-host>/.../reference.jpg?..."`
`video_url`	string (URL)	Yes	Presigned URL to the liveness video (active mode only).	`"https://<media-host>/.../liveness.webm?..."`
`age_estimation`	float	Yes	Estimated age (in years) of the largest face in the reference image.	`34.2`
`matches`	array of objects	No	Cross-session face matches. Each item: `{ session_id, session_number, similarity_percentage, vendor_data, vendor_user_id, biometric_template_id, verification_date, user_details: { full_name, document_type, document_number }, match_image_url, status, is_blocklisted, is_allowlisted, api_service, source }`. `source` is `session`, `imported`, `list_entry`, or `retained_template`. A retained-template match has `vendor_user_id`, `vendor_data`, and `biometric_template_id`; its session, image, identity-detail, status, and API-service fields are `null`.	`[]`
`face_quality`	float (0-100)	Yes	Passive-liveness face-quality score (normalized to a percentage).	`87.50`
`face_luminance`	float (0-100)	Yes	Passive-liveness face-luminance score (normalized from 0-255 to a percentage).	`54.12`
`node_id`	string \| null	Yes	Workflow node identifier (V3).	`"first_liveness"`
`warnings`	array	No	See Warning object.	`[]`

{
  "status": "Approved",
  "method": "PASSIVE",
  "score": 92.41,
  "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
  "video_url": null,
  "age_estimation": 34.2,
  "matches": [],
  "face_quality": 87.50,
  "face_luminance": 54.12,
  "node_id": "first_liveness",
  "warnings": []
}

Face match

Returned per face-match comparison (typically the user’s liveness face against the document portrait). Appears as face_matches[] in GET /v3/session/{sessionId}/decision/. Source: face/serializers/face.py:367-389 (FaceMatchV3Serializer, extends FaceMatchV2Serializer at face/serializers/face.py:323-364).

Field	Type	Nullable	Description	Example
`status`	string	No	See Status enum.	`"Approved"`
`score`	float (0-100)	Yes	Similarity, rounded to 2 decimals. When the provider returns only an `unmatched_faces[].Confidence`, it’s converted to `100 - confidence`.	`97.83`
`source_image_session_id`	string (UUID)	Yes	The session whose stored portrait supplied the source (reference) image — set in portrait-based flows (biometric authentication, or a portrait supplied at session creation). `null` when the reference is the document portrait from the same session.	`null`
`source_image`	string (URL)	Yes	Presigned URL to the source (reference) image — usually the document portrait, or the stored portrait in biometric-authentication flows.	`"https://<media-host>/.../source.jpg?..."`
`target_image`	string (URL)	Yes	Presigned URL to the target (live face) image captured during liveness.	`"https://<media-host>/.../target.jpg?..."`
`node_id`	string \| null	Yes	Workflow node identifier (V3).	`"first_face_match"`
`warnings`	array	No	See Warning object.	`[]`

{
  "status": "Approved",
  "score": 97.83,
  "source_image_session_id": null,
  "source_image": "https://<media-host>/.../source.jpg?signature=...",
  "target_image": "https://<media-host>/.../target.jpg?signature=...",
  "node_id": "first_face_match",
  "warnings": []
}

Face search

Returned by the standalone Face Search API (POST /v3/face-search/). Face Search never appears as a plural array in /v3/session/{sessionId}/decision/ — when persisted with save_api_request=true the session surfaces there as a FACE_SEARCH entry in features[] plus a liveness_checks[] item carrying the stored matches. Sources: apis/serializers/face_search.py:8-79 (FaceSearchResponseSerializer wrapping FaceSearchDetailsSerializer); match dicts built in face/utils/utils.py:869-884. Top-level response:

Field	Type	Nullable	Description	Example
`request_id`	string (UUID)	No	The persisted session id when `save_api_request=true` (usable with `GET /v3/session/{sessionId}/decision/`); otherwise a transient correlation UUID.	`"4a1c2c4e-8b1b-4d6a-91b5-ee9a1f3a2c7f"`
`face_search`	object	No	The search-details payload — see fields below.	—
`vendor_data`	string	Yes	Echoed `vendor_data` from the request.	`null`
`metadata`	object	Yes	Echoed `metadata` from the request.	`null`
`created_at`	string (ISO 8601)	No	Server-side request timestamp.	`"2026-06-12T01:04:42.763237+00:00"`

face_search object:

Field	Type	Nullable	Description	Example
`status`	string	No	`Declined` only when a `FACE_IN_BLOCKLIST` or `POSSIBLE_FACE_IN_BLOCKLIST` warning fired; `Approved` otherwise — duplicate matches alone never decline (`apis/views/face_search.py:242-248`).	`"Approved"`
`total_matches`	integer	No	Number of returned matches in `matches[]` (0–5).	`1`
`matches`	array of face-search match objects	No	Up to 5 matches above the similarity floor, sorted by descending similarity (blocklisted entries first with `search_type=blocklisted_or_approved`).	`[…]`
`user_image`	object	No	Detection result for the submitted image: `{ entities: [{ bbox, confidence }], best_angle }` — one entity per detected face.	`{ "entities": [{ "bbox": [40, 40, 120, 120], "confidence": 0.73 }], "best_angle": 0 }`
`warnings`	array of objects	No	Reduced warning shape for this standalone API — no `node_id`. The serializer contract declares `{ risk, additional_data, log_type, short_description, long_description }` (`apis/serializers/face_search.py:49-54`); the runtime payload also carries `feature`, always `"LIVENESS"` (`apis/views/face_search.py:332-341`).	`[]`

Face-search match object

Field	Type	Nullable	Description	Example
`session_id`	string (UUID)	Yes	The matched verification session. `null` when `source` is `imported`, `list_entry`, or `retained_template`.	`"a3f2a6f1-…"`
`session_number`	integer	Yes	Console-friendly number of the matched session; `null` for non-session matches.	`1024`
`similarity_percentage`	float (0-100)	No	Similarity between the submitted face and the matched face.	`96.42`
`source`	string (enum)	No	Where the matched face was enrolled from: `session` (verification session or saved standalone call), `imported` (direct user-profile face upload), `list_entry` (face attached to a list), `retained_template` (image-free biometric template retained after the source session was deleted).	`"session"`
`vendor_data`	string	Yes	The matched session’s `vendor_data`, or the linked User’s for `imported` and `retained_template` matches.	`"user-12345"`
`vendor_user_id`	string (UUID)	Yes	The linked User. `null` for `list_entry` matches and for sessions without a User.	`"2f7c1a9e-…"`
`biometric_template_id`	string (UUID)	Yes	The retained template that matched. Set only for `retained_template` matches; use it with `GET`/`DELETE /v3/biometric-templates/{id}/`.	`null`
`verification_date`	string (ISO 8601)	Yes	When the matched face was captured, or when a `retained_template` was retained; `null` for `list_entry` matches.	`"2024-11-04T09:14:02Z"`
`user_details`	object	Yes	`{ full_name, document_type, document_number }` from the matched session’s document verification; for `imported` matches only `full_name` is set; `null` when no identity data exists and always `null` for `retained_template` matches.	`{ "full_name": "María García López", "document_type": "Passport", "document_number": "AB1234567" }`
`match_image_url`	string (URL)	Yes	Matched user’s reference face — presigned URL when `save_api_request=true`, raw storage path otherwise. Always `null` for `retained_template` matches, which hold no image.	`"https://<media-host>/.../matched.jpg?..."`
`status`	string	Yes	The matched session’s verification status (see Status enum); `null` for non-session matches.	`"Approved"`
`is_blocklisted`	boolean	No	Whether the matched face is in your face blocklist. Always `false` for `retained_template` matches; a blocklisted face is reported separately as a `list_entry` match.	`false`
`is_allowlisted`	boolean	No	Whether the matched face is in one of your allowlists.	`false`
`api_service`	string (enum)	Yes	Uppercase standalone API type of the matched session (e.g. `PASSIVE_LIVENESS`, `FACE_MATCH`); `null` for workflow sessions and non-session matches.	`null`

{
  "request_id": "4a1c2c4e-8b1b-4d6a-91b5-ee9a1f3a2c7f",
  "face_search": {
    "status": "Approved",
    "total_matches": 1,
    "matches": [
      {
        "session_id": "a3f2a6f1-1c1c-4eec-8b69-1c1c2f3a2c7f",
        "session_number": 1024,
        "similarity_percentage": 96.42,
        "source": "session",
        "vendor_data": "user-12345",
        "verification_date": "2024-11-04T09:14:02Z",
        "user_details": {
          "full_name": "María García López",
          "document_type": "Passport",
          "document_number": "AB1234567"
        },
        "match_image_url": "https://<media-host>/.../matched.jpg?signature=...",
        "status": "Approved",
        "is_blocklisted": false,
        "is_allowlisted": false,
        "api_service": null
      }
    ],
    "user_image": {
      "entities": [
        {
          "bbox": [40, 40, 120, 120],
          "confidence": 0.732973
        }
      ],
      "best_angle": 0
    },
    "warnings": []
  },
  "vendor_data": null,
  "metadata": null,
  "created_at": "2026-06-12T01:04:42.763237+00:00"
}

AML screening

Returned per screened entity. Appears as aml_screenings[] in GET /v3/session/{sessionId}/decision/ for both KYC and KYB sessions. Source: aml/serializers/aml.py:63-85 (AMLV3Serializer, extends AMLV2Serializer at aml/serializers/aml.py:28-60).

Field	Type	Nullable	Description	Example
`status`	string	No	See Status enum.	`"Approved"`
`total_hits`	integer	No	Number of screening hits (always present, defaults to `0`).	`2`
`entity_type`	string (enum)	Yes	`person` or `company` (`EntityTypeChoices`, `common/config/choices.py:675-677`).	`"person"`
`hits`	array of objects	No	One entry per hit. Key fields: `id`, `caption`, `match` (bool), `target` (bool \| null — whether the entity is the direct target of the listing), `match_score` (float 0-100 identity confidence), `risk_score` (float 0-100 entity risk), `score` (deprecated 0-1 float), `datasets[]` (e.g. `PEP`, `PEP Level 1`-`4`, `Sanctions`, `Adverse Media`, `Warnings and Regulatory Enforcement`, `Fitness and Probity`), `properties` (names, aliases, dates of birth, …), `features`, `url`, `first_seen`, `last_seen`, `rca_name`, `risk_view`, `score_breakdown`, `pep_matches`, `sanction_matches`, `warning_matches`, `adverse_media_matches`, `adverse_media_details`, `linked_entities`, `additional_information`, and `review_status` (`Unreviewed`, `Confirmed Match`, `False Positive`, `Inconclusive` — editable via the update-AML-hit-status endpoint, `AMLHitStatusChoices`).	`[…]`
`score`	float (0-100)	Yes	Overall screening score — the highest `risk_score` among hits not marked `False Positive` (`aml/services/aml.py:832-842`); `0` when every hit is a false positive. `null` until computed.	`42.7`
`screened_data`	object	Yes	Snapshot of the data sent to screening: `full_name`, `nationality`, `date_of_birth`, `document_number`.	`{ "full_name": "María García López", "date_of_birth": "1990-05-12" }`
`is_ongoing_monitoring_enabled`	boolean	No	Whether the entity is subscribed to ongoing-monitoring re-screens.	`false`
`next_ongoing_monitoring_bill_date`	string (YYYY-MM-DD)	Yes	Computed as `last_aml_bill_date + 365 days` when ongoing monitoring is enabled. A billing date, not a screening date.	`null`
`last_ongoing_screening_at`	string (ISO 8601)	Yes	When ongoing monitoring last completed a re-screening of this record, whether or not the result changed. `null` when never re-screened; never back-filled.	`"2026-09-12T04:03:11Z"`
`last_ongoing_screening_datasets_updated_at`	string (ISO 8601)	Yes	Most recent AML dataset update the provider reported for that screening. `null` when no dataset date was reported; never estimated.	`null`
`node_id`	string \| null	Yes	Workflow node identifier (V3).	`"first_aml"`
`warnings`	array	No	See Warning object.	`[]`

{
  "status": "In Review",
  "total_hits": 1,
  "entity_type": "person",
  "hits": [
    {
      "id": "Q7XW3-aml-hit-1",
      "caption": "Maria Garcia Lopez",
      "match": true,
      "target": true,
      "match_score": 86.4,
      "risk_score": 42.7,
      "datasets": ["PEP Level 2"],
      "properties": {
        "name": ["María García López", "M. García"],
        "alias": ["Maria Garcia"],
        "birthDate": ["1990-05-12"]
      },
      "url": "https://example.org/registry/entities/Q7XW3",
      "first_seen": "2023-11-02T00:00:00Z",
      "last_seen": "2026-05-01T00:00:00Z",
      "review_status": "Unreviewed"
    }
  ],
  "score": 42.7,
  "screened_data": {
    "full_name": "María García López",
    "date_of_birth": "1990-05-12",
    "nationality": "ES",
    "document_number": "AB1234567"
  },
  "is_ongoing_monitoring_enabled": false,
  "next_ongoing_monitoring_bill_date": null,
  "last_ongoing_screening_at": null,
  "last_ongoing_screening_datasets_updated_at": null,
  "node_id": "first_aml",
  "warnings": []
}

IP analysis

Returned per captured network location. Appears as ip_analyses[] in GET /v3/session/{sessionId}/decision/ for both KYC and KYB sessions. Source: kyc/serializers/location.py:196-243 (IPAnalysisSerializerV3).

Field	Type	Nullable	Description	Example
`status`	string	No	See Status enum.	`"Approved"`
`node_id`	string \| null	Yes	Workflow node identifier (V3).	`"first_ip_analysis"`
`device_brand`	string	Yes	User-agent-derived device brand.	`"Apple"`
`device_model`	string	Yes	Device model.	`"iPhone"`
`browser_family`	string	Yes	Browser family.	`"Mobile Safari"`
`os_family`	string	Yes	OS family.	`"iOS"`
`platform`	string	Yes	High-level platform (`mobile`, `desktop`, `tablet`).	`"mobile"`
`device_fingerprint`	string	Yes	Stable per-device fingerprint hash.	`"f2a3…"`
`ip_country`	string	Yes	Country name resolved from the IP.	`"Spain"`
`ip_country_code`	string (ISO 3166-1 alpha-2)	Yes	Country code resolved from the IP.	`"ES"`
`ip_state`	string	Yes	Region / state resolved from the IP.	`"Comunidad de Madrid"`
`ip_city`	string	Yes	City resolved from the IP.	`"Madrid"`
`latitude`	float	Yes	IP-derived latitude.	`40.4168`
`longitude`	float	Yes	IP-derived longitude.	`-3.7038`
`ip_address`	string	Yes	The captured IP address.	`"203.0.113.42"`
`isp`	string	Yes	ISP name.	`"Telefonica de Espana"`
`organization`	string	Yes	Organization name (often equal to ISP).	`"Telefonica de Espana"`
`is_vpn_or_tor`	boolean	Yes	`true` when the IP belongs to a VPN, proxy, or Tor exit node.	`false`
`is_data_center`	boolean	Yes	`true` when the IP belongs to a known hosting / data-center ASN.	`false`
`time_zone`	string	Yes	IANA time-zone name.	`"Europe/Madrid"`
`time_zone_offset`	string	Yes	UTC offset.	`"+02:00"`
`ip`	object	No	`{ location, distance_from_id_document, distance_from_poa_document }`. `location = { latitude, longitude }`. Distances in km, `null` when either side is missing.	`{ "location": { "latitude": 40.4168, "longitude": -3.7038 }, "distance_from_id_document": 3.4, "distance_from_poa_document": 1.1 }`
`id_document`	object	No	`{ location, distance_from_ip, distance_from_poa_document }`. ID document location resolved from `issuing_state` and parsed address.	`{ "location": { "latitude": 40.4165, "longitude": -3.7026 }, "distance_from_ip": 3.4, "distance_from_poa_document": 4.0 }`
`poa_document`	object	No	`{ location, distance_from_ip, distance_from_id_document }`. POA address geocoded.	`{ "location": { "latitude": 40.4170, "longitude": -3.7040 }, "distance_from_ip": 1.1, "distance_from_id_document": 4.0 }`
`matches`	array of objects	No	Cross-session IP/device matches. Each item: `{ session_id, session_number, vendor_data, verification_date, match_type, match_source, matched_value, status, is_blocklisted, api_service, source, device_info, location_info, confidence, match_mode }`. `match_type` is `ip_address` or `device_fingerprint`; `match_source` is `ip_address`, `persistent_id`, `legacy_fp`, or `recovered_high` (recovered matches also carry `recovery_similarity`, `tls_ja4_corroborated`, `recovery_gate_reason`). Capped at 5 IP + 5 device matches.	`[]`
`warnings`	array	No	See Warning object.	`[]`

{
  "status": "Approved",
  "node_id": "first_ip_analysis",
  "device_brand": "Apple",
  "device_model": "iPhone",
  "browser_family": "Mobile Safari",
  "os_family": "iOS",
  "platform": "mobile",
  "device_fingerprint": "f2a3c1de8b994a3f9e4cdf3a02b1a7c9",
  "ip_country": "Spain",
  "ip_country_code": "ES",
  "ip_state": "Comunidad de Madrid",
  "ip_city": "Madrid",
  "latitude": 40.4168,
  "longitude": -3.7038,
  "ip_address": "203.0.113.42",
  "isp": "Telefonica de Espana",
  "organization": "Telefonica de Espana",
  "is_vpn_or_tor": false,
  "is_data_center": false,
  "time_zone": "Europe/Madrid",
  "time_zone_offset": "+02:00",
  "ip": {
    "location": { "latitude": 40.4168, "longitude": -3.7038 },
    "distance_from_id_document": 3.4,
    "distance_from_poa_document": 1.1
  },
  "id_document": {
    "location": { "latitude": 40.4165, "longitude": -3.7026 },
    "distance_from_ip": 3.4,
    "distance_from_poa_document": 4.0
  },
  "poa_document": {
    "location": { "latitude": 40.4170, "longitude": -3.7040 },
    "distance_from_ip": 1.1,
    "distance_from_id_document": 4.0
  },
  "matches": [],
  "warnings": []
}

Proof of address

Returned per submitted address document. Appears as poa_verifications[] in GET /v3/session/{sessionId}/decision/. Source: poa/serializers/poa.py:212-227 (POAV3Serializer, extends POAV2Serializer at poa/serializers/poa.py:173-209).

Field	Type	Nullable	Description	Example
`status`	string	No	See Status enum.	`"Approved"`
`issuing_state`	string (ISO 3166-1 alpha-3)	Yes	Country code of the document issuer.	`"ESP"`
`document_type`	string	No	High-level type from `PoaDocumentTypeChoices` (`common/config/choices.py:868-873`): `UTILITY_BILL`, `BANK_STATEMENT`, `GOVERNMENT_ISSUED_DOCUMENT`, `OTHER_POA_DOCUMENT`. Falls back to `UNKNOWN` — never `null`.	`"UTILITY_BILL"`
`document_subtype`	string	No	Subtype code from `PoaDocumentSubtypeChoices` (e.g. `ELECTRICITY_BILL`, `WATER_BILL`, `ACCOUNT_STATEMENT`). Falls back to `UNKNOWN` — never `null`.	`"ELECTRICITY_BILL"`
`issuer`	string	Yes	Name of the issuing entity.	`"Iberdrola"`
`issue_date`	string (YYYY-MM-DD)	Yes	Document issue date.	`"2026-04-15"`
`expiration_date`	string (YYYY-MM-DD)	Yes	Expiration date printed on the document, when present.	`null`
`poa_address`	string	Yes	Raw OCR-extracted address.	`"Calle Mayor 1, 28001 Madrid"`
`poa_formatted_address`	string	Yes	Geocoded/formatted address.	`"Calle Mayor 1, 28001 Madrid, Spain"`
`poa_parsed_address`	object	Yes	Structured address (`street_1`, `street_2`, `city`, `region`, `postal_code`, `country` (alpha-2), `address_type`, `document_location`, …).	`{ "street_1": "Calle Mayor 1", "city": "Madrid", "postal_code": "28001" }`
`document_file`	string (URL)	Yes	Presigned URL to the uploaded document.	`"https://<media-host>/.../poa.pdf?..."`
`document_language`	string	Yes	Detected document language (ISO 639-1).	`"es"`
`document_metadata`	object	Yes	Filtered metadata: `file_size`, `content_type`, `creation_date`, `modified_date`, `creator`, `producer`, `software`, `encryption`, `is_signed`, `is_tampered`, `signature_info`, `exif_original_date`, `exif_digitized_date`, `processed_by_known_editor`, `has_different_creation_mod_date`, `overlay_manipulation`.	`{ "file_size": 184221, "content_type": "application/pdf", "is_tampered": false }`
`extra_fields`	object	No	Bank-account fields (`bank_account_number`, `bank_iban`, `bank_sort_code`, `bank_routing_number`, `bank_swift_bic`, `bank_branch_name`, `bank_branch_address`), `document_phone_number`, `additional_names`, plus any custom keys persisted on the record.	`{ "bank_iban": null, "additional_names": [] }`
`name_on_document`	string	Yes	Name as it appears on the POA.	`"María García López"`
`expected_details_address`	string	Yes	Address the customer typed during signup (verbatim).	`"Calle Mayor 1, Madrid"`
`expected_details_formatted_address`	string	Yes	Geocoded expected address.	`"Calle Mayor 1, 28001 Madrid, Spain"`
`expected_details_parsed_address`	object	Yes	Structured expected address.	`{ "city": "Madrid", "postal_code": "28001" }`
`name_match_score_expected_details`	float (0-100)	Yes	Fuzzy match between `name_on_document` and the name supplied at session creation.	`94.0`
`name_match_score_id_verification`	float (0-100)	Yes	Fuzzy match between `name_on_document` and the verified ID’s `full_name`.	`100.0`
`extra_files`	array of strings (URL)	No	Presigned URLs to additional uploaded files.	`[]`
`detected_codes`	array of objects	No	QR codes and barcodes detected across every processed page of the document: `type`, `page_number` (1-based), `position` (polygon), `x`/`y`/`width`/`height` (bounding box), `page_width`/`page_height`, `raw_payload` (base64), `parsed_payload` (decoded value, `null` when a code was located but could not be decoded). Empty array when detection finds nothing.	`[{ "type": "QR_CODE", "page_number": 1, "parsed_payload": "https://issuer.example/inv/9981" }]`
`node_id`	string \| null	Yes	Workflow node identifier (V3).	`"first_poa"`
`warnings`	array	No	See Warning object.	`[]`

{
  "status": "Approved",
  "issuing_state": "ESP",
  "document_type": "UTILITY_BILL",
  "document_subtype": "ELECTRICITY_BILL",
  "issuer": "Iberdrola",
  "issue_date": "2026-04-15",
  "expiration_date": null,
  "poa_address": "Calle Mayor 1, 28001 Madrid",
  "poa_formatted_address": "Calle Mayor 1, 28001 Madrid, Spain",
  "poa_parsed_address": { "street_1": "Calle Mayor 1", "city": "Madrid", "postal_code": "28001", "country": "ES" },
  "document_file": "https://<media-host>/.../poa.pdf?signature=...",
  "document_language": "es",
  "document_metadata": {
    "file_size": 184221,
    "content_type": "application/pdf",
    "creation_date": "2026-04-15T08:11:32Z",
    "modified_date": "2026-04-15T08:11:32Z",
    "creator": "Iberdrola Billing",
    "producer": "Adobe PDF Library 15.0",
    "software": null,
    "encryption": null,
    "is_signed": true,
    "is_tampered": false,
    "signature_info": { "signer_name": "Iberdrola Clientes", "date": "2026-04-15T08:11:32Z" },
    "exif_original_date": null,
    "exif_digitized_date": null,
    "processed_by_known_editor": false,
    "has_different_creation_mod_date": false,
    "overlay_manipulation": null
  },
  "extra_fields": {
    "bank_account_number": null,
    "bank_iban": null,
    "bank_sort_code": null,
    "bank_routing_number": null,
    "bank_swift_bic": null,
    "bank_branch_name": null,
    "bank_branch_address": null,
    "document_phone_number": null,
    "additional_names": []
  },
  "name_on_document": "María García López",
  "expected_details_address": "Calle Mayor 1, Madrid",
  "expected_details_formatted_address": "Calle Mayor 1, 28001 Madrid, Spain",
  "expected_details_parsed_address": { "city": "Madrid", "postal_code": "28001", "country": "ES" },
  "name_match_score_expected_details": 94.0,
  "name_match_score_id_verification": 100.0,
  "extra_files": [],
  "detected_codes": [
    {
      "type": "QR_CODE",
      "page_number": 1,
      "position": [[820, 1120], [1002, 1120], [1002, 1302], [820, 1302]],
      "x": 820,
      "y": 1120,
      "width": 182,
      "height": 182,
      "page_width": 1190,
      "page_height": 1684,
      "raw_payload": "aHR0cHM6Ly9pYmVyZHJvbGEuZXMvZmFjdHVyYS85OTgx",
      "parsed_payload": "https://iberdrola.es/factura/9981"
    },
    {
      "type": "CODE_128",
      "page_number": 1,
      "position": [[112, 1480], [560, 1480], [560, 1540], [112, 1540]],
      "x": 112,
      "y": 1480,
      "width": 448,
      "height": 60,
      "page_width": 1190,
      "page_height": 1684,
      "raw_payload": "MDA5OTgxMDAwNDI=",
      "parsed_payload": "0099810042"
    }
  ],
  "node_id": "first_poa",
  "warnings": []
}

Phone verification

Returned per phone-verification attempt. Appears as phone_verifications[] in GET /v3/session/{sessionId}/decision/ for both KYC and KYB sessions. Source: phone/serializers/phone.py:251-266 (PhoneV3Serializer, extends PhoneV2Serializer at phone/serializers/phone.py:103-248).

Field	Type	Nullable	Description	Example
`status`	string	No	See Status enum.	`"Approved"`
`phone_number_prefix`	string	No	E.164 country prefix (with `+`).	`"+34"`
`phone_number`	string	No	Subscriber number without the prefix.	`"612345678"`
`full_number`	string	No	The full E.164 number (`phone_number_prefix + phone_number`).	`"+34612345678"`
`country_code`	string (ISO 3166-1 alpha-2)	Yes	Country of the number.	`"ES"`
`country_name`	string	Yes	Localized country name.	`"Spain"`
`carrier`	object	No	`{ name, type }` where `type` is a `LineTypeChoices` value (`common/config/choices.py:648-667`): `mobile`, `fixed_line`, `voip`, `isp`, `vpn`, `toll_free`, `premium_rate`, `satellite`, `pager`, `payphone`, `voice_mail`, `unknown`, and other line classes.	`{ "name": "Movistar", "type": "mobile" }`
`is_disposable`	boolean	No	`true` when the carrier marks the number as temporary/disposable.	`false`
`is_virtual`	boolean	No	`true` when `carrier.type` is one of `voip`, `isp`, `vpn`.	`false`
`verification_method`	string	No	Channel used to deliver the OTP (`whatsapp`, `sms`, …). Reads from the last send attempt’s `actual_channel` (falls back to the requested `channel`, then `sms`).	`"whatsapp"`
`verification_attempts`	integer	No	Total OTP send attempts (initial send plus resends).	`1`
`verified_at`	string (ISO 8601)	Yes	Timestamp the OTP was successfully entered.	`"2026-05-17T10:14:02Z"`
`lifecycle`	array of objects	No	Chronological events: send attempts, delivery callbacks, code checks, and the final status event. Each event is `{ type, timestamp, details, fee }`. Event types come from `PhoneEventChoices`.	`[…]`
`matches`	array of objects	No	Cross-session phone-number matches. Each item: `{ session_id, session_number, vendor_data, verification_date, phone_number, status, is_blocklisted, api_service, source }`. `source` is `session` or `list_entry`.	`[]`
`node_id`	string \| null	Yes	Workflow node identifier (V3).	`"first_phone"`
`warnings`	array	No	See Warning object.	`[]`

{
  "status": "Approved",
  "phone_number_prefix": "+34",
  "phone_number": "612345678",
  "full_number": "+34612345678",
  "country_code": "ES",
  "country_name": "Spain",
  "carrier": { "name": "Movistar", "type": "mobile" },
  "is_disposable": false,
  "is_virtual": false,
  "verification_method": "whatsapp",
  "verification_attempts": 1,
  "verified_at": "2026-05-17T10:14:02Z",
  "lifecycle": [
    {
      "type": "PHONE_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2026-05-17T10:13:51Z",
      "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "whatsapp" },
      "fee": 0.04
    },
    {
      "type": "PHONE_DELIVERY_DELIVERED",
      "timestamp": "2026-05-17T10:13:52Z",
      "details": { "channel": "whatsapp", "status": "delivered" },
      "fee": 0
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2026-05-17T10:14:02Z",
      "details": { "code_tried": "482917", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "PHONE_VERIFICATION_APPROVED",
      "timestamp": "2026-05-17T10:14:02Z",
      "details": null,
      "fee": 0
    }
  ],
  "matches": [],
  "node_id": "first_phone",
  "warnings": []
}

Email verification

Returned per email-verification attempt. Appears as email_verifications[] in GET /v3/session/{sessionId}/decision/ for both KYC and KYB sessions. Source: email_verification/serializers/email.py:149-164 (EmailV3Serializer, extends EmailV2Serializer at email_verification/serializers/email.py:38-146).

Field	Type	Nullable	Description	Example
`status`	string	No	See Status enum.	`"Approved"`
`email`	string	No	The submitted email address.	`"maria.garcia@example.com"`
`is_breached`	boolean	No	`true` when the email appears in a known data breach.	`false`
`breaches`	array of objects	No	Per-breach detail when `is_breached` is `true`: `{ name, domain, logo_path, breach_date, description, is_verified, data_classes, breach_emails_count }`.	`[]`
`is_disposable`	boolean	No	`true` when the email belongs to a disposable-mail provider.	`false`
`is_undeliverable`	boolean	No	`true` when SMTP delivery probing shows the inbox doesn’t accept mail.	`false`
`verification_attempts`	integer	No	Total OTP check attempts.	`1`
`verified_at`	string (ISO 8601)	Yes	Timestamp the OTP was successfully entered.	`"2026-05-17T10:15:22Z"`
`lifecycle`	array of objects	No	Chronological events: send attempts, code checks, and the final status event. Each event is `{ type, timestamp, details, fee }`. Event types come from `EmailEventChoices`.	`[…]`
`matches`	array of objects	No	Cross-session email matches. Each item: `{ session_id, session_number, vendor_data, verification_date, email, status, is_blocklisted, api_service, source }`. `source` is `session` or `list_entry`.	`[]`
`node_id`	string \| null	Yes	Workflow node identifier (V3).	`"first_email"`
`warnings`	array	No	See Warning object.	`[]`

{
  "status": "Approved",
  "email": "maria.garcia@example.com",
  "is_breached": false,
  "breaches": [],
  "is_disposable": false,
  "is_undeliverable": false,
  "verification_attempts": 1,
  "verified_at": "2026-05-17T10:15:22Z",
  "lifecycle": [
    {
      "type": "EMAIL_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2026-05-17T10:15:11Z",
      "details": { "status": "Success", "reason": null },
      "fee": 0.03
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2026-05-17T10:15:22Z",
      "details": { "code_tried": "739204", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "EMAIL_VERIFICATION_APPROVED",
      "timestamp": "2026-05-17T10:15:22Z",
      "details": null,
      "fee": 0
    }
  ],
  "matches": [],
  "node_id": "first_email",
  "warnings": []
}

Database validation

Returned per database lookup run against the user’s submitted data. Appears as database_validations[] in GET /v3/session/{sessionId}/decision/. Source: database_validation/serializers/database_validation.py:21-142 (DatabaseValidationV3Serializer, extends DatabaseValidationV2Serializer).

Field	Type	Nullable	Description	Example
`issuing_state`	string (ISO 3166-1 alpha-3)	Yes	Country whose registry was queried.	`"ESP"`
`validation_type`	string (enum)	No	How the result was corroborated: `one_by_one` (single-service outcome), `two_by_two` (two or more distinct services independently full-matched the identification number), or `not_enabled` (the validator was skipped or no provider responded — a definitive `no_match` still yields `one_by_one`). Never `null`. Source: `DatabaseValidationChoices` (`common/config/choices.py:1097-1100`).	`"one_by_one"`
`screened_data`	object	No	The data submitted to the registry. File fields (`selfie`, `cnh_qr_code_image`, `document_image`) are presigned at read time.	`{ "document_number": "99999999R", "date_of_birth": "1990-05-12" }`
`validations`	array of objects	No	One entry per catalog service that produced a match. Each entry can include `service_id`, `service_name`, `validation` (provider verdict object), `outcome_code`, `outcome_detail`, and `source_data` (cleaned citizen profile: `full_name`, `gender`, `date_of_birth`, `photo` (presigned URL), `signature` (presigned URL), …).	`[…]`
`errors`	array of objects	Yes	Per-service errors when a lookup failed; the key is omitted entirely when empty. Each entry is the upstream service’s error object plus the `service_id` that produced it.	`[]`
`match_type`	string (enum)	Yes	Aggregate match verdict across queried services: `full_match`, `partial_match`, or `no_match` (`DatabaseValidationMatchTypeChoices`, `common/config/choices.py:1103-1106`). `null` until evaluated.	`"full_match"`
`status`	string	No	See Status enum.	`"Approved"`
`node_id`	string \| null	Yes	Workflow node identifier (V3).	`"first_db_validation"`
`warnings`	array	No	See Warning object.	`[]`

{
  "issuing_state": "ESP",
  "validation_type": "one_by_one",
  "screened_data": {
    "document_number": "99999999R",
    "date_of_birth": "1990-05-12",
    "first_name": "María",
    "last_name": "García López"
  },
  "validations": [
    {
      "service_id": "esp_dni",
      "service_name": "Spain - DNI/NIE verification",
      "validation": { "is_valid": true, "match_score": 100 },
      "outcome_code": "MATCH",
      "outcome_detail": "All identifiers match the registry record.",
      "source_data": {
        "full_name": "María García López",
        "gender": "F",
        "date_of_birth": "1990-05-12",
        "photo": "https://<media-host>/.../registry_photo.jpg?signature=...",
        "signature": null
      }
    }
  ],
  "match_type": "full_match",
  "status": "Approved",
  "node_id": "first_db_validation",
  "warnings": []
}

Questionnaire response

Returned per questionnaire submission. Appears as questionnaire_responses[] in GET /v3/session/{sessionId}/decision/ for both KYC and KYB sessions. Source: questionnaires/serializers/questionnaire.py:591-597 (QuestionnaireResponseV3Serializer, extends QuestionnaireResponseSerializer at questionnaires/serializers/questionnaire.py:520-588).

Field	Type	Nullable	Description	Example
`questionnaire_id`	string (UUID)	No	Identifier of the questionnaire version that was answered.	`"6a0f1c2c-…"`
`title`	string	No	Questionnaire name, as set in the Console.	`"Customer risk profile"`
`description`	string	Yes	Questionnaire description.	`"Short risk-profile questions."`
`languages`	array of strings	No	Language codes the questionnaire is published in.	`["en", "es"]`
`default_language`	string	No	Fallback language code.	`"en"`
`is_active`	boolean	No	Whether this questionnaire version is the active one.	`true`
`is_simple_questionnaire`	boolean	No	`true` when the questionnaire has no branching (flat list).	`true`
`questionnaire_group_id`	string (UUID)	No	Identifier shared across versions of the same questionnaire.	`"a7c2c2c2-…"`
`version`	integer	No	Version number of the active template.	`3`
`status`	string	No	One of `Approved`, `In Review`, `Not Finished` (a questionnaire-level decline maps to `In Review`).	`"Approved"`
`published_at`	string (ISO 8601)	Yes	When the template was published.	`"2026-01-12T11:00:00Z"`
`sections`	array of objects	No	Ordered sections after applying graph traversal and visibility filtering. Each section is `{ title, description, items[] }` (title/description come from the opening `SECTION_HEADER`, pre-translated). Each item is a form element (`uuid`, `value` (node id), `element_type`, `is_required`, `title`, `description`, `placeholder`, `choices`, `max_files`, `required_if`, `repeatable_config`, plus an `answer` field — `null` when unanswered, omitted on `HEADING`/`PARAGRAPH`/`SEPARATOR` layout items). File answers contain `{ files: [<presigned URL>, …] }`.	`[…]`
`node_id`	string \| null	Yes	Workflow node identifier (V3).	`"first_questionnaire"`

{
  "questionnaire_id": "6a0f1c2c-3b7d-4d2c-9eb6-fdc6c7c92ef9",
  "title": "Customer risk profile",
  "description": "Short risk-profile questions.",
  "languages": ["en", "es"],
  "default_language": "en",
  "is_active": true,
  "is_simple_questionnaire": true,
  "questionnaire_group_id": "a7c2c2c2-1111-4d2c-9eb6-fdc6c7c92ef9",
  "version": 3,
  "status": "Approved",
  "published_at": "2026-01-12T11:00:00Z",
  "sections": [
    {
      "title": "Source of funds",
      "description": null,
      "items": [
        {
          "uuid": "4f1d5e2c-aaaa-4d2c-9eb6-fdc6c7c92ef9",
          "value": "q_source_of_funds",
          "element_type": "SINGLE_CHOICE",
          "is_required": true,
          "title": "What is your main source of funds?",
          "description": null,
          "placeholder": null,
          "choices": [
            { "label": "Salary", "value": "salary" },
            { "label": "Business income", "value": "business" },
            { "label": "Investments", "value": "investments" }
          ],
          "max_files": 1,
          "required_if": null,
          "repeatable_config": null,
          "answer": { "value": "salary" }
        }
      ]
    }
  ],
  "node_id": "first_questionnaire"
}

Age estimation

Returned by the standalone Age Estimation API (POST /v3/age-estimation/). The response carries a subset of Liveness check’s shape under an age_estimation envelope — status, method, score, age_estimation, warnings — plus a standalone-only user_image face-detection block; it does not include reference_image, video_url, matches, face_quality, or face_luminance. In workflow sessions there is no separate array — the estimated age surfaces as liveness_checks[].age_estimation in GET /v3/session/{sessionId}/decision/. Source: apis/serializers/age_estimation.py:50-55 (AgeEstimationResponseSerializer), envelope assembled in apis/views/age_estimation.py:138-174.

Field	Type	Nullable	Description	Example
`request_id`	string (UUID)	No	Persisted session id when `save_api_request=true` (the default); otherwise a transient correlation UUID.	`"3b1f1e2c-…"`
`age_estimation`	object	No	Result envelope: `status` (`Approved` / `Declined`), `method` (always `PASSIVE`), `score` (liveness 0-100, nullable), `age_estimation` (predicted age in years of the largest face, nullable), `user_image` (`entities[]` with per-face `age`, `bbox` `[x_min, y_min, x_max, y_max]`, `confidence`, `gender`; plus `best_angle`), `warnings[]`.	`{ … }`
`vendor_data`	string	Yes	Echoed `vendor_data` from the request.	`null`
`metadata`	object	Yes	Echoed `metadata` from the request.	`null`
`created_at`	string (ISO 8601)	No	Server-side request timestamp.	`"2026-05-17T10:22:13.512941+00:00"`

{
  "request_id": "3b1f1e2c-7777-4d2c-9eb6-fdc6c7c92ef9",
  "age_estimation": {
    "status": "Approved",
    "method": "PASSIVE",
    "score": 94.10,
    "age_estimation": 28.7,
    "user_image": {
      "entities": [
        { "age": 28.7, "bbox": [40, 40, 100, 100], "confidence": 0.72, "gender": "male" }
      ],
      "best_angle": 0
    },
    "warnings": []
  },
  "vendor_data": null,
  "metadata": null,
  "created_at": "2026-05-17T10:22:13.512941+00:00"
}

Biometric authentication

Biometric authentication runs the same Liveness + Face Match pipeline used in standard KYC, but configured to compare the captured face against an existing user’s reference image instead of a freshly-OCR’d document portrait. There is no dedicated serializer — GET /v3/session/{sessionId}/decision/ returns the standard Liveness check and Face match objects under liveness_checks[] and face_matches[]. The session’s workflow is configured with workflow_type = "biometric_authentication" (WorkflowTypeChoices, common/config/choices.py:636).

Field	Type	Nullable	Description	Example
`liveness_checks`	array of Liveness check	No	Liveness result for the authentication attempt.	`[ { "status": "Approved", … } ]`
`face_matches`	array of Face match	No	Match result against the enrolled reference. `source_image_session_id` is set to the session’s own `session_id` — the reference face (the supplied `portrait_image`, or the stored face reused via `vendor_data` when `portrait_image` is omitted) is recorded under the authentication session itself (`face/views/face.py:656-659`).	`[ { "status": "Approved", "source_image_session_id": "…", … } ]`
`status`	string	No	Top-level session status (see Status enum).	`"Approved"`

{
  "session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9",
  "status": "Approved",
  "liveness_checks": [
    {
      "status": "Approved",
      "method": "PASSIVE",
      "score": 95.10,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": null,
      "age_estimation": null,
      "matches": [],
      "face_quality": 91.20,
      "face_luminance": 53.10,
      "node_id": "biometric_auth_liveness",
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "status": "Approved",
      "score": 98.42,
      "source_image_session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9",
      "source_image": "https://<media-host>/.../source.jpg?signature=...",
      "target_image": "https://<media-host>/.../target.jpg?signature=...",
      "node_id": "biometric_auth_face_match",
      "warnings": []
    }
  ]
}

KYB registry

Returned per registry-confirmed company in a KYB workflow. Appears as registry_checks[] in GET /v3/session/{sessionId}/decision/ for business sessions. Source: kyb/serializers/kyb.py:939-964 (RegistryCheckV3Serializer).

Field	Type	Nullable	Description	Example
`status`	string	No	See Status enum.	`"Approved"`
`node_id`	string \| null	Yes	Workflow node identifier (V3).	`"first_registry"`
`data_resolved`	boolean	No	`true` when the registry fetch has completed (or `is_from_registry` is `false`, meaning the data was entered manually).	`true`
`company`	object	No	Full company payload — see Company object below.	`{ … }`
`ownership_structure`	object	Yes	Provider-supplied ownership graph (`nodes`, `edges`, percentages). Free-form JSON.	`{ "nodes": [...], "edges": [...] }`
`warnings`	array	No	See Warning object.	`[]`

Company object

From kyb/serializers/kyb.py:220-321 (KYBCompanyResponseSerializer).

Field	Type	Nullable	Description
`uuid`	string (UUID)	No	Internal company identifier.
`node_id`	string \| null	Yes	Workflow node identifier.
`status`	string	No	Feature status (`FeatureStatusChoices`).
`registry_status`	string	Yes	Company status from the registry (`active`, `dissolved`, …).
`data_resolved`	boolean	No	Same definition as on the parent object.
`company_name`	string	Yes	Registered company name.
`registration_number`	string	Yes	Registry identifier.
`country_code`	string (ISO 3166-1 alpha-2)	Yes	Country of incorporation.
`region`	string	Yes	ISO 3166-2 subdivision when applicable (e.g. `US-CA`).
`company_type`	string	Yes	Legal form (`LLC`, `SL`, …).
`incorporation_date`	string (YYYY-MM-DD)	Yes	Date of incorporation.
`registered_address`	string	Yes	Registered legal address.
`tax_number`	string	Yes	Tax / VAT identifier.
`risk_level`	string	Yes	Provider-supplied risk rating.
`verification_status`	string	Yes	Internal verification status enum.
`is_from_registry`	boolean	No	`true` when sourced from the registry (vs. manual entry).
`fetch_status`	string	Yes	`pending`, `resolved`, `failed`.
`alternative_names`	string	Yes	Comma-separated alternative trade names.
`nature_of_business`	string	Yes	Free-text business activity description.
`registered_capital`	string	Yes	Registered capital as a human-readable string.
`registered_capital_amount`	string (decimal)	Yes	Parsed registered capital amount.
`registered_capital_currency`	string (ISO 4217)	Yes	Currency code.
`website`	string (URL)	Yes	Company website.
`email`	string	Yes	Public contact email.
`phone`	string	Yes	Public contact phone.
`legal_entity_identifier`	string	Yes	LEI when available.
`location_of_registration`	string	Yes	Registry office / region.
`vat_number`	string	Yes	VAT number submitted for the company.
`vat_validation_status`	string	No	Result of the EU VIES check: `valid`, `invalid`, `could_not_validate`, or `not_applicable`. Only EU-27 + Northern Ireland (`XI`) VAT numbers are validated; everything else returns `not_applicable`. See VAT validation.
`vat_validated_name`	string	Yes	Company name registered in VIES (empty when the member state does not disclose it).
`vat_validated_address`	string	Yes	Address registered in VIES (empty when not disclosed).
`vat_checked_at`	string (ISO 8601)	Yes	Timestamp of the VIES check; `null` when no check ran.
`financial_summary`	object	Yes	Snapshot of latest financial highlights when supplied by the registry.
`officers`	array of objects	No	B2C-safe officer list: `{ uuid, name, designation, role, nationality, is_active, kyc_status, kyc_session_url }`.
`beneficial_owners`	array of objects	No	B2C-safe UBO list: `{ uuid, name, first_name, last_name, entity_type, roles, ownership_min_shares, ownership_max_shares, is_active, kyc_status, kyc_session_url, effective_ownership_percent }`.
`addresses`	array of objects	Yes	Per-address detail from the registry.
`industries`	array of objects	Yes	SIC/NAICS-style classifications.
`accounts`	array of objects	Yes	Filed accounts metadata.
`registry_data`	object	Yes	Raw registry payload (vendor-specific).
`user_provided_data`	object	Yes	Snapshot of user-edited fields.
`confirmed_by_user_at`	string (ISO 8601)	Yes	Timestamp the user confirmed the extracted data.
`last_console_edit_at`	string (ISO 8601)	Yes	Timestamp of the last console edit.
`is_editable`	boolean	No	`true` while registry-sourced data can still be edited by the end user.

{
  "status": "Approved",
  "node_id": "first_registry",
  "data_resolved": true,
  "company": {
    "uuid": "b1f1e2c2-9999-4d2c-9eb6-fdc6c7c92ef9",
    "node_id": "first_registry",
    "status": "Approved",
    "registry_status": "active",
    "data_resolved": true,
    "company_name": "Sante Clinics SL",
    "registration_number": "B12345678",
    "country_code": "ES",
    "region": null,
    "company_type": "SL",
    "incorporation_date": "2018-03-22",
    "registered_address": "Calle Mayor 1, 28001 Madrid, Spain",
    "tax_number": "B12345678",
    "risk_level": "low",
    "verification_status": "verified",
    "is_from_registry": true,
    "fetch_status": "resolved",
    "alternative_names": "Sante Clinics",
    "nature_of_business": "Medical clinic operations",
    "registered_capital": "EUR 50,000",
    "registered_capital_amount": "50000.00",
    "registered_capital_currency": "EUR",
    "website": "https://santeclinics.com",
    "email": "info@santeclinics.com",
    "phone": "+34911223344",
    "legal_entity_identifier": null,
    "location_of_registration": "Registro Mercantil de Madrid",
    "vat_number": "ESB12345678",
    "vat_validation_status": "valid",
    "vat_validated_name": "SANTE CLINICS SL",
    "vat_validated_address": "CALLE MAYOR 1, 28001 MADRID",
    "vat_checked_at": "2026-05-17T10:11:05Z",
    "financial_summary": null,
    "officers": [
      {
        "uuid": "c1f1e2c2-aaaa-4d2c-9eb6-fdc6c7c92ef9",
        "name": "María García López",
        "designation": "Administrador único",
        "role": "Director",
        "nationality": "ESP",
        "is_active": true,
        "kyc_status": "Approved",
        "kyc_session_url": "https://verify.didit.me/s/…"
      }
    ],
    "beneficial_owners": [
      {
        "uuid": "d1f1e2c2-bbbb-4d2c-9eb6-fdc6c7c92ef9",
        "name": "María García López",
        "first_name": "María",
        "last_name": "García López",
        "entity_type": "person",
        "roles": ["UBO"],
        "ownership_min_shares": "75.00",
        "ownership_max_shares": "75.00",
        "is_active": true,
        "kyc_status": "Approved",
        "kyc_session_url": "https://verify.didit.me/s/…",
        "effective_ownership_percent": 75.0
      }
    ],
    "addresses": [],
    "industries": [],
    "accounts": [],
    "registry_data": {},
    "user_provided_data": {},
    "confirmed_by_user_at": "2026-05-17T10:11:02Z",
    "last_console_edit_at": null,
    "is_editable": false
  },
  "ownership_structure": null,
  "warnings": []
}

KYB document

Returned per node that collects KYB supporting documents. Appears as document_verifications[] in GET /v3/session/{sessionId}/decision/ for business sessions — one entry per node_id, with items[] listing each uploaded document. Source: kyb/serializers/kyb.py:1053-1068 (DocumentVerificationV3Serializer); each item follows kyb/serializers/kyb.py:811-851 (KYBDocumentResponseSerializer).

Field	Type	Nullable	Description	Example
`status`	string	No	Aggregate status across this node’s documents: `Approved` only when every pipeline document is approved; `Declined` if any is declined; `In Review` otherwise; `Not Finished` while pending. See Status enum.	`"Approved"`
`node_id`	string \| null	Yes	Workflow node identifier (V3).	`"first_kyb_documents"`
`items`	array of KYB document item objects	No	One entry per uploaded or requested document.	`[…]`
`groups`	object	No	Per-document-group counts: `{ <group_name>: { total, approved, pending, declined, in_review, other, missing } }`.	`{ "incorporation_certificate": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 } }`
`required_groups`	array of strings	No	Document groups required by the workflow configuration.	`["incorporation_certificate", "shareholder_register"]`
`warnings`	array	No	See Warning object.	`[]`

KYB document item object

Field	Type	Nullable	Description
`uuid`	string (UUID)	No	Internal document identifier.
`document_type`	string	Yes	High-level group (`incorporation_certificate`, `shareholder_register`, …).
`document_subtype`	string	Yes	Provider-specific subtype.
`document_group`	string	Yes	Mirror of `document_type` (alias kept for clarity).
`file_url`	string (URL)	Yes	Presigned URL to the cleaned file.
`original_filename`	string	Yes	Filename as uploaded.
`file_size`	integer	Yes	File size in bytes.
`status`	string	No	Per-document status (`FeatureStatusChoices`).
`created_at`	string (ISO 8601)	No	Upload timestamp.
`cross_check_result`	object	Yes	Cross-check verdict against registry / other docs.
`document_metadata`	object	Yes	Same filtered metadata shape as POA’s `document_metadata`.
`description`	string	Yes	Reviewer- or system-supplied description.
`is_requested`	boolean	No	`true` when the workflow expected this document.
`ocr_data`	object	Yes	OCR-extracted fields when available.
`is_console_upload`	boolean	No	`true` when the document was uploaded by a console reviewer (excluded from the aggregate verdict).
`is_confirmed`	boolean	No	`true` when the reviewer has explicitly confirmed the document.

{
  "status": "Approved",
  "node_id": "first_kyb_documents",
  "items": [
    {
      "uuid": "e1f1e2c2-cccc-4d2c-9eb6-fdc6c7c92ef9",
      "document_type": "incorporation_certificate",
      "document_subtype": "registro_mercantil_extract",
      "document_group": "incorporation_certificate",
      "file_url": "https://<media-host>/.../incorporation.pdf?signature=...",
      "original_filename": "incorporation_certificate.pdf",
      "file_size": 256412,
      "status": "Approved",
      "created_at": "2026-05-17T10:08:00Z",
      "cross_check_result": { "matches_registry_name": true, "matches_registration_number": true },
      "document_metadata": {
        "file_size": 256412,
        "content_type": "application/pdf",
        "is_signed": true,
        "is_tampered": false
      },
      "description": null,
      "is_requested": true,
      "ocr_data": { "company_name": "Sante Clinics SL", "registration_number": "B12345678" },
      "is_console_upload": false,
      "is_confirmed": true
    }
  ],
  "groups": {
    "incorporation_certificate": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 }
  },
  "required_groups": ["incorporation_certificate", "shareholder_register"],
  "warnings": []
}

KYB key person

Returned per Key People node in a KYB workflow. Appears as key_people_checks[] in GET /v3/session/{sessionId}/decision/ for business sessions. Source: kyb/serializers/kyb.py:967-1050 (KeyPeopleCheckV3Serializer).

Field	Type	Nullable	Description	Example
`status`	string	No	See Status enum.	`"Approved"`
`node_id`	string \| null	Yes	Workflow node identifier (V3).	`"first_key_people"`
`registry`	object	No	`{ officers[], beneficial_owners[] }` extracted from the registry. Officers follow `KYBPersonResponseSerializer` (`kyb/serializers/kyb.py:533-645`); beneficial owners follow `KYBBeneficialOwnerResponseSerializer` (`kyb/serializers/kyb.py:648-788`, which adds `date_of_birth`, `country_of_birth`, `email`, `company_name`, `registration_number`, `entity_type`, `roles`, `ownership_min_shares`, `ownership_max_shares`, `child_beneficial_owners`, `effective_ownership_percent`). Both include per-party AML + KYC enrichment (`aml_status`, `kyc_status`, `kyc_session_url`, `kyc_session_id`, `verification_workflow_type`, `verification_workflow_id`, `verification_workflow_label`, `verification_workflow_features`, `didit_internal_id`, `kyc_document_type`, `kyc_nationality`, `kyc_liveness_passed`, `kyc_verified_at`, `kyc_aml_categories`, `kyc_notification_sent_at`).	`{ "officers": [...], "beneficial_owners": [...] }`
`submitted`	object	No	`{ parties[] }` - entries the business confirmed / submitted via the key-people flow (`BusinessParty` rows with `source=USER`). Each party follows `BusinessPartySubmissionResponseSerializer` (`kyb/serializers/party.py:146-194`): `uuid`, `entity_type`, `source`, `name`, `first_name`, `last_name`, `company_name`, `registration_number`, `email`, `nationality`, `phone_number`, `date_of_birth`, `position`, `custom_fields`, `is_active`, `is_skipped`, `requires_verification`, `roles[]` (`{ role, ownership_percent, voting_percent }`), `kyc_session_id`, `kyc_session_status`, `kyc_session_url`, `kyc_session_deleted`, `kyb_sub_session_id`, `kyb_sub_session_status`, `kyb_sub_session_url`, `kyb_sub_session_deleted`, `verification_workflow_type`, `verification_workflow_id`, `verification_workflow_label`, `verification_workflow_features`, `didit_internal_id`. `kyc_session_deleted` / `kyb_sub_session_deleted` mark a child session that was deleted: its status stays frozen at whatever it was, the matching `*_session_url` comes back `null` because the link no longer resolves, and the party stops blocking the parent (the check drops to `In Review` instead). Clear it with `PATCH /v3/session/{id}/kyb/parties/{party_uuid}/`.	`{ "parties": [...] }`
`ubo_kyc_summary`	object	Yes	Counts across active UBOs with linked KYC: `{ total, approved, flagged, pending }`. `null` when no active UBOs have KYC linked.	`{ "total": 2, "approved": 2, "flagged": 0, "pending": 0 }`
`warnings`	array	No	See Warning object.	`[]`

{
  "status": "Approved",
  "node_id": "first_key_people",
  "registry": {
    "officers": [
      {
        "uuid": "c1f1e2c2-aaaa-4d2c-9eb6-fdc6c7c92ef9",
        "name": "María García López",
        "designation": "Administrador único",
        "role": "Director",
        "nationality": "ESP",
        "appointment_date": "2018-03-22",
        "termination_date": null,
        "is_active": true,
        "address": "Calle Mayor 1, 28001 Madrid",
        "aml_status": "Approved",
        "kyc_status": "Approved",
        "kyc_session_url": "https://verify.didit.me/s/…",
        "kyc_session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9",
        "verification_workflow_type": "kyc",
        "verification_workflow_id": "11111111-1111-1111-1111-111111111111",
        "verification_workflow_label": "KYB officer KYC",
        "verification_workflow_features": [
          { "feature": "ID_VERIFICATION", "status": "Approved" },
          { "feature": "LIVENESS", "status": "Approved" },
          { "feature": "FACE_MATCH", "status": "Approved" }
        ],
        "didit_internal_id": "user-12345",
        "kyc_document_type": "Passport",
        "kyc_nationality": "ESP",
        "kyc_liveness_passed": true,
        "kyc_verified_at": "2026-05-17T10:10:11Z",
        "kyc_aml_categories": [],
        "kyc_notification_sent_at": "2026-05-15T08:00:00Z"
      }
    ],
    "beneficial_owners": []
  },
  "submitted": {
    "parties": [
      {
        "uuid": "d1f1e2c2-bbbb-4d2c-9eb6-fdc6c7c92ef9",
        "entity_type": "person",
        "source": "USER",
        "name": "María García López",
        "first_name": "María",
        "last_name": "García López",
        "company_name": null,
        "registration_number": null,
        "email": "maria.garcia@example.com",
        "nationality": "ESP",
        "phone_number": null,
        "date_of_birth": "1990-05-12",
        "position": "Administrador único",
        "custom_fields": {},
        "is_active": true,
        "is_skipped": false,
        "requires_verification": true,
        "roles": [
          { "role": "UBO", "ownership_percent": 75.0, "voting_percent": null }
        ],
        "kyc_session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9",
        "kyc_session_status": "Approved",
        "kyc_session_url": "https://verify.didit.me/s/…",
        "kyb_sub_session_id": null,
        "kyb_sub_session_status": null,
        "kyb_sub_session_url": null,
        "verification_workflow_type": "kyc",
        "verification_workflow_id": "11111111-1111-1111-1111-111111111111",
        "verification_workflow_label": "KYB officer KYC",
        "verification_workflow_features": [
          { "feature": "ID_VERIFICATION", "status": "Approved" },
          { "feature": "LIVENESS", "status": "Approved" }
        ],
        "didit_internal_id": "user-12345"
      }
    ]
  },
  "ubo_kyc_summary": { "total": 1, "approved": 1, "flagged": 0, "pending": 0 },
  "warnings": []
}

Status enum reference

Two related value spaces share the status field name. Every per-feature report object on this page uses the feature-level enum; the parent session’s top-level status uses the wider session enum.

Feature-level statuses

Used by every report object’s status field. Source: common/config/choices.py:343-348 (FeatureStatusChoices).

Value	Meaning
`Not Finished`	The feature has been provisioned but the user has not completed it yet.
`Approved`	The feature passed all checks.
`Declined`	The feature failed at least one hard check (see `warnings[]` with `log_type: "error"`).
`In Review`	The feature triggered soft-fail signals and is awaiting manual review (see `warnings[]` with `log_type: "warning"`).
`Resub Requested`	A reviewer requested the user resubmit this feature.

Phone, email, and ID verification can additionally surface Expired when their step times out (PhoneStatusChoices at common/config/choices.py:377-382, EmailStatusChoices at common/config/choices.py:434-439).

Session-level statuses

Used by the parent session’s top-level status. Source: common/config/choices.py:106-117 (StatusChoices).

Value	Meaning
`Not Started`	The session has been created but the user has not begun it.
`In Progress`	The user has started the flow; result not yet finalized.
`Approved`	The session passed all checks.
`Declined`	The session failed at least one hard check.
`In Review`	The session is awaiting manual review.
`Expired`	The session expired before completion.
`Abandoned`	The user left the flow without completing it.
`Kyc Expired`	The KYC’s validity window elapsed (used in re-verification flows).
`Resubmitted`	The user resubmitted after a prior decline; this session is superseded by a newer one.
`Awaiting User`	The system is waiting on a user-side action (e.g. OTP entry).

Terminal session values are Approved, Declined, In Review, Expired, Kyc Expired, and Abandoned. A session can reach its overall decision while an individual feature stays In Review.

Overview

Pricing

Workflows & Verification

Review & Operations

Entities (Users & Businesses)

Settings & Customization

Security & Compliance

Didit Academy

Resources

Overview

Common fields

Warning object

Report objects

ID verification

NFC verification

Liveness check

Face match

Face search

Face-search match object

AML screening

IP analysis

Proof of address

Phone verification

Email verification

Database validation

Questionnaire response

Age estimation

Biometric authentication

KYB registry

Company object

KYB document

KYB document item object

KYB key person

Status enum reference

Feature-level statuses

Session-level statuses

​Overview

​Common fields

​Warning object

​Report objects

​ID verification

​NFC verification

​Liveness check

​Face match

​Face search

​Face-search match object

​AML screening

​IP analysis

​Proof of address

​Phone verification

​Email verification

​Database validation

​Questionnaire response

​Age estimation

​Biometric authentication

​KYB registry

​Company object

​KYB document

​KYB document item object

​KYB key person

​Status enum reference

​Feature-level statuses

​Session-level statuses

Overview

Common fields

Warning object

Report objects

ID verification

NFC verification

Liveness check

Face match

Face search

Face-search match object

AML screening

IP analysis

Proof of address

Phone verification

Email verification

Database validation

Questionnaire response

Age estimation

Biometric authentication

KYB registry

Company object

KYB document

KYB document item object

KYB key person

Status enum reference

Feature-level statuses

Session-level statuses