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

# Integration guide

> How to integrate ID Analysis: prepare the captures, chain front and back with relatedUuid, use the template catalog, and validate the integration before production.

## The flow in five steps

<Steps>
  <Step title="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.
  </Step>

  <Step title="Prepare the capture">
    A photo of the document, well lit, without glare, with all four borders inside the frame. Base64 **without** the `data:` prefix.
  </Step>

  <Step title="Send the front">
    `POST /front` with `info` and `image`. Keep the returned `uuid`: it is the transaction identifier and the link to the back.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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](/en/vucs/id-analysis/introduction).
  </Step>
</Steps>

```mermaid theme={null}
sequenceDiagram
    participant C as Your backend
    participant A as ID Analysis
    C->>A: POST /front (info, image)
    A-->>C: 200 · uuid · id · front.viz · hasBackSide
    C->>A: POST /back (info, image, relatedUuid = uuid)
    A-->>C: 200 · back.mrz · validations · crossMatchConfidence
```

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

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

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

<CodeGroup>
  ```powershell Windows (PowerShell) theme={null}
  [Convert]::ToBase64String([IO.File]::ReadAllBytes('C:\path\front.jpg')) | Set-Clipboard
  ```

  ```bash Linux theme={null}
  base64 -w0 front.jpg
  ```

  ```bash macOS theme={null}
  base64 -i front.jpg | pbcopy
  ```
</CodeGroup>

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

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

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

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

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

## Before going to production

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

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


## Related topics

- [Integration guide](/en/vucs/face-analysis/integration.md)
- [Identity Link API: Integration Guide](/en/identity-link/introduction.md)
- [Create and Manage Verification Links](/en/identity-link/links.md)
- [Identity Link Webhooks: Verification Lifecycle Events](/en/identity-link/webhooks.md)
- [Authenticate with OAuth2 Client Credentials](/en/identity-link/authentication.md)


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