mode is staged. The documents reached you through your own onboarding, so
there is nobody to send to a journey: you upload what you hold, send the values the steps take, and
ask for the checks to run.
Three calls: create, upload each file, run. For runnable code, see
Recipes; for request and response shapes, the
API reference tab.
A workflow whose mode is instant is answered in a single call instead, with the result in the
reply; see Instant. A workflow is configured for one or the other.
Creating
POST /verifications takes the workflow_key, your reference_user_id and any context, and nothing
else. There is no user to sign in, so a call that names a mobile or a return_url is refused with
400, and the record comes back with mobile, return_url and journey_url all null.
Creating is idempotent on your reference: the same reference_user_id in the same workflow always
resolves to the same verification, answering 200 instead of 201, until that verification expires.
See Verification lifecycle for the rest.
Addressing a document
Every step a staged workflow declares is one you can answer. The types the person being verified answers themselves,selfie, premises-photos, digilocker and review, belong to a hosted
workflow and are never declared on a staged one.
A file is uploaded against the step it belongs to and the slot on that step it answers. Reading the
workflow names both: intake.slots lists the slots, each saying whether it is required and which kinds
of document satisfy it, and intake.values names the values the step takes in the run request. A step
whose intake is empty on both counts is answered from what earlier steps established, and you send
nothing for it.
Every slot names the kinds of document that satisfy it, as a bank account proof takes a statement, a
cancelled cheque or a bank letter. Where a slot names several, send the kind alongside the file to
say which of them yours is; where it names one, your file is taken as that one. The files in one slot
are all of the same kind, because together they are one document.
Each kind says how it arrives, in its accept: how many files, in what formats. They differ within one
slot, since a cancelled cheque is one photograph and a statement is a document of several pages, so
read the shapes off the kind you are sending rather than off the slot.
A PDF may be up to 20 MB and an image up to 10 MB. A file the slot cannot take is refused on its own
call, 415 for the wrong format and 413 for one over the limit, and nothing else you uploaded is
affected.
The mode, the step keys and the intake are stable. They are how you address a document and a value, so
they do not change under a workflow you are integrated against. What a step is configured to check, and
which steps a workflow declares, we tune as a journey is refined. Each refinement is a new version of
the workflow, and a verification you have created keeps the version it was created on, so the steps you
upload to and ask to run are the ones it had when you created it.
Correcting an upload
DELETE /verifications/{verification_id}/documents/{document_id} withdraws a file. It stops counting
towards its step and its slot has room again, so a wrong upload is corrected without resetting the
whole verification.
What you decide, and what we do
You supply documents and values. You never say which order the checks run in, which steps this particular subject needs, or when a step is finished. The workflow decides all three, and each step is checked against what the steps before it established.
A step gated on what an earlier step publishes cannot be decided when you ask for the run, so it is not
checked then. If it turns out to apply and nothing arrived for it, it reads
not-supplied, required or
not.
There is no separate step to confirm a document, and nothing to submit at the end. Asking for the
checks to run is the whole of it.
The run request freezes the submission
POST /verifications/{verification_id}/run records your request on the verification as
run_requested_at and returns at once. From that moment the submission is frozen: an upload, a
withdrawal, or another run request with different values is refused with 409 until you reset. Sending
the same run request again is safe; it names the run already in progress and changes nothing.
Reading each document and confirming it with the issuing body takes longer than a request should be
held open, so the record comes back with run_requested_at set, the checks still to run and the status
still open. Wait for your callback, or poll until the status is
completed.
When something is missing
A submission that cannot be run as it stands is refused with422 before anything runs, so a document
you left out is answered by the call that left it out rather than by a verification that never
finishes.
When a source cannot be reached
A registry or bank being unreachable is not a verdict about the subject, so we do not record one as though it were. The run keeps trying the submission for about an hour, and only once those attempts are spent does the verification complete with that step readingerror.
That is what distinguishes it from failed: a failed step was checked and did not stand up; a step in
error was never checked at all.