Skip to main content
POST
Approve a verification

Authorizations

Authorization
string
header
required

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

Path Parameters

verification_id
string<uuid>
required

Body

application/json

What approving or rejecting a verification takes.

reason
string | null

Why, in your own words, for whoever reads the record after you. It is deleted with everything the user provided once the verification expires or you purge it, and the review itself stays.

Required string length: 1 - 500

Response

The record, now approved.

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, and again once you reopen a finished run for the user to correct; 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; pending-approval instead of completed on a hosted workflow that does not approve its runs automatically, until you approve the run or reject it, which makes it rejected; pending-signature instead of completed, once approved, on a version that offers contracts, until a contract of each one in offered_contracts is signed, which completes it; 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 one of your gate checks ended the run where it stood, which your system does by answering terminate or redirect, as does a workflow falling back to either when your system gives no answer. Poll until the status is one of pending-approval, pending-signature, completed, rejected, 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, signed_at, review, cancelled_at, gated_at or failed_at for that rather than expecting the status to hold it.

Available options:
open,
submitted,
pending-approval,
pending-signature,
completed,
rejected,
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 where you gave none, on a verification you supplied yourself, and once the verification has expired.

email
string | null
required

The user's email address, as you provided it and lowercased. Null where you gave none, on a verification you supplied yourself, and once the verification has expired.

reference_user_id
string
required

Your identifier for this verification, echoed back.

inviter
string | null
required

The person any invitation email into this verification names as inviting the user: the inviter you created it with, or your account's default inviter where you gave none. It is kept whether or not an invitation is emailed, so one sent after a reset onto a version that sends them names the same person, and it stays after the verification expires, being your colleague's name and not the user's data. Null where neither names anyone, and on a verification you supplied yourself.

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 address of this verification's own journey. It 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 a one-time code sent to the contact the workflow's signs_in_with names, as you created the verification with it. Your own people open the same address to answer the steps the workflow gives them, signed in as themselves. Where the verification's version has sends_invitations true we send it to every contact you gave, and invitation says how each fared: wherever it reads not-sent, send this link yourself. On any other, send it yourself. 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. Reopening the verification clears it until the user submits again.

completed_at
string<date-time> | null
required

When the work that follows the submission was done, if it has been, whether the run then completed or waited on your review. Approving or rejecting the run leaves it as it is; reopening it clears it until the user's next submission has been through the same.

signed_at
string<date-time> | null
required

When the last of the contracts the verification waited on was signed, which completed it. Null until then, on a version that offers no contracts, and once you reject or reset it.

offered_contracts
string[] | null
required

The contract workflows the verification is signed on once you approve it, by key: each one its version offers whose condition the run meets. Send it a contract of each from pending-signature; a contract workflow not named here is refused. Until the run is approved it names the ones its answers so far meet.

Empty on a version that offers no contracts. A run approved with this empty on a version that offers some waits in pending-signature with nothing to send, until you reopen, reset or reject it. Null once the verification expires.

review
ApprovedReviewRecord · object
required

An approval, which completed the run or, on a version that offers contracts, left it pending-signature.

reopen
ReopenRecord · object | null
required

Your latest reopen of the run, and every step to look at again since: each step it sent back and every other step that differs from then, so you know what changed before you give your verdict. It stands from the reopen until you approve, reject, reset or cancel the run, through the user submitting it again, which clears review. Null on every other run, and once the verification expires.

cancelled_at
string<date-time> | null
required

When the verification was cancelled, if it was.

gated_at
string<date-time> | null
required

When one of your gate checks ended the run, if one did.

gated_by_step
string | null
required

The gate check that ended the run, if one did. A workflow may declare more than one, and this says which.

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, by you cancelling, resetting or reopening it, or by one of its contracts being sent, withdrawn or reaching its end. Approving or rejecting it, reminding a contract's signers and reading anything leave it as it was. A verification that is created and never touched reads the moment it was created. expires_after_days is counted from here.

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: 1 <= x <= 36135
expires_at
string<date-time> | null
required

When the verification expires if nothing more happens to it: last_activity_at plus expires_after_days. Any activity moves it later. Null once it has expired.

invitation
InvitationRecord · object | null
required

How the journey link went out to the user over each contact you gave, on a hosted verification whose version sends invitations. It is sent once the verification is created, again when it is reset, and whenever you ask for it to be sent again; this holds the latest, and a reset clears it until the new one has gone out. One created with invite false is sent none until you ask for it.

Null until the first has been sent, on a verification whose version sends no invitations, on one you supplied yourself, and where it could not be sent at all, in which case ask for it again or send journey_url yourself.

reminder
InvitationRecord · object | null
required

How the latest reminder to finish their journey went out to the user over each contact you gave, once you have asked for one. Null until the first has been sent, and again once the verification is reset.

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 one of your gate checks ended 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. Reopening the verification clears it, and the user's next submission is called back afresh.

completion_callback
CallbackRecord · object | null
required

How the verification.completed callback ended, which the last signature completing the run owes you. Null until it settles, on a run no signature completed, and on every verification of a workflow with no callback endpoint registered.

credits_consumed
integer
required

How many credits this verification has used. A run uses one credit when it first reaches pending-approval, pending-signature, completed, cancelled or expired, whatever the workflow asks for and however many of its checks ran, and approving, rejecting or reopening it uses nothing more, nor does the user submitting a reopened run again. Each contract sent on it uses a contract credit instead, which the workflow's contract_credits counts. 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.