Skip to main content
POST
Run an instant verification

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

A whole verification in one request: the subject, the values its steps take, and every document.

​
workflow_key
string
required

Which of your workflows the verification runs. Its mode must be instant.

Minimum string length: 1
​
reference_user_id
string
required

Your own label for the subject of this verification. It is echoed back on every response, and together with the workflow key it is the handle that survives once the verification has expired, so make it something you can reconcile against your own records.

It is a label rather than a key: every call runs the checks and is charged for, so sending the same one again is a second verification of that subject and several records may carry it. Listing by it reads back every time you asked.

Required string length: 1 - 255
​
context
Context · object

Facts you already know about the user, as a flat JSON object. Workflow conditions and step inputs can read these values to decide what the verification asks for.

A field one of the workflow's required steps cannot run without is refused if you leave it out. Fields no step reads are yours to use as you like and are echoed back untouched.

​
steps
Steps · object

Values for the steps that take them, keyed by step key. Each step's intake.values on the workflow names the values it takes; a step whose intake.values is empty takes none and has no entry here.

Leave a step out and it is answered from the documents you sent for it. Leave out an optional step entirely, sending no document for it either, and it is recorded as not provided. A step that takes both, such as a bank account, is answered with one or the other: sending values and a document for the same step is refused.

Example:
​
documents
CarriedDocument · object[]

Every document the workflow asks for, at most 12 of them, each naming the step it answers. Send several for one slot where that slot takes several, as a certificate whose pages arrive as separate images does.

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.

Maximum array length: 12

Response

The finished record, with every step checked and its verdict on it.

The whole record of one verification; safe to poll.

​
id
string<uuid>
required

The verification's id.

​
mode
enum<string>
required

How verifications on this workflow are conducted. hosted: the person being verified walks the journey on our screens and submits it. staged: you create a verification, upload each document against the step it answers, and then ask for the checks to run. instant: you send the whole submission in one request, which runs the checks and answers with the finished record.

A workflow is one of the three, and every endpoint belonging to another is refused on it.

Available options:
hosted,
staged,
instant
​
status
enum<string>
required

open while the run is live and the user may act, which a step held up by a technical problem does not end; submitted once the user has finished, which they can only do with every step settled, so the result is final from that moment; completed once the checks that follow a submission have run, such as notifying you by callback, and the data is safe to read; failed if the run reached an unrecoverable state, in which case reset it or create a new one; cancelled if you ended the run; gated if a check this workflow puts to a system of yours stopped the journey there, which ends the run where it stood. A check stops it when your system answers terminate or redirect, or when your system gave no answer and the workflow falls back to terminate. Poll until the status is one of completed, cancelled, gated or failed.

expired supersedes all of them once the retention window runs out: the run is of no further use and is kept for your audit alone. It says nothing about how the run had ended, so read completed_at, cancelled_at, gated_at or failed_at for that rather than expecting the status to hold it.

Available options:
open,
submitted,
completed,
cancelled,
gated,
expired,
failed
​
workflow_key
string
required

The workflow this verification runs.

Minimum string length: 1
​
version
integer
required

Which version of the workflow this verification runs. It is the workflow's latest version when the verification was created, and it holds for the verification's whole life: a change published to the workflow afterwards never changes what this verification asks for, which steps it reports or the names its outputs arrive under. Resetting the verification moves it onto the latest version at the time.

Required range: x >= 1
​
mobile
string | null
required

The user's mobile number, as you provided it. Null on a verification you supplied yourself, and null once the verification has expired.

​
reference_user_id
string
required

Your identifier for this verification, echoed back.

​
context
Context · object
required

The facts you supplied when you created it, unchanged. Empty once the verification has expired.

​
return_url
string | null
required

Where the user is sent after submitting, where one was given.

​
journey_url
string | null
required

Where to send your user, on a hosted verification. The same address serves every user of this workflow and carries no credential, so it is safe to send over WhatsApp, SMS, or email, and the user proves who they are by signing in with the mobile number you created the verification with. To open the journey from inside your own app with the user already signed in, create a handoff instead.

Null on a verification you supplied yourself, which opens no journey.

​
created_at
string<date-time>
required

When the verification was created.

​
run_requested_at
string<date-time> | null
required

