For a workflow whose mode is instant. Everything a verification takes goes in the body, the checks
run before the response comes back, and the record you get is the finished one. The documents are read
as they arrive and stored nowhere, so nothing of the files outlives the request that carried them.
One call. For runnable code, see Recipes; for request and response
shapes, the API reference tab.
For a workflow built up over several calls instead, with the checks running after the response, see
Staged. A workflow is configured for one or the other, so its mode tells you
which you are integrating.
The call
POST /verifications/instant takes the workflow_key, your reference_user_id, any context, the
steps that take values, and documents.
Each document names the step it answers and carries the file base64-encoded. Name the slot as well
only where the step has more than one; a step with a single slot takes the file without being told,
because there is nothing else it could be. Reading the workflow tells you which is which:
intake.slots lists a step’s slots and intake.values names the values it takes.
Send several documents to the same slot where that slot takes several, as a certificate whose pages
arrive as separate images does. The files in one slot are all of the same kind, because together they
are one document.
Every slot names the kinds of document that satisfy it. Where it names several, as a bank account
proof takes a statement, a cancelled cheque or a bank letter, name which of them yours is as the
document’s kind; where it names one, your document is taken as that one. Each kind says how many
files it arrives as and in what formats, in its accept, and the kinds of one slot differ.
What comes back
The finished record: every step, its state, what it collected and why anything did not pass. The same
record the other ways of running a verification produce, and the same shape you would have polled for.
There is nothing to wait for and no callback for this call.
Each file is on it as its name, type, size and SHA-256 hash, against the step and the slot and kind it
answered as.
That is the record of what was checked, and it survives like everything else the verification
concluded; the file itself does not, so asking for a link to one answers 409.
Every call runs
There is no record here to add to or come back to, so nothing is reused between calls. Send the same
subject again, with the same documents or different ones, and you get a second verification of them
answered on what that call carried.
reference_user_id is your label for the subject rather than a key, so several records may carry it.
Reading them back by it lists every time you asked, newest first:
That is also how you find a result whose response you never saw, because a call that reached us ran
the checks whether or not the answer got back to you.
Limits
Up to 12 documents in one request. A PDF may be up to 20 MB and an image up to 10 MB, and the
documents together may total 25 MB once decoded. A request larger than that is refused with 413
before it is read.
Reading documents and confirming them with the issuing registries takes time, so allow at least 200
seconds before your own client gives up. A typical submission answers in well under a minute.
Losing the connection does not stop the run. Whether your own client gave up or the connection was cut
between us, the checks are still made and still charged for, and the record is finished here even
though no response reached you. There is no id in your hands in that case, so find it by the
reference you sent:
Read it back before you send the submission again. Every call to this endpoint is a new verification
and a new credit, so a submission you retry after a timeout is charged twice and answered twice.
error rather than a verdict. The rest of the record stands, so a submission that runs long comes back
partly checked rather than not at all.
When something is missing
A submission that cannot be run as it stands is refused before anything runs, and nothing is checked
or charged for. A required step with nothing sent for it:
A slot filled only in part, whether its step is required or not:
A step given both values and a document, which the step would have to choose between:
A document naming a step the workflow does not declare, or leaving out the slot where the step has
several, is refused the same way. Correct the request and send it again.
When a check could not be made
A registry being unreachable is not a verdict about the subject, so none is recorded. That step reads
error, the rest of the record stands, and the response still carries it all.
That is what distinguishes error from failed: a failed step was checked and did not stand up; a
step in error was never checked at all. Send the request again to have another go at those; it is a
verification of its own and answers on its own checks.
Which to use
