API reference
Base URL: https://verify.zetaid.com/api/v1 — the verification portal
of the ZetaID cloud. If we gave you another host (your own branded host, or
another region), use that one; the paths are the same.
Authentication: your API key in the X-SDK-Key header. Requests from a
web page (with an Origin header) are refused.
Format: JSON in and out, UTF-8. Times are RFC 3339 in UTC.
The OpenAPI description of these calls and the webhooks: /openapi.yaml.
Create a verification
Section titled “Create a verification”POST /api/v1/verifications
| Body field | Type | Required | |
|---|---|---|---|
return_url | string (URL) | no | Where the person goes when done. Nothing is added to it. |
extra_data | object | no | Your own reference; returned in webhooks and GET. No personal data. |
flow | string[] | no | Steps for this verification only (default: the key’s flow). |
module_overrides | object | no | Per-module settings, e.g. {"form_data": {"values": {…}, "locked": […]}}. |
Body size: at most 64 KB.
201 Created
| Field | Type | |
|---|---|---|
verification_id | string (UUID) | The verification’s id. |
url | string (URL) | The link for the person. |
flow | string[] | The steps it will go through. |
due_at | string (time) | The link works until then. |
expires_at | string (time) | The captured images are deleted then. |
Errors: 401 SDK_KEY_INVALID, 402 CREDITS_EXHAUSTED,
403 SERVER_SIDE_ONLY, 413 BODY_TOO_LARGE, 422 FLOW_INVALID,
422 RELYING_PARTY_INACTIVE, 502 BACKEND_UNREACHABLE,
503 SYSTEM_TEMPORARILY_UNAVAILABLE, 500 GENERATE_FAILED.
Read a verification
Section titled “Read a verification”GET /api/v1/verifications/{verification_id}
200 OK
| Field | Type | |
|---|---|---|
verification_id | string | |
status | string | See statuses. |
terminal | boolean | The checks have finished. |
reason_code | string | null | Why it ended this way (e.g. DOCUMENT_EXPIRED, COMPLETION_TIMEOUT). |
export | object | null | The result (The result); null before the checks ran and after personal-data retention. |
extra_data | object | null | What you sent at creation. |
created_at | string (time) | |
updated_at | string (time) | Last status change. |
Errors: 401 SDK_KEY_INVALID, 403 SERVER_SIDE_ONLY,
404 VERIFICATION_NOT_FOUND (unknown, or another organization’s),
502 BACKEND_UNREACHABLE.
Errors
Section titled “Errors”Every error has the same shape:
{ "error": { "code": "FLOW_INVALID", "message": "optional detail" } }Branch on code; message is for logs. All codes: Errors.