> ## Documentation Index > Fetch the complete documentation index at: https://docs.get-rial.com/llms.txt > Use this file to discover all available pages before exploring further. # List verifications > Newest first. Pass `next_cursor` back as `cursor` for the next page. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/verifications openapi: 3.1.0 info: title: rial API version: 0.1.0 description: 'Prove a photo is real. Base URL: https://api.rial.io' contact: name: rial-platform team url: https://github.com/Rial-ventures-Inc/rial-platform license: name: UNLICENSED — proprietary, internal use only servers: - url: https://api.rial.io description: Production security: [] tags: - name: Verifications description: >- Create, fetch, list, and finalize verifications. The core of the API — every tenant integration starts here. - name: Templates description: >- Publish, update, revoke and inspect link templates — the reusable capture links behind `/l/{token}` (a compact JWT carrying the org and template slugs; the legacy `/l/{org}/{slug}` keeps resolving). Callable with a secret key; each publish snapshots a versioned capture spec (GET-83). - name: Databases description: >- Create, update, inspect and synchronize tenant-scoped databases used by reusable verification templates. Callable with a dashboard session or secret API key. paths: /v1/verifications: get: tags: - Verifications summary: List verifications description: Newest first. Pass `next_cursor` back as `cursor` for the next page. parameters: - schema: type: integer minimum: 1 maximum: 100 description: Soft cap; adapters may return fewer. example: 20 required: false name: limit in: query - schema: type: string description: Opaque cursor from a previous response. Treat as a black box. required: false name: cursor in: query - schema: type: string enum: - pending - partially_captured - completed - expired - failed - abandoned description: Exact match on verification status. required: false name: status in: query - schema: type: string enum: - verified - suspicious - failed description: Exact match on `verdict.label`. Pending verifications never match. required: false name: verdict in: query - schema: type: string enum: - screen_detected - ai_generated - context_mismatch - reverse_search_match description: >- Exact match on `verdict.reason_code`. Verifications with no verdict, or a `verified` verdict, never match. required: false name: reason_code in: query - schema: type: string description: Inclusive lower bound on `created_at`. ISO 8601 date or date-time. example: '2026-07-01T00:00:00.000Z' required: false name: from in: query - schema: type: string description: Inclusive upper bound on `created_at`. ISO 8601 date or date-time. example: '2026-07-31T23:59:59.999Z' required: false name: to in: query - schema: type: string description: >- Exact match against `config.metadata[]`. Repeatable with different keys (ANDed). Literal param name is `metadata.` followed by the metadata key, e.g. `metadata.client_label=estancia-la-julia`. example: estancia-la-julia required: false name: metadata. in: query - schema: type: string description: >- Exact match against `ocr.primary` of any capture on the verification. example: AB123CD required: false name: caravana in: query - schema: type: string enum: - verification - audit description: >- Provenance split. `audit` matches `config.mode = audit` or an upload-only step spec (link-template audits that never stamp `mode`). `verification` is everything else — live capture, including rows that omit `mode`. required: false name: mode in: query responses: '200': description: >- A page of verifications matching the filters. `next_cursor` absent means no more pages. content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/DeveloperVerification' next_cursor: type: string required: - items example: items: - id: vfy_01HXYZABCDEFGHJKMNPQRSTVWX status: completed capture_url: https://verify.rial.io/v/vfy_01HXYZABCDEFGHJKMNPQRSTVWX created_at: '2026-09-16T19:06:57.718Z' expires_at: '2026-09-16T20:06:57.718Z' captures_count: 1 verdict: rial: false signals: - screen_detected object_match: status: match expected_object: car location_match: status: verified expected_location: Av. Córdoba 5635, Buenos Aires distance_m: 23 condition: score: 8 label: good aspects: - name: paint score: 8 reasoning: Even, no visible damage. - id: vfy_01HXYZABCDEFGHJKMNPQRSTVWX status: pending capture_url: https://verify.rial.io/v/vfy_01HXYZABCDEFGHJKMNPQRSTVWX created_at: '2026-09-16T19:06:57.718Z' expires_at: '2026-09-16T20:06:57.718Z' captures_count: 0 next_cursor: eyJwayI6ICJWRlkjdmZ5XzAxLi4uIiwic2siOiAiTUVUQSJ9 '400': description: >- An explicit search filter (`status`, `verdict`, `reason_code`, `from`, `to`, `mode`) was malformed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: invalid_request message: Request body failed validation fields: - path: config.max_captures message: must be ≤ 20 '401': description: No valid session / API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: unauthorized message: Missing or invalid API key security: - bearerApiKey: [] components: schemas: DeveloperVerification: type: object properties: id: type: string pattern: ^vfy_[0-9A-HJKMNP-TV-Z]{26}$ status: type: string enum: - pending - partially_captured - completed - expired - failed - abandoned description: >- 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. capture_url: type: string format: uri created_at: type: string format: date-time expires_at: type: string format: date-time captures_count: type: integer minimum: 0 verdict: anyOf: - type: object properties: rial: type: boolean description: True when no check tripped. signals: type: array items: type: string enum: - screen_detected - ai_detected - found_online description: >- A check that tripped: `screen_detected` (photo of a screen), `ai_detected` (AI-generated), `found_online` (already published). description: The checks that tripped. required: - rial - signals description: >- Verdict of a live capture. Branch on `rial`; `signals` says why when it is false. - type: object properties: signals: type: array items: oneOf: - type: object properties: type: type: string enum: - screen_detected required: - type - type: object properties: type: type: string enum: - ai_detected confidence: type: number minimum: 0 maximum: 1 required: - type - confidence - type: object properties: type: type: string enum: - found_online required: - type description: A check that tripped on an audited file. required: - signals description: >- Verdict of an audit (`mode: "audit"`, a file that already existed). No `rial`: with no live capture behind it, the checks are reported for you to weigh. Empty `signals` means nothing tripped. location: type: object properties: lat: type: number lng: type: number accuracy_m: type: number minimum: 0 derived_from: type: string enum: - exif - live - last_known_session - last_known_system - last_known_persisted age_ms: type: integer minimum: 0 place: type: string required: - lat - lng - accuracy_m description: >- Where the photo was taken, from the device. Absent for uploaded files and when the device reported no fix. location_match: type: object properties: status: type: string enum: - verified - no_match - ungeocoded - rejected - not_applicable expected_location: type: string observed_location: type: string expected_point: type: object properties: lat: type: number lng: type: number required: - lat - lng observed_point: type: object properties: lat: type: number lng: type: number required: - lat - lng distance_m: type: number minimum: 0 threshold_m: type: number minimum: 0 gps_accuracy_m: type: number minimum: 0 geocode_ref: type: string reason: type: string required: - status description: >- 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: type: object properties: status: type: string enum: - match - mismatch - inconclusive expected_object: type: string required: - status description: >- 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: type: object additionalProperties: type: object properties: status: type: string enum: - match - mismatch - inconclusive expected_object: type: string required: - status - expected_object description: >- Object-check result for one image step, including its expected object. description: >- 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: type: object properties: score: type: number minimum: 0 maximum: 10 label: type: string enum: - good - fair - poor aspects: type: array items: type: object properties: name: type: string score: type: number minimum: 0 maximum: 10 reasoning: type: string required: - name - score - reasoning description: >- One scored aspect of the condition assessment. `name` echoes the free-form tenant-defined aspect from `condition_aspects` verbatim — any language, any domain, no fixed vocabulary. `score` is 0..10 with one decimal; `reasoning` is a one-or-two-sentence visual justification. steps: type: object additionalProperties: type: object properties: score: type: number minimum: 0 maximum: 10 label: type: string enum: - good - fair - poor aspects: type: array items: type: object properties: name: type: string score: type: number minimum: 0 maximum: 10 reasoning: type: string required: - name - score - reasoning description: >- One scored aspect of the condition assessment. `name` echoes the free-form tenant-defined aspect from `condition_aspects` verbatim — any language, any domain, no fixed vocabulary. `score` is 0..10 with one decimal; `reasoning` is a one-or-two-sentence visual justification. required: - score - label - aspects description: >- 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. description: >- Condition results keyed by photo step. Each uses only that step’s photos and its rubric, falling back to the shared rubric. The aggregate averages all assessed aspect scores. required: - score - label - aspects description: >- 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: type: object properties: capture_id: type: string frames_extracted: type: integer minimum: 0 frames_analyzed: type: integer minimum: 0 screen: type: object properties: screen_detected: type: boolean confidence: type: number minimum: 0 maximum: 1 decided_at_ms: type: integer minimum: 0 required: - screen_detected - confidence - decided_at_ms description: >- Worst-case across sampled frames: one flagged frame flags the clip; `decided_at_ms` is the clip position of the deciding frame. analyzed_at: type: string format: date-time required: - capture_id - frames_extracted - frames_analyzed - analyzed_at description: >- 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. ocr_primary: type: string answers: type: object additionalProperties: type: object properties: values: type: array items: type: string address: type: object properties: street: type: string minLength: 1 maxLength: 200 number: type: string minLength: 1 maxLength: 200 neighborhood: type: string minLength: 1 maxLength: 200 complement: type: string maxLength: 200 city: type: string minLength: 1 maxLength: 200 region: type: string minLength: 1 maxLength: 200 postal_code: type: string maxLength: 200 required: - street - number - neighborhood - city - region - postal_code additionalProperties: false value: type: string maxLength: 2000 answered_at: type: string format: date-time required: - value - answered_at description: >- One answered text step. `value` is USER-DECLARED — typed by the person capturing; unlike live-captured content, it is never sensor-attested. Potential PII: it rides the operator/developer contracts and the webhook only, never OG cards or third-party public surfaces. record_seal: anyOf: - type: object properties: algorithm: type: string enum: - sha256 hash: type: string minLength: 64 maxLength: 64 covers: type: array items: type: string enum: - record - answers answers_provenance: type: string enum: - user_declared required: - algorithm - hash - covers - answers_provenance - type: object properties: algorithm: type: string enum: - sha3-512 hash: type: string minLength: 128 maxLength: 128 covers: type: array items: type: string enum: - record - answers answers_provenance: type: string enum: - user_declared required: - algorithm - hash - covers - answers_provenance description: >- 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. required: - id - status - capture_url - created_at - expires_at - captures_count description: >- 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`. ErrorResponse: type: object properties: error: type: object properties: code: type: string message: type: string fields: type: array items: type: object properties: path: type: string message: type: string required: - path - message required: - code - message required: - error description: >- Uniform error envelope. `code` is the stable string SDKs branch on (`invalid_request`, `unauthorized`, `not_found`, `expired`, `step_full`, `unknown_step`, `steps_incomplete`, `already_finalized`, `too_many_requests`, `storage_unavailable`, `internal_error`). `fields` is only present on `invalid_request` validation failures. securitySchemes: bearerApiKey: type: http scheme: bearer bearerFormat: rk_secret_ description: >- 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. ````