How do I call the VerifyAI damage inspection API?

Get an API key from the sandbox, then POST an image (multipart file or base64 string) and a damage policy ID to /api/v1/verify, authenticating with an X-API-Key header carrying your vai_ key. You get back a structured JSON verification object with a top-level is_compliant decision, a confidence score, an outcome category, machine-readable violation reasons, and a damage grade on the AIAG / K1–K5 scale.

What does the damage inspection API return?

A verification object you can branch on in code: an id, a status, a boolean is_compliant decision, a 0-to-1 confidence score, an outcome category, an array of violation_reasons naming each failed criterion, a human-readable feedback string safe to show an end user, and a severity grade on the AIAG / K1–K5 scale. For returns, a before/after delta isolates new damage from pre-existing wear.

Is there a free way to test the damage inspection API?

Yes. The sandbox gives you $5 in credit with no credit card, for evaluating single-photo API checks. Sign up, create a key in the dashboard, and send your first photo in a few minutes. Nothing needs to be installed to try it: a single curl request with an image file and a policy ID is a complete test of the endpoint.

What image formats and size limits does the verify endpoint accept?

The endpoint accepts JPEG, PNG, and WebP images up to 10 MB. You can send the image either as multipart/form-data, which is the better fit for a live camera upload from a mobile app, or as application/json with a base64 string. A data URL prefix is stripped automatically, so both a raw base64 string and a full data URL work in the image field.

How do I safely retry a damage verification?

Send an Idempotency-Key header with the original request and reuse the same key on the retry. An identical retry returns the original cached response instead of running and billing a second verification, which matters when a mobile network drops mid-flight or an app retries on resume. Reusing a key with a different request body is rejected, so each key stays bound to one payload.

What errors can the verify endpoint return?

400 for missing fields, invalid JSON, an oversized image, or an unknown policy ID; 401 for a missing or invalid API key; 403 when the key is not valid for VerifyAI or has no active subscription; 409 when a request with the same idempotency key is still in flight; 422 when an idempotency key is reused with a different body; 429 for a rate limit or monthly cap; 500 when processing fails; and 503 when authentication is unavailable.

AI Damage Inspection API Quickstart: From Photo to Grade in 5 Minutes

To go from a vehicle photo to a graded damage verdict: create a sandbox account and copy a vai_ API key, POST the image plus a damage policy ID to /api/v1/verify with an X-API-Key header, and read the structured verification object that comes back — is_compliant, a confidence score, an outcome category, the violation reasons behind it, and an AIAG / K1–K5 damage grade. Two optional steps finish the loop: a before/after delta that isolates new damage from pre-existing wear, and an exported PDF condition report.

That's the whole walkthrough in one paragraph. The rest of this page is the same five steps with the request and response shapes filled in. If you've read what a photo verification API is and want to actually wire one up, start here.

In brief

Auth is a single X-API-Key header carrying a vai_ key. There is no OAuth dance and no SDK requirement — curl is enough to test the endpoint.
One endpoint does the work: POST /api/v1/verify, taking an image and a policy ID.
Images can be multipart (best for live camera capture) or base64 JSON; JPEG, PNG, or WebP, up to 10 MB.
The response is a decision, not a description: branch on is_compliant or on the violation_reasons array.
Retries are safe if you send an Idempotency-Key — an identical retry returns the cached response instead of billing twice.
The sandbox is $5 of credit with no card, for evaluating the single-photo API.

A note on positioning: VerifyAI leads with parking compliance, and vehicle damage inspection is a secondary capability — but the API surface is the same, so this walkthrough applies to any policy.

Vehicle appraisal pricing: $2.00 per completed appraisal, including up to 16 original photos and detailed damage analysis. Single-photo API checks are a separate product and do not include the appraisal workflow. See the offer and arrange production access.

Step 1 — Get an API key

You get a key by creating a sandbox account; the key is issued in the dashboard and needs no approval step. The sandbox comes with $5 in credit and no credit card — use it to evaluate individual API checks. Export it so the examples below work:

bash

export VERIFY_API_KEY="vai_..."

Keys are managed from the dashboard and rotate independently — see authentication and the API keys reference for scoping and rotation.

Step 2 — Send a photo to the verify endpoint

A damage inspection is one POST to /api/v1/verify carrying two things: the image and a reference to the damage policy that defines what counts as damage. Here's a base64 example:

bash

curl https://verify.switchlabs.dev/api/v1/verify \
  -H "X-API-Key: $VERIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "policy": "vehicle-damage-inspection-policy",
    "image": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  }'

For a live camera capture from a mobile app, send multipart/form-data with the file instead of base64 — it avoids the roughly one-third size inflation base64 adds.

