Submit a capture against the verification

Stage 3 of the upload flow (or stage 1 for inline-base64 payloads ≤ 6 MB). Two body shapes, discriminated by which field is present:

• inline: {image_base64, surface?, client_captured_at?} — the bytes ride in the request, capped at Lambda’s 6 MB sync-invoke limit.
• key_ref: {image_key, image_sha256, surface?, client_captured_at?} — image_key is the URL returned by /captures/upload-url; the handler reads bytes from S3 and verifies the hex image_sha256 matches before persisting.

Both shapes also accept an optional step_key naming which step of the verification’s steps this capture fills. It may reference an image step (any state, capacity permitting) or an upload step with remaining capacity — upload steps hold pre-existing content and are reachable by explicit key only, there is no keyless fallback into them. Omitting step_key lands the capture in the first image step with remaining capacity (legacy keyless clients: the pre-steps hosted SPA, the SDK worker). A key that doesn’t resolve to an evidence step with capacity — unknown, or naming a text step — is 400 unknown_step; a step already at its max is 409 step_full.

Side effects:

• Persists a Capture row atomically with capture-count + status transition guards.
• Emits verification.capture.persisted on the EventBridge bus. The per-capture analysis worker consumes it (today: ANALYSIS=stub; future: crosscheck).
• If this is the capture that fills the verification’s max_captures quota, the analysis worker may also write a final verdict and transition status to completed.

Attestation: if cf_turnstile_token is present and the verifier is configured, the token is validated server-side and persisted as an attestation field on the capture row. A failed verification is recorded as verdict: 'error' but the capture is still persisted (attestation is signal, not gate).

Returns: the updated verification snapshot (post-write state).

POST /v1/verifications/{token}/captures

Submit a capture against the verification

cURL

curl --request POST \
  --url 'https://platform-staging.get-rial.com/v1/verifications/{token}/captures?token=' \
  --header 'Content-Type: application/json' \
  --data '
{
  "image_key": "s3://rial-platform-evidence-staging-977916686093/vfy_01HXYZ/cap_01ABC",
  "image_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "surface": "hosted_link",
  "cf_turnstile_token": "0.<turnstile-response-token>",
  "step_key": "id_document"
}
'

201

{
  "id": "<string>",
  "capture_url": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z",
  "captures_count": 1,
  "config": {
    "max_captures": 10,
    "steps": [
      {
        "key": "<string>",
        "type": "image",
        "description": "<string>",
        "min": 1,
        "max": 2
      }
    ],
    "signals_required": [],
    "context": {
      "kind": "<string>",
      "summary": "<string>",
      "attributes": {}
    },
    "webhook_url": "<string>",
    "notify_email": "[e-mail]",
    "metadata": {},
    "expected_location": "<string>",
    "expected_object": "<string>",
    "condition_aspects": [
      "<string>"
    ]
  },
  "answers": {},
  "record_seal": {
    "algorithm": "sha256",
    "hash": "<string>",
    "covers": [],
    "answers_provenance": "user_declared"
  },
  "verdict": {
    "score": 0.5,
    "signals": {
      "screen_detection": {
        "screen_detected": true,
        "confidence": 0.5
      },
      "ai_detection": {
        "confidence": 0.5
      },
      "reverse_search": {
        "found_online": true,
        "match_count": 1
      },
      "depth": {
        "source": "<string>",
        "confidence": 0.5
      }
    }
  },
  "narrative": "<string>",
  "case_analysis": {
    "overall_risk_score": 0.5,
    "confidence": 0.5,
    "dimensions": {
      "cross_image_consistency": {
        "score": 0.5,
        "evidence": "<string>",
        "concerns": [
          "<string>"
        ]
      },
      "physical_plausibility": {
        "score": 0.5,
        "evidence": "<string>",
        "concerns": [
          "<string>"
        ]
      },
      "narrative_image_match": {
        "score": 0.5,
        "evidence": "<string>",
        "concerns": [
          "<string>"
        ]
      }
    },
    "uncertainty_areas": [
      "<string>"
    ],
    "model": "<string>",
    "rubric_version": 5,
    "consistency_level": 0.5,
    "analysis": [
      {
        "capture_id": "<string>",
        "screen": true
      }
    ],
    "text_analysis": "<string>"
  },
  "object_match": {
    "expected_object": "<string>"
  },
  "condition": {
    "score": 5,
    "aspects": [
      {
        "name": "<string>",
        "score": 5,
        "reasoning": "<string>"
      }
    ]
  },
  "progress": {
    "schema_version": 1,
    "elapsed_ms": 1,
    "updated_at": "2023-11-07T05:31:56Z",
    "step_index": 1
  }
}

Authorizations

token · string · query · required

Possession of the verification id in the URL path (/v1/verifications/:token/...) authenticates the SPA capture flow. No header — the id is the credential. ULIDs are large enough that existence-by-id is not a meaningful leak. Used for POST /captures/upload-url, POST /captures, GET /v1/verify/:token.

Path Parameters

token · string · required

Pattern: ^vfy_[0-9A-HJKMNP-TV-Z]{26}$

Example:

"vfy_01HXYZABCDEFGHJKMNPQRSTVWX"

Body

application/json

Option 1

Option 2

image_base64 · string · required

surface · string

cf_turnstile_token · string

step_key · string

Response

201

application/json

Capture persisted. Returns the updated verification — status will be partially_captured until the worker writes the verdict.

Canonical wire shape for a verification. narrative is present only after POST /v1/verifications/:id/finalize ran. verdict is present only after analysis completed. case_analysis is the structured Gemini multi-image rubric, embedded inline by the sync finalize path when analysis succeeded.

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

config · object · required

Tenant-supplied configuration baked into the token at issue time. Immutable after creation — changing config means issuing a new verification. steps is the normalized capture spec: requests that sent max_captures: N read back as a single anonymous step { key: "capture_1", min: N, max: N }.

Show child attributes

answers · object

Show child attributes

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.

Show child attributes

verdict · object

Aggregate verdict produced by the per-capture analysis pipeline. label is the human-readable bucket; score is the confidence in the verdict.

Show child attributes

narrative · string

Maximum string length: 2000

case_analysis · object

Structured output from the multi-image case-analysis worker (Gemini batch reasoning). Per-dimension scores 0..1 where 0 = nothing suspicious on that dimension and 1 = that dimension alone is grounds to reject. overall_risk_score aggregates with cross-dimensional reasoning, not a simple average.

Show child attributes

object_match · object

Object-check result. Present only when the verification was created with expected_object. Independent of the fraud verdict.

Show child attributes

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.

Show child attributes

progress · object

Latest funnel-progress snapshot reported via POST /v1/verifications/:token/progress. A snapshot, not an event log — each call overwrites the previous one. Operator-only; never present on the public projection.

Show child attributes