Integration guide

The flow in five steps

Verify connectivity

GET /version with your Api-Key. It must return 200. Check the status code, not the body. If it fails, the problem is URL, network or proxy — there is nothing to debug on the API side yet.

Prepare the capture

A photo of the document, well lit, without glare, with all four borders inside the frame. Base64 without the data: prefix.

Send the front

POST /front with info and image. Keep the returned uuid: it is the transaction identifier and the link to the back.

Send the back (if the template has one)

If the front returned hasBackSide: true, call POST /back with the same info, the back image, and the front’s uuid as relatedUuid.

Decide with the rule in the positive

Front: 200 + "Operation end successfully." + id !== "unknown". Back: additionally frontBackTemplateValidation === true, then review crossMatchConfidence. Details in the introduction.

The request body

Field	Applies to	What it does
`info`	both	Required. Your reference, 2–256 characters, echoed back verbatim.
`image`	both	Required. The capture in base64, no `data:` prefix.
`relatedUuid`	`/back` only	The front’s `uuid`. Required on `/back`, forbidden on `/front`.
`documentId`	`/front`	A template hint (e.g. `VU-ARG-ID-04`): faster, narrower inference.
`possibleCountries`	`/front`	Narrows inference to a list of ISO country codes.
`antiSpoofingDocument`	`/front`	Adds `security.*` blocks: screen recapture, photocopy, tampering signals on the document itself.
`antiSpoofingFaceInDocument`	`/front`	Adds `face.isSpoofing` for the portrait printed on the document.
`strictBorderMode`	`/front`	Rejects captures where the document borders are cut off.
`logAnonymity`	both	Asks the service not to persist personal data in its logs.
`events`	both	Adds the internal pipeline trace. Diagnostics only.

Never send relatedUuid in /front. That field belongs to /back only; including it in /front produces a deterministic 500. And despite what the /back error message suggests, documentId does not replace relatedUuid — only relatedUuid links the transaction.

Image requirements

Aspect	Requirement
Minimum resolution	480 × 480 px — below that, `400`.
Maximum useful resolution	~1920 px on the long side — larger images are downscaled internally; sending more only adds upload time.
Framing	The whole document, all four borders visible, no fingers over data.
Compression	JPEG quality ≥ 90. Aggressive compression degrades OCR.
Encoding	Standard base64, no `data:` prefix, no line breaks.

To convert an image to base64:

[Convert]::ToBase64String([IO.File]::ReadAllBytes('C:\path\front.jpg')) | Set-Clipboard

base64 -w0 front.jpg

base64 -i front.jpg | pbcopy

The template catalog

Endpoint	Returns
`GET /listTemplates`	A plain array of every supported template id.
`GET /listTemplatesByCountry`	The same catalog grouped by country.
`GET /{templateId}/details`	Which VIZ fields, MRZ, barcode and face that template carries.
`GET /{templateId}/images`	Anonymized sample images (`front`/`back` are 1-element arrays).

Template ids follow VU-<ISO3>-<TYPE>-<NN> — ID national id, IDF foreigner id, PA passport, DL driver’s license.

GET /{templateId}/details is the authoritative source for which fields to expect in viz — the set varies per template. Wire your parser against the template’s details, not against one sample response.

A Bad relatedUuid error immediately after a successful front can be replication lag: wait one second and retry once. If it persists, the relatedUuid is genuinely wrong.

Timeouts and retries

Situation	Policy
Read timeout	≥ 30 s — OCR plus validations take time.
Sporadic `5xx`	Retry with backoff, maximum 2 attempts.
Deterministic `500` (`relatedUuid` on `/front`)	Do not retry: fix the request.
`400` / `401` / `404` / `422`	Do not retry: fix the capture, credential, route or body.

Responses weigh ~1 MB. They embed the normalized document, the cropped face and — with MRZ — the MRZ strip, all in base64. Size your buffers and do not log raw response bodies.

Before going to production

GET /version returns 200 from your production connectivity.
Your acceptance condition requires 200 and message: "Operation end successfully." and id !== "unknown" (front), plus frontBackTemplateValidation === true (back).
You tested a mismatched back and your system rejects it.
You tested a photo with no document and your system asks for a new capture instead of accepting empty fields.
Your captures are ≥ 480 × 480 px and the base64 has no data: prefix.
relatedUuid is sent on /back only, never on /front.
Your logs never persist raw error bodies (the 422 echoes your request, image included) nor response images.
Read timeout ≥ 30 s; retries only for sporadic 5xx, with backoff.
Your parser reads the fields declared by GET /{templateId}/details for each template you accept.
You send your own info per operation and log the uuid of every response.

Next: Responses

The extracted fields, the cross-validations between front and back, and the two 200s that do not approve anything.

Start here

ID Analysis

Face Analysis

Facial Antispoofing

Connection Fingerprint

The flow in five steps

The request body

Image requirements

The template catalog

Timeouts and retries

Before going to production

Next: Responses

​The flow in five steps

​The request body

​Image requirements

​The template catalog

​Timeouts and retries

​Before going to production

Next: Responses

The flow in five steps

The request body

Image requirements

The template catalog

Timeouts and retries

Before going to production