> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/rest-api/midapi-v2/document-services/document-validation.md).

# Document Validation

**Document Validation** is the service that analyzes the identity document (and, optionally, a selfie) and determines whether they are authentic and consistent with each other. The service is integrated as part of the Facephi API ecosystem.

From the document (and, if provided, the selfie), the service runs a set of anti-fraud validations and returns a single diagnosis:

* **APPROVED**: the document (and, where applicable, its match with the selfie) passes the validations.
* **DECLINED**: an inconsistency, manipulation, or quality/format non-compliance is detected that prevents validation of the document.
* **DOUBTFUL**: the analysis is inconclusive. The document is neither confirmed authentic nor rejected, and the decision is left to the consumer. It appears only in automatic mode.

### Asynchronous nature

Document Validation is an asynchronous service: the call that starts the validation does not block waiting for the result. It responds immediately with a transaction identifier (`transactionId`) and the consumer obtains the result through status queries (polling).

### Service modes

Document Validation is provided in two modes, which are set when the service is enabled and are not chosen per request:

* **Automatic**: the diagnosis is issued entirely by the Facephi anti-fraud engine. When the analysis does not reach a conclusion, the transaction ends with `diagnostic = DOUBTFUL` and its `rejectionReason` corresponding.
* **Hybrid**: when the initial analysis is inconclusive, the case goes through an additional escalated verification before resolution. The final diagnosis is **always `APPROVED` or `DECLINED`: this mode does not return `DOUBTFUL`**. Reason codes 600 to 603 only appear here.

If you do not know which one your integration has, check with support.

### Integration Flow

The startup (Token, operation and asset upload) is common to all services that work by reference and is developed in [Common Flow](/docs.facephi-en/rest-api/midapi-v2/flujo-comun.md). From there:

1. Complete the previous steps of the [common Flow](/docs.facephi-en/rest-api/midapi-v2/flujo-comun.md), including the [asset upload](/docs.facephi-en/rest-api/midapi-v2/document-services/document-validation/subida-de-assets.md) of the document and, optionally, the selfie.
2. [Start the validation](/docs.facephi-en/rest-api/midapi-v2/document-services/document-validation/iniciar-validacion.md) by sending the `fileKeys` obtained as-is, with the `operationId` in the header `operation-id`. The service responds immediately with a `transactionId`.
3. [Check the status](/docs.facephi-en/rest-api/midapi-v2/document-services/document-validation/consultar-estado.md) of the transaction through polling until a terminal status is obtained.

```mermaid
sequenceDiagram
    actor C as Consumer
    participant API as MIDAPI v2

    Note over C,API: Previous steps: Token, operation and asset upload (see common Flow)

    C->>API: POST /document/validate (fileKeys + operation-id)
    API-->>C: 202 transactionId, status PROCESSED

    loop Polling until terminal state
        C->>API: GET /document/validate/{transactionId}
        API-->>C: status IN_PROGRESS
    end

    C->>API: GET /document/validate/{transactionId}
    API-->>C: COMPLETED + diagnostic + rejectionReason + diagnostics[] + ocr
```

The recommended polling cadence is in [Best practices](/docs.facephi-en/rest-api/midapi-v2/document-services/document-validation/buenas-practicas.md), and the detail of the terminal response in [Result Response](/docs.facephi-en/rest-api/midapi-v2/document-services/document-validation/respuesta-de-resultado.md).

{% hint style="info" %}
Document Validation works **exclusively by reference**: it does not accept the asset contents inline. The common reference model for the entire API is in [Storage](/docs.facephi-en/rest-api/midapi-v2/storage.md).
{% endhint %}

{% hint style="warning" %}
**Route changes.** The document validation is now published under `/document/validate`. The previous routes continue to be served so as not to break existing integrations, but they are obsolete and will no longer be documented:

The contract does not change: same headers, same request body, and same responses. Only the route changes.
{% endhint %}

| Previous route             | Current route                            |
| -------------------------- | ---------------------------------------- |
| `POST /daf/validate`       | `POST /document/validate`                |
| `GET /daf/{transactionId}` | `GET /document/validate/{transactionId}` |
| `POST /daf/fraud-report`   | `POST /document/validate/fraud-report`   |