ID verification warnings

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.

For the standalone OCR API, the unconditional-decline set is DOCUMENT_EXPIRED, MINIMUM_AGE_NOT_MET, PORTRAIT_IMAGE_NOT_DETECTED, SCREEN_CAPTURE_DETECTED, PRINTED_COPY_DETECTED, PORTRAIT_MANIPULATION_DETECTED, and PUBLIC_DOCUMENT_IMAGE_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 Without Portrait	`DOCUMENT_HAS_NO_PORTRAIT`	Review

Two ID risk families are threshold-driven instead of Approve/Review/Decline toggles:

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.

One ID risk is neither configurable nor threshold-driven: BARCODE_SIGNATURE_INVALID always routes to Review. It fires only when a barcode carries an issuing-authority signature that fails cryptographic verification, so there is no configuration in which a proven forgery is ignored.

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
`DOCUMENT_HAS_NO_PORTRAIT`	Document has no portrait	The recognized document family never carries a portrait photo on any side (some residence permits, health cards, registration certificates, tax cards, and a subset of DLs/IDs). This is a catalog-level fact about the document type, not an image-quality issue — re-scanning the document cannot change the outcome.	Configurable — Document Without Portrait, default Review
`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, IMAGE_QUALITY_TOO_LOW, and DOCUMENT_OCCLUSION_DETECTED (a finger or object is judged to be physically covering printed text). These prompt a retake in the SDK but are not persisted to the report’s warnings[] — only the blurry/dark/bright risks are.

If your workflow anchors identity on Face Match rather than the document portrait, consider routing Document Without Portrait to Decline — otherwise a portrait-less document family reaches Face Match with nothing to compare against.

Field extraction

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
`BARCODE_SIGNATURE_INVALID`	Barcode signature invalid	The barcode carries a digital signature from the issuing authority, and that signature did not verify - the data in the barcode is not the data the authority signed, which points to a forged or altered document. Currently checked for French 2D-Doc (ANTS) barcodes, where a verified signature lets Didit promote fields without needing MRZ corroboration; AAMVA (US/Canada driving licences and IDs) signatures are detected and logged only, not yet enforced.	Fixed - Review (own action group `invalid_barcode_signature_action`; not yet console/API-configurable)
`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

Barcode signature verification currently covers French national ID cards, whose ANTS 2D-Doc barcode is signed by the issuing authority. BARCODE_SIGNATURE_INVALID is raised only when the signature check itself rejects the payload. A barcode with no signature, one signed by an authority not yet in Didit’s trust store, or one whose signature cannot be decoded is treated as unauthenticated data and validated against the MRZ and printed text as before, without raising this risk.US and Canadian driving licence (AAMVA) barcodes are not cryptographically verified: digital signing there is optional and jurisdiction-specific, and no jurisdiction publishes verification keys, so Didit only detects and logs whether a payload carries a signature; the signature itself is never checked. AAMVA signature failures are not a risk signal today. A tampered AAMVA payload only surfaces as BARCODE_VALIDATION_FAILED, and only if the tampering also makes the barcode disagree with the MRZ or printed/OCR data - a forged signature on an otherwise internally consistent payload passes with no signal at all.The user is never asked to re-capture on BARCODE_SIGNATURE_INVALID: a signature that does not match the payload cannot be fixed by taking a better photo.

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

Known public document images

Risk	Short description	Cause	Severity
`PUBLIC_DOCUMENT_IMAGE_DETECTED`	Known public internet document image detected	The submitted document image matches a known publicly available internet image (for example a specimen, press, or stock photo of a document), so it cannot be a photo of the user’s own physical document. Matching uses exact and perceptual (pHash/dHash) fingerprinting against Didit’s corpus of known public document images; `additional_data` carries `match_type` (`exact` or `perceptual`), `source`, `source_url`, and a `similarity_score` (0-100).	Fixed - Review in workflows; auto-decline on the standalone `/id-verification` API

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.

Each mismatch warning carries the expected and extracted values in 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

Configurable warning at its default routing (information)

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

ID verification report — full report schema and statuses.
Document monitoring — how Didit detects tampering and cross-session duplicates.
Webhooks — session.status.updated carries the warnings as soon as the ID step finishes.
Data models — ID verification — canonical field-by-field schema.
Data models — Warning object — the shape of every entry in warnings[].

Authentication

Verification

Monitoring

Platform

Overview

Auto-decline conditions

Configurable verification settings

Warnings produced

Document recognition and quality

Field extraction

MRZ, QR, barcode

Identity matching

Document liveness (tampering)

Known public document images

Expected-details mismatches

Age

Address

Cross-session document matches

Examples

Configurable warning at its default routing (information)

Auto-decline on expired document

Expected-details mismatch with payload

Warning types

​Overview

​Auto-decline conditions

​Configurable verification settings

​Warnings produced

​Document recognition and quality

​Field extraction

​MRZ, QR, barcode

​Identity matching

​Document liveness (tampering)

​Known public document images

​Expected-details mismatches

​Age

​Address

​Cross-session document matches

​Examples

​Configurable warning at its default routing (information)

​Auto-decline on expired document

​Expected-details mismatch with payload

​Warning types

​Related

Overview

Auto-decline conditions

Configurable verification settings

Warnings produced

Document recognition and quality

Field extraction

MRZ, QR, barcode

Identity matching

Document liveness (tampering)

Known public document images

Expected-details mismatches

Age

Address

Cross-session document matches

Examples

Configurable warning at its default routing (information)

Auto-decline on expired document

Expected-details mismatch with payload

Warning types

Related