Skip to main content

​
What this API does

You mint a verification against your tenant account, get back a capture_url, and send that link to your end-user (an insurance claimant, a marketplace seller, whoever needs to prove a photo is real). They open the link on their phone, capture the photos you asked for, and the verification’s status moves through:
Once completed, the verification carries a verdict (verified / suspicious / failed) built from on-device signals — screen-recapture detection and AI-generation detection — plus the captured images themselves. You can also attach a claimant narrative and finalize the case for deeper batch analysis (Case Analysis).

​
Base URLs

​
Authentication

Server-to-server calls use a tenant-scoped API key, format pk_live_<ulid>, sent as a bearer token:
A rial operator mints your API key today. The plaintext key is returned once, at mint time; only its hash is stored afterwards. If you’re integrating and don’t have a key yet, ask your rial contact.
There’s a second, more privileged key type (rk_secret_…) that must never leave your servers — see Authentication for the full breakdown of both key types, plus environments and how the same key authenticates the mobile SDKs. The link you hand your end-user needs no key at all: possession of the verification id in the URL is the credential for the capture flow (same trust model as a Stripe payment-intent client_secret) — see the API reference for the full set of auth modes.

​
Quickstart: zero to a verification

1

Issue a verification

POST /v1/verifications with either max_captures: N (N anonymous shots) or a steps array for guided slots. This example asks for 3 photos and requests both fraud signals:
The response includes id (vfy_<ulid>) and capture_url — a link on verify.get-rial.com.
2

Share the capture link

Send capture_url to your end-user however you’d send any link — SMS, WhatsApp, email. No app install, no account: it opens directly in their mobile browser.
3

The claimant captures photos

The hosted capture flow walks them through each requested shot, runs the on-device fraud signals, and uploads directly to storage. You don’t need to build any of this — it’s rial’s hosted page at the capture_url you already have.
4

Read back the result

A completed verification that failed a fraud check looks like this:
reason_code names which signal drove the label — here, the capture looked like a screen recapture rather than a live photo. See Verdicts for the full signal set and what each one checks.If the response doesn’t contain a verdict object yet, analysis is still processing — poll again.
5

Optional: skip polling with a webhook

Set webhook_url when you create the verification (as in the example above) and rial POSTs to it instead of making you poll — deliveries are HMAC-signed with your tenant’s webhook secret so you can verify they actually came from rial.
6

Optional: finalize for Case Analysis

If you collect a written narrative from the claimant, attach it and close the case for deeper multi-image cross-reasoning:

​
Next steps

Authentication

Both key types, environments, and how the SDKs authenticate.

Verdicts

What status and verdict mean, and what each signal checks.

Kotlin SDK

Capture natively on Android instead of hosting the link.

API reference

Every endpoint, request/response schema, and error shape — generated straight from the API’s own OpenAPI document.