Skip to navigation
Identity verification APIVerifications

Review a verification

Approves, declines or sends back a finished verification, or changes an earlier decision. The check result is never rewritten. Your webhook endpoints receive verification.status_updated. Only a send-back creates a session, so only a send-back counts towards the session rate limit.

Error codes

errorStatusMeaning
invalid_input400The body is malformed, or a field came with a decision it does not apply to.
invalid_steps400A step name is not valid. The message lists the valid names.
invalid_reference_photo400A biometric workflow reference photo could not be found.
verification_not_found404No verification with that id for this organisation and environment.
verification_in_progress409The checks have not finished.
no_workflow422The verification did not run a workflow, so there is no flow to send the applicant back into.
user_reference_required422A biometric workflow redo did not name its subject.
not_enrolled422The subject has no active biometric enrolment.
rate_limited429Too many sessions were started. Try again shortly.
Missing or invalid Authorization header401No bearer credential was sent.
Invalid API key401The key is unknown or revoked.
environment_mismatch403The key belongs to an environment this host does not serve.
origin_not_allowed403The request origin is not on the publishable key allowlist.
ip_not_allowed403The caller address is not on the secret key allowlist.
organization_suspended403The organisation is suspended.
secret_key_required403A publishable key was used on a secret-key endpoint.
business_not_approved403A production key was used before the business was approved.

Requires a secret (sk_) key. A publishable key receives 403 secret_key_required.

Authentication

AuthorizationBearer
Send the API key as a Bearer token. Each operation states whether a publishable key is enough or a secret key is required.

Path parameters

idstringRequired
The verification identifier.

Request

This endpoint expects an object.
decisionenumRequired
Approve, decline, or send the verification back to the applicant.
Allowed values:
notestringOptional<=2000 characters
An internal note. Kept in your audit log and never sent to webhooks or returned by the API.
stepslist of enumsOptional

RESUBMISSION only. The steps to redo. Absent or empty means the whole flow.

messagestringOptional<=500 characters

RESUBMISSION only. Shown to the applicant when they open the link.

policyenumOptional

Which workflow version the redo runs: the one the applicant walked (original) or the one published now (latest). Absent follows the workflow setting.

Allowed values:
notifyApplicantbooleanOptional

APPROVED or DECLINED only. Whether to email the applicant about the decision. Absent follows the workflow.

emailstringOptionalformat: "email"<=320 characters

On a RESUBMISSION, email the link to this address. On an approval or decline sent with notifyApplicant: true, the address to email instead of the one on file.

Response

The decision was recorded.
reviewobject
The recorded decision.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error