ID Analysis

The ID Analysis service reads identity documents. You send a photo of the front of a document and receive the identified document type, the data extracted from the visual zone (VIZ), the cropped face, and — if you then send the back — the MRZ, the barcode, and the cross-validations between both sides and between data sources. The flow is always the same and carries no other state: POST /front returns a uuid; that uuid travels as relatedUuid in POST /back; the back’s response carries the cross-validations.

The decision rule

This is the most important part of the integration. Write it in the positive:

// Front: all three conditions. Anything else did NOT read the document.
const frontOk = status === 200
  && body.message === "Operation end successfully."
  && body.id !== "unknown";          // the document type was identified

// Back: in addition to the above
const backOk = body.back.frontBackTemplateValidation === true;
// then review body.crossMatchConfidence before trusting the data

HTTP 200 does not mean “data extracted”. A photo with no readable document also returns 200 — with message: "Cant get document fields", id: "unknown" and an empty viz. And a back that belongs to a different document also returns 200 / "Operation end successfully." — what changes is back.frontBackTemplateValidation: false. Deciding on the status code alone accepts empty reads and mixed documents.

The three identifiers — do not mix them up

Field	What it is
`uuid`	The transaction identifier. It is the value that travels as `relatedUuid` in `/back` and the one support needs. It also arrives in the `x-request-id` header.
`id`	The identified document type (e.g. `VU-ARG-ID-04`), or `"unknown"`.
`info`	Your reference (2–256 characters), echoed back verbatim.

Error bodies carry a uuid generated on the spot that does not correspond to any transaction — only the 200 responses of /front return a uuid usable as relatedUuid.

Endpoints

Method	Path	What it’s for
`POST`	`/front`	Analyze the front. Returns the transaction `uuid`.
`POST`	`/back`	Analyze the back, linked via `relatedUuid`. Returns the cross-validations.
`GET`	`/listTemplates`	The catalog of supported document templates.
`GET`	`/listTemplatesByCountry`	The catalog grouped by country.
`GET`	`/{templateId}/details`	Which fields, MRZ, barcode and face to expect from a template.
`GET`	`/{templateId}/images`	Anonymized sample images of a template.
`GET`	`/version`	Verify connectivity. Check the status code, not the body.

The base URL depends on the environment and is provided by VU along with your api-key. Examples below refer to it as BASE_URL.

Authentication

Every call carries the Api-Key header with your environment’s key.

curl -X GET "$BASE_URL/version" \
  -H "Api-Key: $VU_ID_ANALYSIS_API_KEY"

The api-key belongs in your backend. Never embed it in a mobile app or front-end bundle — anyone can extract it from the binary or the JavaScript.

A complete example

curl -X POST "$BASE_URL/front" \
  -H "Api-Key: $VU_ID_ANALYSIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "info": "onboarding-12345",
    "image": "/9j/4AAQSkZJRgABAQAAAQABAAD..."
  }'

A successful read looks like this, trimmed to the fields that matter (specimen document, fictitious person):

{
  "uuid": "e2084653-7268-4748-9b80-a0da6a22a875",
  "info": "onboarding-12345",
  "message": "Operation end successfully.",
  "id": "VU-ARG-ID-04",
  "front": {
    "ocrType": "template",
    "viz": {
      "name": "NIHAD ELIDUVINA",
      "lastName": "CELDA",
      "documentNumber": "99999999"
    },
    "face": { "image": "/9j/4AAQ..." },
    "hasBackSide": true
  }
}

front.face.image is the face cropped from the document — the image you compare against the selfie with Face Analysis. hasBackSide: true tells you this template expects a back side.

Environments

The UAT environment may run ahead of production. It also validates pre-release versions, so response times and extraction results can differ. Use it to certify your integration — the contract, the status codes, the error handling — not as a performance reference.

Integration

Prepare the images, chain front and back, use the template catalog, and validate before production.

Responses

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

Errors

Status codes, the 422 that echoes your whole request, and which errors are safe to retry.

Start here

Face Analysis

Facial Antispoofing

Connection Fingerprint

ID Analysis

The decision rule

The three identifiers — do not mix them up

Endpoints

Authentication

A complete example

Environments

Next

Integration

Responses

Errors

​The decision rule

​The three identifiers — do not mix them up

​Endpoints

​Authentication

​A complete example

​Environments

​Next

Integration

Responses

Errors

The decision rule

The three identifiers — do not mix them up

Endpoints

Authentication

A complete example

Environments

Next