Overview
Warnings on the ID verification report flag every condition Didit observed while reading and validating the document. They land in the warnings[] array on each item of id_verifications[] (see ID verification report), with the shape described in Data models — Warning object: feature, risk, additional_data, log_type, short_description, long_description, node_id.
Every warning has three layers:
- The
risk code — a stable identifier you can match on in your code.
- The
log_type — derived from the action your configuration assigns to the risk at evaluation time: Decline → error, Review → warning, anything else → information.
- The decision impact — set by the workflow’s configurable risk groups. The same
risk code can be routed to Approve, Review, or Decline depending on how your application is configured.
Auto-decline conditions
In workflows, the following risks always force the ID report (and the session) to Declined. They cannot be configured:
| Risk | Trigger |
|---|
DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION | The submitted document type is not on your application’s allowed-documents list. additional_data includes issuing_state, document_type, document_subtype, document_region, and document_region_with_subtype so you can enable the exact document in your workflow. |
DOCUMENT_EXPIRED | The document’s expiration date has passed at capture time. |
PORTRAIT_IMAGE_NOT_DETECTED | No portrait image could be located on the document. |
ID_DOCUMENT_IN_BLOCKLIST | The document matches an entry on your application’s blocklist. |
AGE_BELOW_MINIMUM | Adaptive age-verification workflows only: extracted age is below the minimum. |
AGE_NOT_DETECTED | Adaptive age-verification workflows only: age could not be extracted from the document. |
DOCUMENT_EXPIRED, MINIMUM_AGE_NOT_MET, PORTRAIT_IMAGE_NOT_DETECTED, SCREEN_CAPTURE_DETECTED, PRINTED_COPY_DETECTED, and PORTRAIT_MANIPULATION_DETECTED. In workflows, minimum age is configurable (default Decline) and the three document-liveness risks are threshold-driven (see below).
Configurable verification settings
In the Didit console, the remaining ID risks are grouped into settings you can route to Approve, Review, or Decline (per workflow, and per node in graph workflows):
| Group | Risks | Default action |
|---|
| Minimum Age | MINIMUM_AGE_NOT_MET | Decline |
| Maximum Age | MAXIMUM_AGE_EXCEEDED | Decline |
| Duplicated User | POSSIBLE_DUPLICATED_USER (skipped when the document number is in your document allowlist) | Approve (information) |
| Invalid Code | QR_NOT_DETECTED, BARCODE_NOT_DETECTED, QR_VALIDATION_FAILED, BARCODE_VALIDATION_FAILED | Approve (information) |
| Invalid MRZ | MRZ_VALIDATION_FAILED, MRZ_NOT_DETECTED | Approve (information) |
| Data Inconsistency | DATA_INCONSISTENT, MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME, DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS, DOCUMENT_SIDES_MISMATCH, ID_VERIFICATION_DATA_MISMATCH_BETWEEN_DOCUMENTS | Approve (information) |
| Invalid Validation | INVALID_DATE, COULD_NOT_RECOGNIZE_DOCUMENT, DOCUMENT_NUMBER_NOT_DETECTED, COULD_NOT_DETECT_DOCUMENT_TYPE, NAME_NOT_DETECTED, DATE_OF_BIRTH_NOT_DETECTED | Review |
| Expected Details Mismatch | FULL_NAME_MISMATCH_WITH_PROVIDED, GENDER_MISMATCH_WITH_PROVIDED, DOB_MISMATCH_WITH_PROVIDED, COUNTRY_MISMATCH_WITH_PROVIDED, NATIONALITY_MISMATCH_WITH_PROVIDED, IDENTIFICATION_NUMBER_MISMATCH_WITH_PROVIDED | Review |
| Expiration Date Not Detected | EXPIRATION_DATE_NOT_DETECTED | Approve (information) |
| Document or Personal Number Format Mismatch | DOCUMENT_NUMBER_FORMAT_MISMATCH, PERSONAL_NUMBER_FORMAT_MISMATCH (one shared action) | Approve (information) |
| Unparsed Address | UNPARSED_ADDRESS | Approve (information) |
| Image Quality | IMAGE_TOO_BLURRY, IMAGE_TOO_DARK, IMAGE_TOO_BRIGHT (one action per risk) | Approve (information) |
- Document liveness —
SCREEN_CAPTURE_DETECTED, PRINTED_COPY_DETECTED, PORTRAIT_MANIPULATION_DETECTED. Each fraud type has its own decline and review thresholds: score below the decline threshold → error + Declined; below the review threshold → warning + In Review; otherwise information.
- Cross-camera face match —
LOW_FRONT_CAMERA_FACE_MATCH_SIMILARITY, governed by document_selfie_portrait_match_decline_threshold / document_selfie_portrait_match_review_threshold.
Warnings produced
Verified against collect_ocr_logs, the document-capture flow, and process_ocr_logs_and_get_status. Short descriptions below are the exact short_description strings returned by the API.
Document recognition and quality
| Risk | Short description | Cause | Severity |
|---|
COULD_NOT_RECOGNIZE_DOCUMENT | Could not validate Document | The system could not confirm the authenticity or validity of the submitted document — often poor image quality or an unsupported document type. Also used as the fallback for unrecognized processing failures. | Configurable — Invalid Validation, default Review |
COULD_NOT_DETECT_DOCUMENT_TYPE | Could not detect document type | The OCR engine could not classify the document family (passport vs ID vs DL). When this fires, DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION is suppressed (the type is unknown, so “not supported” would be contradictory). | Configurable — Invalid Validation, default Review |
DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION | Document not supported for your application | The recognized document type is not on the application’s allowed list. additional_data carries the country, document type, subtype, and region-aware subtype. | error — auto-decline |
DOCUMENT_EXPIRED | Document expired | At capture time: the document’s expiration date is in the past (error, auto-decline). Post-approval: ongoing expiration monitoring appends this warning with log_type: "warning" when an approved document’s date passes, and the report status becomes Expired. | error at capture; warning from monitoring |
DOCUMENT_SIDES_MISMATCH | Document sides mismatch | Front and back images do not belong to the same document. | Configurable — Data Inconsistency, default information |
PORTRAIT_IMAGE_NOT_DETECTED | Portrait image not detected | No portrait could be located on a document that should have one (deferred when the user uploads the non-portrait side first). | error — auto-decline |
IMAGE_TOO_BLURRY / IMAGE_TOO_DARK / IMAGE_TOO_BRIGHT | Document image is too blurry / too dark / too bright | The image-quality gate rejected an upload (the user is asked to retake). additional_data carries the failing side. A successful retake clears the stale warning; the gate is skipped on the user’s final allowed attempt so they are never hard-blocked. | Configurable — per-risk Image Quality action, default information |
The capture flow can also reject an upload with the feedback codes IMAGE_RESOLUTION_TOO_LOW, DOCUMENT_NOT_FULLY_VISIBLE, and IMAGE_QUALITY_TOO_LOW. These prompt a retake in the SDK but are not persisted to the report’s warnings[] — only the blurry/dark/bright risks are.
| Risk | Short description | Cause | Severity |
|---|
NAME_NOT_DETECTED | First name and/or last name not detected | First name and last name could not be extracted. Exempt when the holder legitimately has a single name (one-name countries, or the MRZ itself carries a single name) and at least one name value was extracted. | Configurable — Invalid Validation, default Review |
DATE_OF_BIRTH_NOT_DETECTED | Date of birth not detected | Date of birth could not be extracted from a document that should have one. | Configurable — Invalid Validation, default Review |
DOCUMENT_NUMBER_NOT_DETECTED | Document number not detected | Neither the document number nor a personal number could be extracted. | Configurable — Invalid Validation, default Review |
EXPIRATION_DATE_NOT_DETECTED | Expiration date not detected | Expiration date could not be extracted from a document that should have one. | Configurable — Expiration Date Not Detected, default information |
INVALID_DATE | Invalid Date | A date on the document (date of birth or expiry) doesn’t parse to a valid date. In the current capture flow this surfaces as a retake prompt during upload rather than a stored warning; the code remains in the Invalid Validation routing group and may appear on older sessions. | Configurable — Invalid Validation, default Review |
DOCUMENT_NUMBER_FORMAT_MISMATCH | Document number format mismatch | Document number does not match the expected format configured for this document type. additional_data carries expected_format and extracted_value. | Configurable — Format Mismatch, default information |
PERSONAL_NUMBER_FORMAT_MISMATCH | Personal number format mismatch | Personal number does not match the expected format configured for this document type. | Configurable — Format Mismatch, default information |
MRZ, QR, barcode
All three MRZ risks are skipped for document types with known-unreliable MRZs.
| Risk | Short description | Cause | Severity |
|---|
MRZ_NOT_DETECTED | MRZ not detected | MRZ could not be located on a document that should have one. | Configurable — Invalid MRZ, default information |
MRZ_VALIDATION_FAILED | MRZ is not valid | MRZ failed checksum / format validation. Often a low-quality capture; can indicate tampering. | Configurable — Invalid MRZ, default information |
MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME | MRZ and data extracted from OCR have some discrepancies | MRZ contents disagree with the VIZ (visible-zone) OCR. Possible alteration. | Configurable — Data Inconsistency, default information |
QR_NOT_DETECTED | QR not detected | QR code could not be located on a document that should have one. | Configurable — Invalid Code, default information |
QR_VALIDATION_FAILED | QR validation failed | QR contents could not be validated against the rest of the document. | Configurable — Invalid Code, default information |
BARCODE_NOT_DETECTED | Barcode not detected | Barcode could not be located on a document that should have one. | Configurable — Invalid Code, default information |
BARCODE_VALIDATION_FAILED | Barcode validation failed | Barcode contents could not be validated against the rest of the document. | Configurable — Invalid Code, default information |
DATA_INCONSISTENT | OCR data in the document is not consistent | Data extracted from different parts of the document disagrees — typically the front and back sides of the same document. | Configurable — Data Inconsistency, default information |
Identity matching
| Risk | Short description | Cause | Severity |
|---|
ID_DOCUMENT_IN_BLOCKLIST | ID document in blocklist | The document matches a blocklisted document (same date of birth, issuing country, and exact document number) or a manually blocklisted document number. additional_data carries the blocklisted session reference. | error — auto-decline |
ID_DOCUMENT_IN_ALLOWLIST | ID document in allowlist | The document number matches your document allowlist, so the duplicate-user action was skipped. additional_data carries the document_number. | information |
POSSIBLE_DUPLICATED_USER | Possible duplicated user from other session | Another document in your application has the same date of birth, the same issuing country, and a highly similar full name — under a different user (vendor_data), regardless of that session’s status. additional_data carries the duplicate session reference. | Configurable — Duplicated User, default information |
DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS | Document name differs from other approved documents | Name on this document differs from previously approved documents for the same user. Only produced for Didit-protocol (UserKYC) accounts, not standard API sessions. | Configurable — Data Inconsistency, default information |
ID_VERIFICATION_DATA_MISMATCH_BETWEEN_DOCUMENTS | Data mismatch between ID verification documents | Two ID documents in the same session disagree on name / date of birth. | Configurable — Data Inconsistency, default information |
LOW_FRONT_CAMERA_FACE_MATCH_SIMILARITY | Selfie during document capture doesn’t match document portrait | The face captured from the user’s front camera during document capture does not match the portrait on the document well. | Threshold-driven: error below the decline threshold, warning at or below the review threshold |
Document liveness (tampering)
Threshold-driven per fraud type in workflows; unconditionally declining on the standalone OCR API.
| Risk | Short description | Cause | Severity |
|---|
SCREEN_CAPTURE_DETECTED | Screen capture of document detected | Document was captured from a screen rather than a physical document. | error below the decline threshold, warning below the review threshold, else information |
PRINTED_COPY_DETECTED | Printed copy of document detected | Document appears to be a printed copy rather than the original. | Same tri-bucket thresholds |
PORTRAIT_MANIPULATION_DETECTED | Portrait manipulation detected | The portrait region appears to have been replaced or altered. | Same tri-bucket thresholds |
Expected-details mismatches
When you pass expected_details to a session, Didit raises a mismatch warning per field that does not match. One grouping (expected_details_mismatch_action, default Review) controls routing for all of these:
| Risk | Short description | Cause |
|---|
FULL_NAME_MISMATCH_WITH_PROVIDED | Full name mismatch with provided information | Provided name scores below the name-match threshold against the document. |
DOB_MISMATCH_WITH_PROVIDED | Date of birth mismatch with provided information | Provided date of birth does not match. |
GENDER_MISMATCH_WITH_PROVIDED | Gender mismatch with provided information | Provided gender does not match. |
COUNTRY_MISMATCH_WITH_PROVIDED | Country mismatch with provided information | Provided country does not match issuing_state. |
NATIONALITY_MISMATCH_WITH_PROVIDED | Nationality mismatch with provided information | Provided nationality does not match. |
IDENTIFICATION_NUMBER_MISMATCH_WITH_PROVIDED | Identification number mismatch with provided information | Provided ID number does not match the document number, personal number, or tax number. |
additional_data.
Age
| Risk | Short description | Cause | Severity |
|---|
MINIMUM_AGE_NOT_MET | Minimum age not met | Holder is below the configured minimum age (global or per-country/state). additional_data carries min_age_allowed and user_age. | Configurable — Minimum Age, default Decline (error); unconditional decline on the standalone OCR API |
MAXIMUM_AGE_EXCEEDED | Maximum age exceeded | Holder is above the configured maximum age. additional_data carries max_age_allowed and user_age. | Configurable — Maximum Age, default Decline (error) |
AGE_NOT_DETECTED | Age not detected | Adaptive age-verification workflows: age could not be extracted from the document. | error — auto-decline |
AGE_BELOW_MINIMUM | Age below minimum | Adaptive age-verification workflows: extracted age is below the minimum. | error — auto-decline |
Address
| Risk | Short description | Cause | Severity |
|---|
UNPARSED_ADDRESS | Unable to determine address location | The document defines an address field, but the extracted address could not be parsed or geolocated. | Configurable — Unparsed Address, default information |
Cross-session document matches
In addition to the warnings above, the V3 ID report ships a matches[] array — up to 5 other documents in your application with the same date of birth, the same issuing country, and a highly similar full name (blocklisted documents additionally require an exact document-number match), excluding sessions that belong to the same user. Documents added to your blocklist appear with is_blocklisted: true. Documents on your allowlist still appear in matches, but their duplicate-user action is skipped.
Each match includes session_id, session_number, vendor_data, verification_date, user_details (name, document_type, document_number), status, is_blocklisted, api_service, and a signed front_image_url.
Examples
"warnings": [
{
"feature": "ID_VERIFICATION",
"risk": "QR_NOT_DETECTED",
"additional_data": null,
"log_type": "information",
"short_description": "QR not detected",
"long_description": "The system couldn't find or read the QR code on the document. This could be due to poor image quality or an unsupported document type.",
"node_id": "id_primary"
}
]
Auto-decline on expired document
"warnings": [
{
"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": "id_primary"
}
]
Expected-details mismatch with payload
"warnings": [
{
"feature": "ID_VERIFICATION",
"risk": "DOB_MISMATCH_WITH_PROVIDED",
"additional_data": {
"expected_dob": "1990-01-01",
"extracted_dob": "1991-03-15"
},
"log_type": "warning",
"short_description": "Date of birth mismatch with provided information",
"long_description": "The provided date of birth in `expected_details` doesn't match the date extracted from the document.",
"node_id": "id_primary"
}
]
Warning types
Each risk is assigned a severity based on your application’s configuration. The three severities are:
Get Started
Integrate / SDKs
User Verification
Business Verification
Transaction Monitoring
Changelog