> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vu-one.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ID Analysis

> VU's ID Analysis API: send the front (and optionally the back) of an identity document and get the extracted data, the document type, the cropped face, and the cross-validations.

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:

```js theme={null}
// 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
```

<Warning>
  **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.
</Warning>

## 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. |

<Note>
  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`.
</Note>

## 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.

```bash theme={null}
curl -X GET "$BASE_URL/version" \
  -H "Api-Key: $VU_ID_ANALYSIS_API_KEY"
```

<Warning>
  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.
</Warning>

## A complete example

```bash theme={null}
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):

```json theme={null}
{
  "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](/en/vucs/face-analysis/introduction). `hasBackSide: true` tells you this template expects a back side.

## Environments

<Note>
  **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.
</Note>

## Next

<CardGroup cols={3}>
  <Card title="Integration" icon="code" href="/en/vucs/id-analysis/integration">
    Prepare the images, chain front and back, use the template catalog, and validate before production.
  </Card>

  <Card title="Responses" icon="list-check" href="/en/vucs/id-analysis/responses">
    The extracted fields, the cross-validations, and the two 200s that do not approve anything.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/en/vucs/id-analysis/errors">
    Status codes, the 422 that echoes your whole request, and which errors are safe to retry.
  </Card>
</CardGroup>


## Related topics

- [Errors and diagnostics](/en/vucs/id-analysis/errors.md)
- [Integration guide](/en/vucs/id-analysis/integration.md)
- [Interpreting responses](/en/vucs/id-analysis/responses.md)
- [VU Cloud Services](/en/vucs/introduction.md)
- [VU Technical Documentation](/en/index.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.