Decision reasons

When a verification ends as declined or resubmission_requested, its reason field names why, in the verification object and in the webhook. For every other status reason is null, and so is it on the resubmission_requested a facial age estimation sends when it asks for an ID. A verification carries one reason: the most important of what went wrong. A selfie that is unclear and also looks like a photo of a screen is reported as the screen, not as unclear.

Using the reasons

Declined is final, whatever the code. Usually the check found something a new photo would not fix. But when the attempts run out, the verification is declined with the last attempt’s reason, which may be a code from the retake family below. Never offer a retry on declined. Don’t wait for verification.attempts.exhausted to spot a run-out either: it is listed below, but a verification that runs out of attempts carries its last attempt’s reason.
Resubmission requested means the person can still fix it. The widget already asks them to retake the image, so you rarely need to show the reason yourself.
Map codes to your own messages where you need them, and treat a code you do not know as a generic failure: new codes are added as checks improve.
The code’s first segment tells you which step failed: selfie, document, verification (a rule about the whole verification) or aml (the blocklist). Document codes name the side next when it matters, as in document.front.glare.high.

All reasons

Blocklist

Code	Label	What happened	Outcome
`aml.blocklist.device_match`	Device Linked to Blocked Identity	This device is linked to a blocked identity	Declined
`aml.blocklist.face_match`	Blocked by Security Policy	This person matches a restricted list	Declined

Document

Code	Label	What happened	Outcome
`document.ai.image_manipulation`	Image Manipulation Detected	Signs of digital manipulation or editing were detected on the document image	Declined
`document.ai.not_a_document`	Not an Identity Document	The uploaded image does not appear to be a valid identity document	Declined
`document.ai.suspicious_words`	Suspicious Words Detected	Suspicious or anomalous text was detected on the document	Declined
`document.back.blur.high`	Back Image Blurred	The document back image is too blurry	Resubmission requested
`document.back.damaged.folded_over_text`	Document Folded (Back)	The document back is folded, obscuring important text	Resubmission requested
`document.back.damaged.torn_or_cut`	Document Torn or Cut (Back)	The document back is physically torn or cut	Resubmission requested
`document.back.data.not_readable`	Back Data Not Readable	Text on the document back cannot be read — the image may be too blurry, damaged, or poorly lit	Resubmission requested
`document.back.data.not_visible`	No Text Detected (Back)	No text was detected on the document back — the image may not contain a valid document	Resubmission requested
`document.back.framing.not_fully_in_frame`	Document Back Outline Not Found	The edges of the back of the document could not be located in the photo	Resubmission requested
`document.back.glare.high`	High Glare on Back	Excessive glare on the document back makes it hard to read	Resubmission requested
`document.back.not_a_document_suspected`	Not a Valid Document (Back)	The back image does not appear to be a valid identity document	Declined
`document.back.obscured`	Document Back Obscured	Part of the document back is covered or obstructed by an object	Resubmission requested
`document.back.quality.poor`	Poor Back Quality	The document back image quality is insufficient	Resubmission requested
`document.back.spoof.photo_suspected`	Photo of Photo Suspected (Back)	The document back appears to be a photograph of another photo	Declined
`document.back.spoof.print_suspected`	Printed Document Suspected (Back)	The document back appears to be a printed copy	Declined
`document.back.spoof.screen_suspected`	Screen Photo Suspected (Back)	The document back appears to be photographed from a screen	Declined
`document.back.tampering.suspected`	Document Tampering Suspected (Back)	The document back shows signs of potential tampering or alteration	Declined
`document.checks.not_provided`	Document Check Missing	Required document verification was not provided	Declined
`document.data.not_visible`	No Text Detected	No text was detected on the document — the image may not contain a valid document	Resubmission requested
`document.expired`	Document Expired	The identity document has passed its expiry date	Resubmission requested
`document.face.match_insufficient_quality`	Face Comparison Inconclusive	The document photo quality is insufficient for reliable face comparison — please retake the document photo with better lighting	Resubmission requested
`document.face.mismatch`	Face Does Not Match	The selfie does not match the document photo	Declined
`document.fields.required_missing`	Required Fields Missing	Essential document information could not be read	Resubmission requested
`document.front.blur.high`	Front Image Blurred	The document front image is too blurry	Resubmission requested
`document.front.damaged.folded_over_text`	Document Folded (Front)	The document front is folded, obscuring important text	Resubmission requested
`document.front.damaged.torn_or_cut`	Document Torn or Cut (Front)	The document front is physically torn or cut	Resubmission requested
`document.front.data.not_readable`	Front Data Not Readable	Text on the document front cannot be read — the image may be too blurry, damaged, or poorly lit	Resubmission requested
`document.front.data.not_visible`	No Text Detected (Front)	No text was detected on the document front — the image may not contain a valid document	Resubmission requested
`document.front.face.angle_incorrect`	Document Face Photo at Wrong Angle	The face photo on the document is tilted or at the wrong angle	Resubmission requested
`document.front.face.not_clear`	Document Face Photo Blurry	The face photo on the document is blurry or unclear	Resubmission requested
`document.front.face.not_found`	No Face on Document	No face photo was found on the front of the document	Resubmission requested
`document.front.face.occluded`	Document Face Photo Partially Hidden	Part of the face on the document is covered or obstructed	Resubmission requested
`document.front.face.too_small`	Document Face Photo Too Small	The face photo on the document is too small to extract for comparison	Resubmission requested
`document.front.framing.not_fully_in_frame`	Document Front Outline Not Found	The edges of the front of the document could not be located in the photo	Resubmission requested
`document.front.glare.high`	High Glare on Front	Excessive glare on the document front makes it hard to read	Resubmission requested
`document.front.not_a_document_suspected`	Not a Valid Document (Front)	The front image does not appear to be a valid identity document	Declined
`document.front.obscured`	Document Front Obscured	Part of the document front is covered or obstructed by an object	Resubmission requested
`document.front.quality.poor`	Poor Front Quality	The document front image quality is insufficient	Resubmission requested
`document.front.spoof.photo_suspected`	Photo of Photo Suspected (Front)	The document front appears to be a photograph of another photo	Declined
`document.front.spoof.print_suspected`	Printed Document Suspected (Front)	The document front appears to be a printed copy	Declined
`document.front.spoof.screen_suspected`	Screen Photo Suspected (Front)	The document front appears to be photographed from a screen	Declined
`document.front.tampering.portrait_replaced_suspected`	Portrait Replacement Suspected	The photo on the document appears to have been replaced	Declined
`document.front.tampering.suspected`	Document Tampering Suspected (Front)	The document front shows signs of potential tampering or alteration	Declined
`document.front.tampering.text_overlay_suspected`	Text Overlay Suspected (Front)	Text on the document front appears to be digitally overlaid	Declined
`document.quality.poor`	Poor Document Quality	The document image quality is insufficient	Resubmission requested

