Verdicts

A verification carries one verdict, and it is the only field you should branch your business logic on. It is derived from the individual check verdicts by a fixed rule, so the same set of check results always produces the same answer.

The three verdicts

The roll-up rule

Evaluate in this order and stop at the first match.

1. If any required check has a verdict of reject, the verification is reject.
2. Otherwise, if any check has a verdict of review, the verification is review.
3. Otherwise the verification is approve.

Optional checks never cause a rejection. They still report their own verdict and reason codes on the check object, so you can apply your own policy to them, for example flagging an account internally without blocking sign-up.

Verdict against status

Keep these two apart, because conflating them is the most common source of integration bugs.

verdict is the decision. status is where the session is in its lifecycle. The verdict is null until the session settles, and it is authoritative only once status is terminal. A verification sitting in processing may already have some checks resolved, but the roll-up is not final until the whole session is.

Reason codes

reason_codes on the verification is the union of the reason codes of the checks that drove the verdict. It is empty on a clean approval. Use it to decide what to tell the user, and use the per-check reason_codes when you need to know which step to send them back to. The vocabulary is listed in Reason codes.

A worked example

A flow of document (required), liveness (required) and AML screening (optional) produces:

The last row is the one worth reading twice. The AML check rejected, but it is optional, so it does not reject the verification. The document check needs a human, so the verification lands in review.