Skip to main content
POST
Issue a new verification token

Authorizations

rial_session
string
cookie
required

Dashboard / operator session cookie. Set by /v1/auth/google/callback after Google OAuth, JWT signed with the rotating rial-platform/session-signing HMAC. Read on every request the SPA makes with credentials: include. Browser-only — server-to-server callers use bearerApiKey instead.

Body

application/json

Body for POST /v1/verifications. All fields optional — sensible defaults: max_captures: 1, expires_in_seconds: 3600, signals_required: ["screen", "ai"]. Capture quantity comes as EITHER max_captures (N anonymous captures) OR steps (guided slots with key/description/min/max) — never both. context is what the analysis pipeline cross-references against the capture; metadata is opaque pass-through echoed back on every webhook event.

max_captures
integer
Required range: 1 <= x <= 20
steps
object[]
Minimum array length: 1
expires_in_seconds
integer
default:3600
Required range: 60 <= x <= 86400
signals_required
enum<string>[]
Minimum array length: 1
Available options:
screen,
ai,
reverse,
context,
depth
seal
boolean
default:true
mode
enum<string>
Available options:
verification,
audit
context
object
webhook_url
string<uri>
notify_email
string<email> | null
Maximum string length: 254
metadata
object
expected_location
string
Required string length: 1 - 300
expected_object
string
Required string length: 1 - 200
condition_aspects
string[]
Required array length: 1 - 6 elements
Required string length: 1 - 40
expected_info
object
brand_slug
string
Required string length: 2 - 40
Pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$

Response

Verification minted. Returns the canonical wire shape including the capture_url the tenant sends to the end-user.

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 }.

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.

verdict
object

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

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.

object_match
object

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

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.

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.