Field	Where	Required	What it is
`X-API-Key`	Header	Yes	Your `vai_` key. This is the only auth header the endpoint reads.
`Content-Type`	Header	Yes	`multipart/form-data` or `application/json`.
`Idempotency-Key`	Header	No	Opaque string. An identical retry returns the cached response.
`image`	Body	Yes	File or base64 string. JPEG, PNG, or WebP, up to 10 MB. A `data:` prefix is stripped for you.
`policy`	Body	Yes	The policy ID to evaluate against — built-in or one of your own.
`metadata`	Body	No	Free-form key/values persisted with the verification (vehicle ID, rental ID, GPS).
`include_image_data`	Body	No	Returns the base64 image in the response for audit capture. Defaults to `false`.

The policy is policy-as-code — an editable ruleset of criteria like "no body damage," "no broken glass," "no missing parts," and "vehicle clearly in frame," each with a severity. Start from the built-in damage policy or a template and tune it to your SOP; the custom policies guide covers authoring your own. The full request/response contract is in the verify endpoint reference.

Step 3 — Read the structured response

The response is a machine-readable verdict your code branches on — there is no human review step and nothing to poll:

json

{
  "id": "ver_8x92m4k9",
  "status": "success",
  "is_compliant": false,
  "confidence": 0.94,
  "policy": "vehicle-damage-inspection-policy",
  "category": "damage_detected",
  "violation_reasons": ["body_damage"],
  "feedback": "Dent on rear driver door.",
  "grade": "K3"
}

Field	Type	What to do with it
`id`	string	Verification ID, prefix `ver_`. Store it — it's your handle for the audit log.
`status`	string	`success` if the verification ran, `error` if processing failed.
`is_compliant`	boolean	The top-level pass/fail. This is the field most integrations branch on.
`confidence`	number	0–1 score. Route the low end to human review rather than auto-charging.
`category`	string	Outcome bucket for the matched result.
`violation_reasons`	string[]	Machine-readable IDs, one per failed criterion — use these to drive workflow, not the prose.
`feedback`	string	Human-readable explanation, safe to show an end user.
`grade`	string	Severity on the AIAG / K1–K5 scale.

Your code reads is_compliant (or the failed violation_reasons) and decides what to do — flag the vehicle, open a damage record, or pass it through. If you're new to the grades, the AIAG & K1–K5 explainer and the glossary entry break them down. How verifications work documents the object in full.

When a call fails

Every failure is an HTTP status you can branch on, and each one has exactly one sensible response:

Status	Reason	What to do
400	Missing fields, invalid JSON, image too large, unknown policy ID	Fix the request. Retrying unchanged will fail again.
401	Missing or invalid API key	Check the `X-API-Key` header and the key's state.
403	Key not valid for VerifyAI, or no active subscription	Check the account, not the code.
409	A request with the same `Idempotency-Key` is still in flight	Wait and re-read; do not issue a new key.
422	`Idempotency-Key` reused with a different body	Generate a fresh key for the new payload.
429	Rate limit or monthly usage cap	Back off using the `Retry-After` header — see rate limits.
500	Verification processing failed	Retry with the same idempotency key.
503	Authentication service unavailable	Retry — see handling retries.

Every response also carries an X-Request-Id; log it, because it's the first thing support will ask for.

Step 4 — Compute a before/after delta for returns

A before/after delta is what separates new damage from wear that was already there: you capture a baseline at check-out and a second set at return, and the API compares them. That comparison, not the return photo alone, is the persuasive part of a damage dispute.

Capture a baseline at check-out and a second photo at return, and request a before/after delta — the API isolates new damage from pre-existing wear, so you're not arguing about a scratch that was always there. The glossary entry defines the term, and rental return verification shows where it sits in the workflow.

Step 5 — Export a PDF condition report

A PDF condition report packages the baseline, the delta, and the grade into one document you can attach to a chargeback response or hand to a customer. It's a single call — no template work on your side.

For a representment or a customer-facing record, see the PDF condition reports guide, and chargeback defense for assembling the surrounding evidence package.

Capture without slowing the counter

You don't have to staff the inspection. Self-inspection links let the renter photograph the vehicle from their own phone, producing a customer-acknowledged baseline — see self-inspection links for how that flow works alongside the API.

Next steps

That's the full loop: key → verify → read grade → delta → PDF. From here:

Go deeper on the API: the quickstart and verify endpoint reference cover auth, errors, and the complete schema; first verification walks the very first call line by line.
Pick an SDK: REST for anything, the Python SDK for backend pipelines, or React Native if the capture happens on a phone.
Get results pushed to you: HMAC-signed webhooks mean you don't poll for verification results.
See the use case end to end: vehicle damage inspection, or car rental for the industry view.
Model the cost: single-photo API pricing applies to this endpoint. Complete vehicle appraisals are a separate workflow at $2.00 per completed appraisal, including up to 16 photos and detailed analysis.

On compliance claims

VerifyAI is GDPR-aligned, with a SOC 2 audit in progress — not yet SOC 2 certified. See security and GDPR for the current status.

Get your API key and grade your first photo free — $5 sandbox credit, no card required.

Get in Touch