Finalize with a narrative
Attach a written narrative and close the case.
Authorizations
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
ULID with vfy_ prefix.
^vfy_[0-9A-HJKMNP-TV-Z]{26}$"vfy_01HXYZABCDEFGHJKMNPQRSTVWX"
Body
Body for POST /v1/verifications/:id/finalize. narrative is the claimant's written description of what the captures show.
1 - 2000Response
Verification closed. Response is the updated verification with narrative now present.
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.
^vfy_[0-9A-HJKMNP-TV-Z]{26}$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.
pending, partially_captured, completed, expired, failed, abandoned x >= 0Verdict of a live capture. Branch on rial; signals says why when it is false.
- Option 1
- Option 2
Where the photo was taken, from the device. Absent for uploaded files and when the device reported no fix.
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-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-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 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.
Screen-detection analysis of a video-step clip, sampled at one frame per second. Written asynchronously after capture — poll or use webhooks; absent until the worker has run.
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.
- Option 1
- Option 2