Skip to main content
POST
Create a verification from a template

Authorizations

Authorization
string
header
required

Secret API key, created in the dashboard under Settings → API. Send it as Authorization: Bearer rk_secret_… from your server only. Publishable keys (pk_live_…) are for the native SDKs and reach the capture endpoints alone. An unknown key returns 401.

Path Parameters

slug
string
required

Template slug — lowercase [a-z0-9-].

Pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
Example:

"warehouse-intake"

Body

application/json

Body for POST /v1/link-templates/{slug}/verifications. Every field is optional and overrides the template: metadata merges key by key, the rest replace.

identification
string

The value the template asks the person for (customer number, claim id). With a connected database it also picks the row to compare against.

Required string length: 1 - 120
metadata
object

Your own key/value pairs. Merged over the template metadata; same key, body wins.

webhook_url
string<uri>

HTTPS URL that receives verification.created and verification.completed.

expires_in_seconds
integer

How long the link stays open. Replaces the template default.

Required range: 60 <= x <= 86400
notify_email
string<email> | null

Email that receives the result. null opts this verification out; absent uses the template, then your account default.

Maximum string length: 254
brand_slug
string

Brand profile to render instead of the template one.

Required string length: 2 - 40
Pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$

Response

Verification minted. capture_url is the link to send to the person.

A verification as your API key sees it. verdict appears once analysis finished; object_match, location_match and condition appear when you asked for them and the check ran. Your metadata is not echoed back: keep the id.

id
string
required
Pattern: ^vfy_[0-9A-HJKMNP-TV-Z]{26}$
status
enum<string>
required

Lifecycle state. pending → first capture flips to partially_captured → analysis sets the verdict and transitions to completed. Terminal: completed, expired, failed. abandoned is a side-branch off pending/partially_captured, reported by the capture screen via POST /v1/verifications/:token/progress when the end user leaves before finishing — NOT terminal: a later capture resurrects the row to partially_captured like any other.

Available options:
pending,
partially_captured,
completed,
expired,
failed,
abandoned
capture_url
string<uri>
required
created_at
string<date-time>
required
expires_at
string<date-time>
required
captures_count
integer
required
Required range: x >= 0
verdict
object

Verdict of a live capture. Branch on rial; signals says why when it is false, and unavailable when a check could not be completed.

location
object

Where the photo was taken, from the device. Absent for uploaded files and when the device reported no fix.

location_match
object

Whether the photo was taken at expected_location. verified within GPS tolerance; no_match somewhere else; ungeocoded when the address or the fix could not be resolved; rejected when the device reported a mock location.

object_match
object

Object-check result. Present when an object check was requested globally or on an image step. With step-only configuration the status is the worst step result and expected_object is omitted. Independent of the fraud verdict.

object_matches
object

Object-check results keyed by image step. Missing capture verdicts yield inconclusive; otherwise each value is the worst context result for the step, ignoring not_applicable when live evidence exists.

condition
object

Condition assessment. Present only when the verification was created with condition_aspects — the free-form tenant-defined aspect names (any language, any domain). score is the one-decimal average of aspect scores; label buckets it (>=7.5 good, >=5 fair, else poor). Independent of the fraud verdict.

video_analysis
object

Analysis of a video-step clip, sampled at one frame per second and run through the same checks a photo gets. Written asynchronously after capture — poll or use webhooks; absent until the worker has run.

ocr_primary
string
similar_photo
object

An earlier verification of yours whose photo matches this one. method: "phash": the perceptual hashes are within threshold (Hamming distance 0–64; 0 is bit-identical) — a re-upload. method: "embedding": the hashes differ but the photos are the same scene by embedding (cosine) and a geometric check confirmed it (inliers) — a screenshot or a crop. Present only when a match was found. It does not change rial: a legitimate re-submission and a recycled photo look the same — your reviewer decides.

answers
object
record_seal
object

Integrity seal over the verification record including answers. Present only when answers exist and sealing is on (seal !== false). The hash proves the stored answers have not changed — it does NOT claim they are true or sensor-attested; answers_provenance carries that distinction explicitly.