When you asked for the checks to run, on a staged verification. From that moment the submission is frozen: uploads, withdrawals and a run request with different values are refused until you reset.

On an instant verification it is when the request carrying the whole submission arrived. Null on a hosted one, and null on a staged one until you ask.

​
submitted_at
string<date-time> | null
required

When the verification was submitted, if it has been: by the user on a hosted workflow, by the run of the checks on one you supplied yourself.

​
completed_at
string<date-time> | null
required

When the verification completed, if it has.

​
cancelled_at
string<date-time> | null
required

When the verification was cancelled, if it was.

​
gated_at
string<date-time> | null
required

When a check of yours stopped the journey, if one did.

​
gated_by_step
string | null
required

The step whose check stopped the journey, if one did. A workflow may put more than one check to you, and this says which of them the run stopped at.

It is set and cleared with gated_at: it stays set once the verification expires or you purge it, so the record still says how the run had ended, and a reset clears both.

​
failed_at
string<date-time> | null
required

When the verification was marked failed, if it was.

​
expired_at
string<date-time> | null
required

When the verification expired, if it has. From that moment it is kept for your audit and nothing else: it holds what each step concluded and nothing the user gave, so no answers, no values read off their documents, and no files. The step states you read are the ones frozen at that moment. Read the other timestamps to see how it had ended before it expired.

​
expired_by
enum<string> | null
required

What expired the verification. retention when its workflow's retention window ran out; client when you purged it. Null until it expires.

Available options:
retention,
client
​
last_activity_at
string<date-time>
required

When the verification was last acted on: by the user on a hosted workflow, by you or by the run of the checks on one you supplied yourself. A verification that is created and never touched reads the moment it was created. expires_after_days is counted from here, so the two together say when a record left untouched expires.

​
expires_after_days
integer
required

How many days this verification may go without activity before it expires and everything the user provided is deleted, as the version it runs states. It is this verification's own window: a later version of its workflow can state a different one, which reaches the verifications created or reset after it, so read the window here rather than off the workflow. On an expired verification it is the window it was held to.

Required range: x >= 1
​
acknowledgement
AcknowledgementRecord · object | null
required

The receipt the user was sent telling them their submission arrived, on a workflow that acknowledges submissions by email. Null wherever nothing has been sent: a workflow that acknowledges nothing, a verification carrying no address to send to, a submission still being finalised, and a send that could not be made.

It names the submission it answers. A reset undoes a submission without unsending its receipt, so read submitted_at here against the record's own to tell a receipt for the submission this record stands in from one for a submission it no longer does.

​
callback
CallbackRecord · object | null
required

How the callback for this verification's run ended: verification.submitted once it was submitted, or verification.gated once a check of yours stopped it. Null until the callback settles, and on every verification of a workflow with no callback endpoint registered. A verification completes, or stays gated, whether or not its callback was delivered, so read this to tell a result you were told about from one you were not.

​
credits_consumed
integer
required

How many credits this verification has used. A run uses one credit when it first reaches completed, cancelled or expired, whatever the workflow asks for and however many of its checks ran. A run that ends as failed or gated uses none, and one still open or submitted has used nothing yet.

Resetting a verification runs the subject through again, which is a run of its own and uses a credit of its own, so a record reset twice and completed each time reads 3.

​
resets
integer
required

How many times this verification has been reset. A reset clears everything the record collected and runs the subject through the checks again, so a verification reading 2 is on its third run and holds what that one has collected.

Each of these opened a run charged a credit of its own where it ended, which is what credits_consumed counts. A reset that cleared a run no credit had paid for also drew one of the workflow's resets: see resets on the workflow.

​
progress
ProgressRecord · object
required

Every step of the journey counted by where it stands, the ones left out included.

​
steps
StepRecord · object[]
required

The steps this journey has not ruled out, in journey order. A workflow presents the steps that apply to whoever is being verified, so a journey that took one branch reports that branch and not the others; progress.not_applicable says how many are missing from here, and reading the verification with include_not_applicable shows them.

A step is only missing once something has ruled it out. One whose place in the journey turns on a value an earlier step has yet to publish is here, reading undetermined, so a verification you have just created reports every step its workflow declares and they resolve into the other states as it goes on.