Verifications

Cursor-paginated, newest first. limit accepts 1 to 100 and defaults to 20. To walk further, set starting_after to the id of the last record on the page you just read. has_more tells you another page exists and next_cursor is the value to pass back; on the last page has_more is false and next_cursor is null. An unknown cursor is ignored and you get the first page. Requires the verification:read permission on the calling key.

Query Parameters

Response Body

Start a verification. What it runs is resolved in this order: an inline checks array wins, then a flow id you name, then the flow you have marked as your default, and finally a built-in preset (document, liveness and face match) if you have no default. Send flow or checks, never both; omit both to run your default.

The flow on the response is the flow that actually ran, so a call that named nothing still tells you which composition it resolved to.

Returns a session with a short-lived client_token and a hosted_verify_url. In sandbox mode, magic applicant inputs (approved/rejected/review/pending) force the verdict.

An archived flow starts no new verifications: naming one, or having one as your default, returns 400 FLOW_ARCHIVED. An unknown flow id returns 400 FLOW_NOT_FOUND.

Requires the verification:create permission on the calling key. A key without it gets a 403. This is the one endpoint that honours Idempotency-Key.

Header Parameters

Response Body

Answer "have these people verified?" for up to 1,000 email addresses in one call. For each address you get whether any verification exists, how many there have been, whether any of them ever passed, and a summary of the most recent one.

It is a POST because it reads: a list of real people's addresses in a URL is written to every proxy log on the path and kept in shell history. The body keeps them out of both. A body is not privacy on its own, though, so redact request bodies wherever your own stack logs them.

found: false does not mean the person never verified. Three different situations produce it and none is distinguishable from the response:

1. They never started a verification.
2. They did, but nothing recorded their address on it. An address reaches a session in exactly two ways: you send applicant.email when you create the verification, or the applicant completes an email step in the hosted flow. If you do neither, every address you look up returns found: false against sessions that exist and completed normally.
3. They verified, and their retention window has since elapsed. We destroy the stored identity and the search fingerprint in the same statement, so a record we have promised to forget cannot still answer "yes, they verified".

Scoped to the calling key's environment, like every read: a live key does not see sandbox sessions.

Requires the verification:read permission. Rate limited by size rather than by call, at one token per 50 addresses, so a full 1,000-address call costs 20 of your per-minute budget.

Header Parameters

Response Body

Fetch the current status, verdict and per-check results for one session. client_token is only populated on create, so it is null here. Requires the verification:read permission on the calling key.

To also read who the applicant is and the images they captured, add ?include=applicant,documents. Both need the applicant:read permission, which is deliberately in no default permission set and is granted per key on request, because it is the only scope that returns a real person. Requesting either without it returns 403 rather than quietly omitting the data, so a missing applicant always means the applicant has none.

Path Parameters

Query Parameters

Response Body

Step one of the two-step upload. Reserves an upload against the session and returns a short-lived presigned upload_url. PUT the raw bytes straight to that URL with the same Content-Type you declared, then call the complete endpoint. The bytes never pass through this API.

Supported content_type values are image/jpeg, image/jpg, image/png, image/webp, image/heic, image/heif, application/pdf, video/mp4, video/webm and video/quicktime. Anything else is rejected with 400 UNSUPPORTED_CONTENT_TYPE.

Requires the verification:create permission on the calling key.

Path Parameters

Response Body

Step two of the two-step upload. Confirms the presigned PUT finished and moves the upload from pending to uploaded. The object must already be in storage, otherwise you get 400 UPLOAD_NOT_RECEIVED. Calling it again on an already completed upload is safe and returns the same record.

Takes no request body. Requires the verification:create permission on the calling key.

Path Parameters

Response Body

Lifts the ALREADY_VERIFIED refusal on one approved verification, so the person behind it can run your flow again. Call this when a create answered 409 and you have decided that person should go through anyway.

Most of the time you do not need it. An approval stops refusing repeats on its own when the document it was based on expires, and when the re-verification period you configured elapses. This is for what a date cannot express.

It does NOT un-approve anybody. The original approval stands, and the webhook you already received for it stays true, until a new approval supersedes it. The applicant still has to pass every check in the flow.

One permission at a time: an approval can hold at most one open grant, so calling this twice returns the same grant with 200 rather than opening a second. The permission is spent by the next verification it lets through, and lapses at expires_at if nobody uses it.

Requires the verification:create permission, the same one that creates a verification, so no new key is needed.

Path Parameters

Response Body

Closes a permission nobody has spent yet. One that has already been used cannot be withdrawn: the verification it let through is the record of it.

Requires the verification:create permission.

Path Parameters

Response Body