API Reference

Veridia exposes a small REST API. Three endpoints. JSON in, JSON out. No SOAP, no GraphQL, no XML.

Base URL

https://api.xxuxe.online

All requests must use HTTPS. HTTP requests are rejected.

Endpoints overview

Method	Path	Purpose
POST	/v1/verify/init	Start a verification, get presigned upload URLs
POST	/v1/verify/submit	After uploads, kick off the ML pipeline
GET	/v1/verify/:id	Poll verification status / fetch verdict
GET	/health	Liveness check (no auth required)

The widget uses these endpoints under the hood. You only call them directly when you're building a server-side flow or a custom mobile client.

Authentication

Every endpoint (except /health) requires a bearer token:

Authorization: Bearer qv_pub_FJJWXMA2RN2XPRDK6YJX4KTVD0XSQHW9

Two key types exist:

Type	Prefix	Where to use
Publishable	qv_pub_*	Browser, widget, public clients
Secret	qv_sec_*	Server-side only — fetches verdicts, verifies webhooks

Full details: Authentication.

Versioning

The API is versioned in the URL path: /v1/.... Breaking changes get a new version path (/v2/...). The current version stays available for at least 12 months after a successor ships.

Non-breaking additions (new optional fields, new endpoints) happen on /v1 without notice.

Request format

All POST bodies are JSON:

POST /v1/verify/init HTTP/1.1
Host: api.xxuxe.online
Authorization: Bearer qv_pub_...
Content-Type: application/json

{
  "userRef": "customer-12345",
  "country": "PY",
  "documentType": "dni"
}

Response format

JSON responses include a requestId you should log. When something goes wrong, that's how support traces the issue:

{
  "verificationId": "vf_AG07CDWRRFQV4T05ZXG2",
  "uploads": { ... },
  "expiresAt": 1714604000
}

Error responses use a consistent shape:

{
  "error": "invalid_body",
  "message": "Request body failed validation",
  "requestId": "9f511d92ac11236d-SJC",
  "detail": {
    "fieldErrors": {
      "country": ["expected 2 characters"]
    }
  }
}

The X-Request-Id response header carries the same value, so you can correlate even when JSON parsing fails.

Latency expectations

Operation	Typical	P99
/v1/verify/init	<400ms	<1.2s
/v1/verify/submit	<2.7s	<5s
/v1/verify/:id (during processing)	<150ms	<400ms

The /submit endpoint is the slow one — it runs OCR, dispatches to the ML backend, and waits for an initial response. The actual ML pipeline finishes asynchronously; poll /v1/verify/:id for the verdict.

Rate limits

Default rate limits per tenant:

Endpoint	Requests / minute
/v1/verify/init	60
/v1/verify/submit	30
/v1/verify/:id	600

Need higher limits? Contact support — we can lift them per-tenant.

When you hit a limit, the response is 429 Too Many Requests with a Retry-After header.

CORS

The API allows cross-origin requests from any origin listed in your key's allowed origins in the dashboard. Preflight (OPTIONS) requests are cached for 10 minutes.

Errors

All error responses follow the same shape. See Errors for the full catalog of error codes you might receive.

Where to next

• Authentication — keys, environments, security
• POST /v1/verify/init — start a verification
• POST /v1/verify/submit — submit captured images
• GET /v1/verify/:id — fetch the verdict
• Errors — error code reference
• Rate limits — limits and quotas