Verdict

The highest-level verification output is verification.verdict.

It's the culmination of all the checks, settings, properties of the document, and properties of the captured images.

The purpose of the verdict is to answer what to do with the document and the end user.

The answer depends on how you've defined fraud and desired behavior using the use case system and individual settings.

Possible values

The following things can happen when verifying a document:

• We can be sure it's genuine and live.
• We can be sure it's not genuine or not live.
• We can be unsure about one or both of the above.
• The document could be completely unextractable or unsupported.
• We can be fairly certain the quality of the images is poor to a degree that would affect the system's ability to make a fraud verdict.

Thus, the verdict can be one of the following values:

• Accept: the document is genuine and live.
• Reject: the document is not genuine or not live.
• Retry: the document can't be verified from these images, but a different image of the same document could resolve the issue.
• Review: the result is borderline, and a human should take a look. You still get a verdict and detailed check results.
• Unverifiable: the document isn't supported by our systems, or the image is so poor that we couldn't even find a supported document in it.

Verdict is an open enum: the schema lists the values above, but future versions of the API can add new ones without that counting as a breaking change. Handle a value you don't recognize as unknown rather than as invalid, so a new value can't break your integration.

What drives the verdict

Three use case parameters shape the verdict:

• verificationPolicy: HighConversion, Balanced, or HighAssurance. This is the pass rate versus fraud detection trade-off, and it works by moving the sensitivities you didn't set yourself. The default is Balanced.
• manualReviewStrategy: Never, RejectedAndAccepted, RejectedOnly, or AcceptedOnly. This decides whether a borderline document can come back as Review at all. The default is RejectedAndAccepted.
• verificationContext: Remote or InPerson. InPerson disables the checks that only make sense for remote capture, so those checks can no longer contribute to a Reject. The default is Remote.

On top of that, individual settings affect the verdict: each check's sensitivity, the image quality retry policy, and cropAffectsVerdict.

Act on the verdict

• On Accept, proceed with the user.
• On Reject, read verification.failedChecks to find out why. It's a flat array of dotted paths into verification.checks, such as checks.extractedDataCheck.matchCheck.dateOfBirthCheck, and it's the fastest way to see what went wrong.
• On Retry, ask the user for a new image of the same document, and read imageAssessment to find out what to ask for.
• On Review, route the transaction to your manual review queue. You still get the full verification.checks breakdown to show the reviewer. If you don't have a review queue, consider disabling manual review.
• On Unverifiable, there's nothing to retry with this document. Either the document type isn't supported, or no supported document was found in the image.

For the shape of each of these objects in the response, see Interpret the response.

Review requires manual review to be enabled

A Review verdict only occurs if manual review is enabled through manualReviewStrategy.

With Never, borderline documents are resolved into Accept or Reject instead, so the only verdicts you can get are Accept, Reject, Retry, and Unverifiable.

Which side of the borderline band gets routed to review is also up to you: RejectedOnly sends only near-rejections, AcceptedOnly sends only near-acceptances, and RejectedAndAccepted sends both.

See Manual review strategy for the full explanation.

When image quality turns a verdict into Retry

Retry exists because a failing check isn't always evidence of fraud. A document number obscured by glare fails a data check just like a tampered one does, and an image artifact can be visually indistinguishable from physical tampering.

verification.settings.imageQualityRetryPolicy decides what Verify does with that ambiguity:

• NeverRetryBadQuality: reach a verdict regardless of image quality issues.
• RetryBadQualityAlways: return Retry whenever image quality issues are detected.
• RetryBadQualityForAcceptances: return Retry only when quality issues stand between the document and an Accept.
• RetryBadQualityForRejections: return Retry only when quality issues stand between the document and a Reject. This is the default, so a document that would otherwise be rejected on poor-quality images comes back as Retry instead.

Verdicts are never inverted by this policy: a Fail never becomes a Pass.

To find out why a Retry happened, look at imageAssessment, which holds imageQualityCheck, croppedDocumentCheck, and handPresenceCheck. Cropping is a special case: by default a cropped document counts against the verdict, and you can change that with cropAffectsVerdict.

How close the verdict was

A single verdict doesn't tell you how marginal the decision was.

Tiered checks report passesAtOrBelowSensitivity, the highest sensitivity at which that check would still have passed. Compare it with the sensitivity you actually configured, and you know how much headroom the document had.

tip

passesAtOrBelowSensitivity returns "None" for failed checks that wouldn't pass even "Level1" sensitivity, and "NotApplicable" and "Disabled" when the check isn't applicable or is disabled.

This replaces two v2 fields, both of which are gone: the per-check matchLevel, and the overall verification.certaintyLevel. Instead of one confidence figure for the whole transaction, you get per-check headroom, which tells you which check to loosen if you want a different outcome.

See Sensitivities for the levels, and Checks for the individual checks.