Selfie

Code	Label	What happened	Outcome
`selfie.face.multiple_detected`	Multiple Faces Detected	More than one face was detected in the selfie	Resubmission requested
`selfie.face.not_clear`	Face Not Clear	The face in the selfie is blurry or unclear	Resubmission requested
`selfie.face.not_found`	Face Not Detected	No face was found in the selfie image	Resubmission requested
`selfie.face.occluded`	Face Partially Hidden	Part of the face is covered or obstructed	Resubmission requested
`selfie.framing.not_fully_in_frame`	Face Not Fully Visible	The face is cut off or not fully in frame	Resubmission requested
`selfie.liveness.failed`	Liveness Check Failed	The liveness check did not confirm a live person in front of the camera	Declined
`selfie.liveness.unavailable`	Liveness Check Unavailable	The liveness check could not be completed for technical reasons	Declined
`selfie.quality.lighting_poor`	Poor Lighting	The selfie has insufficient or uneven lighting	Resubmission requested
`selfie.quality.poor`	Poor Image Quality	The selfie quality is insufficient for verification	Resubmission requested
`selfie.quality.screen_attack_suspected`	Screen or Device Check Failed	Please retake the selfie without screens or other devices visible	Resubmission requested
`selfie.quality.spoof_suspected`	Selfie Liveness Check Failed	Please retake the selfie directly from a live face	Resubmission requested
`selfie.quality.too_bright`	Image Too Bright	The selfie is overexposed	Resubmission requested
`selfie.quality.too_tilted`	Face Angle Incorrect	The face is tilted or at the wrong angle	Resubmission requested
`selfie.spoof.non_human_suspected`	Non-Human Face Suspected	The selfie face appears to be a doll, figurine, mannequin or mask rather than a live person.	Declined
`selfie.spoof.print_suspected`	Printed Photo Suspected	The photo appears to be of a printed image	Declined
`selfie.spoof.screen_suspected`	Screen Photo Suspected	The photo appears to be taken from a screen	Declined

Verification

Code	Label	What happened	Outcome
`verification.age_threshold.failed`	Age Requirement Not Met	The person does not meet the minimum age requirement	Declined
`verification.attempts.exhausted`	Attempts Exhausted	All resubmission attempts have been used without a successful verification	Declined
`verification.processing.failed`	Processing Error	An error occurred during verification processing	Resubmission requested

Selfie checks

Document checks

Fraud prevention

Reference

Using the reasons

All reasons

Blocklist

Document

Selfie

Verification

​Using the reasons

​All reasons

​Blocklist

​Document

​Selfie

​Verification

Using the reasons

All reasons

Blocklist

Document

Selfie

Verification