Quickstart: verify your first photo with the Rial API

Base URL: https://api.rial.io

Get an API key

Dashboard → Settings → API → create a key. Copy it once; it’s not shown again.

export RIAL_API_KEY=rk_secret_...

Create a verification

curl https://api.rial.io/v1/verifications \
  -H "Authorization: Bearer $RIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "max_captures": 1 }'

{ "id": "vfy_01H...", "capture_url": "https://verify.rial.io/v/...", "status": "pending" }

Keep the id: it is how you find this verification later. Send capture_url to the person. No app, no account: it opens in their phone’s browser and walks them through the photo.

Read the verdict

curl https://api.rial.io/v1/verifications/vfy_01H... \
  -H "Authorization: Bearer $RIAL_API_KEY"

{
  "status": "completed",
  "verdict": { "rial": true, "signals": [] }
}

rial is what you branch on. When it is false, signals says why: screen_detected, ai_detected or found_online. No verdict yet means analysis is still running.

Don’t poll. Pass "webhook_url": "https://your.app/rial" when creating the verification and Rial POSTs verification.created and verification.completed to that URL, each with your metadata so you can route it. Retries on failure. Treat the event as a notification: confirm with GET /v1/verifications/{id} before you act on it.

Ask for more than one photo

Each image step can say what must appear in it and what condition to assess.

{
  "steps": [
    {
      "key": "front",
      "label": "Front",
      "type": "image",
      "description": "Please take a photo of the front of your 2021 Toyota Corolla",
      "expected_object": "2021 Toyota Corolla",
      "condition_aspects": ["paint", "bumper", "headlights"]
    },
    {
      "key": "plate",
      "label": "License plate",
      "type": "image",
      "description": "Please take a photo of the rear license plate of your Corolla",
      "expected_object": "license plate"
    },
    {
      "key": "odometer",
      "label": "Odometer",
      "type": "image",
      "description": "Please take a photo of the dashboard with the odometer reading visible",
      "expected_object": "car odometer"
    },
    {
      "key": "mileage",
      "label": "Mileage",
      "type": "text",
      "description": "Type the mileage shown on the odometer"
    }
  ],
  "expected_location": "Av. Córdoba 5635, Buenos Aires"
}

Have the photo already? See Audits. expected_object rejects a photo of something else. condition_aspects scores each aspect 0 to 10 with a one-line reason. expected_location checks the photo was taken there. All three come back as separate fields next to the verdict — see Verdicts. description is the instruction the person reads on their phone, so write it as one. label is the short name of the step in the results. The same shape works for a home claim:

{
  "steps": [
    {
      "key": "damage", "label": "Water damage", "type": "image",
      "description": "Please take a photo of the water damage on your kitchen ceiling",
      "expected_object": "kitchen ceiling",
      "condition_aspects": ["water stains", "cracks"]
    },
    {
      "key": "meter", "label": "Water meter", "type": "image",
      "description": "Please take a photo of your water meter showing the reading",
      "expected_object": "water meter"
    }
  ],
  "expected_location": "Av. Córdoba 5635, Buenos Aires"
}

Reuse it: publish a template

Same steps, published once, one permanent link you can send forever.

curl https://api.rial.io/v1/link-templates \
  -H "Authorization: Bearer $RIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "slug": "car-intake", "name": "Car intake", "steps": [ ... ] }'

{ "slug": "car-intake", "public_url": "https://verify.rial.io/l/...", "status": "active" }

Every person who opens public_url gets their own verification. Same thing from the terminal: rial templates apply car-intake.json — see CLI.

One link for one person

When you already know who the link is for, mint a single-use verification from the template. The body is optional and overrides the template for that one verification: metadata merges, the rest replace.

curl https://api.rial.io/v1/link-templates/car-intake/verifications \
  -H "Authorization: Bearer $RIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "identification": "POL-001", "webhook_url": "https://your.app/rial", "metadata": { "claim_id": "CLM-9912" } }'

{ "id": "vfy_…", "status": "pending", "capture_url": "https://verify.rial.io/v/vfy_…", "expires_at": "…" }

Send capture_url to that person. identification is what the template asks for; with a connected database it also picks the row to compare against.

Verdicts

What every field means.

API reference

Every field you can send.

Start

Results

Quickstart

Ask for more than one photo

Reuse it: publish a template

One link for one person

Verdicts

API reference

​Ask for more than one photo

​Reuse it: publish a template

​One link for one person

Verdicts

API reference

Ask for more than one photo

Reuse it: publish a template

One link for one person