Get verification status
Returns the minimal lifecycle state of a verification. status is the merged
top-line (not_started, in_progress, processing, in_review,
awaiting_resubmission, approved, declined, abandoned, expired, error)
and checkStatus is what the automated checks found (pending, verified,
failed, not_found, error). Act on status; keep checkStatus as the
explanation. The two differ whenever your workflow or a reviewer decided something
the checks alone would not have, for example processing with
checkStatus: "verified" while your workflow waits on a screen. Before submission
there is no checkStatus, because no checks have run. See
Status and checkStatus for every combination.
This endpoint is publishable-safe: it can be
called with the pk_ key that ships in your SDK, so it deliberately returns no
PII, no match scores, and no result data. To read the full result + extracted
biodata, use Get verification result with a secret
(sk_) key from your backend.
Webhooks are the recommended way to learn about completion without polling.
Authentication: Authorization: Bearer pk_… or sk_… (required). A verification is only visible to the organisation that created it.
Request
Responses
Every response includes verificationId, status, createdAt, your
externalUserId (so a publishable key can tell which user an id belongs to;
your metadata stays on the secret-key result), and
the workflow attribution pair workflowId / workflowVersion (both null when
the SDK was configured with plain props instead of a workflow), and
attempt with its submittedAt. A verification you
send back or verify again keeps its id: when the applicant
resubmits, attempt counts up and submittedAt and completedAt describe their
latest attempt.
Why a verification is still processing
processing means “no answer yet”, and it covers both the eight seconds we
spend reading a document and the eight days an address presence
watch runs. Those read identically
on a row, so waitingOn says which:
It is only ever set while a decision run is genuinely parked, and it clears the moment the run continues. Values are add-only: treat one you do not recognise as a check you have not learned about yet, rather than mapping it to a known one.
processing / approved
workflowVersion is the published version that actually ran. Publishing a
workflow overwrites its live configuration in place, so keep the pair if you need
to explain later exactly which rules a submission went through. The workflow’s
human-readable name is on the full result; this
endpoint stays minimal.
An approved status confirms the person was accepted, but carries no identity
data. Fetch the full result with a secret key to read
the biodata and facial-match score.
approved with checkStatus: "failed" is not a contradiction. It means the
person was accepted despite what the checks found, by a reviewer or by one of your
workflow rules, and reason/reasonCode below say what they were accepted
despite. Branch on status; store checkStatus alongside it.
declined / error
declined means the person was not accepted, either because the checks did not pass or because a reviewer declined them. error means a system problem occurred on our side and you were not charged. Both include a human-readable reason and a stable reasonCode you can branch on. See failure reason codes.
A reason is present whenever the checks did not pass, even on a verification a reviewer later approved.
declined with identity_not_found
An ID number the government database does not hold is a decline like any other; the reasonCode is what tells it apart from a failed face match. There is no separate not_found status.
Errors
Polling guidance
If you must poll, do so with backoff (e.g. every 2–3 seconds, widening over time) and keep going while status is processing, in_review or awaiting_resubmission, and stop once it settles on approved, declined, abandoned, expired or error. Prefer webhooks for production. Once complete, fetch the full result from your backend.