> 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/iniciar-validacion.md). # Start Validation Start a document validation by sending the `fileKeys` from the previously [uploaded to storage](/docs.facephi-en/rest-api/midapi-v2/document-services/document-validation/subida-de-assets.md). The service immediately responds with a `transactionId`. The result is obtained via [polling](/docs.facephi-en/rest-api/midapi-v2/document-services/document-validation/consultar-estado.md). {% hint style="info" %} The final diagnosis (`APPROVED`, `DECLINED` or `DOUBTFUL`), the reason (`rejectionReason`) and the individual verification signals (`diagnostics[]`) are detailed in the [result response](/docs.facephi-en/rest-api/midapi-v2/document-services/document-validation/respuesta-de-resultado.md), which includes the **full catalog of reason codes** (general and granular). {% endhint %} ### Endpoint ``` POST /document/validate ``` ### Headers | Name | Type | Required | Description | | ----------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Authorization** | string | **Yes** | Consumer Token in Bearer format `Bearer ` (see [Authentication](/docs.facephi-en/rest-api/midapi-v2/autenticacion.md)). | | **consumer-id** | string | **Yes** | Consumer identifier. | | **operation-id** | string | **Yes** | Identifier of the [operation](/docs.facephi-en/rest-api/midapi-v2/operations.md) to which the assets belong, as returned by `POST /operation`. All the `fileKey` of the request must name this same operation. | ### Request body **Content-Type:** `application/json` Each asset is referenced using a fixed role key (`document_front`, `document_back`, `face`), with its `type` context and its `fileKey`: #### Parameters | Parameter | Type | Required | Description | | ------------------------ | ------ | -------- | -------------------------------------------------------------------------------------------------------- | | `document_front` | object | **Yes** | Front of document asset. | | `document_front.type` | string | **Yes** | `TOKEN_FRONT_DOCUMENT`. | | `document_front.fileKey` | string | **Yes** | `fileKey` returned by `POST /storage`, in the form `{operationId}/TOKEN_FRONT_DOCUMENT`, sent unchanged. | | `document_back` | object | No | Back of document asset. | | `document_back.type` | string | No | `TOKEN_BACK_DOCUMENT`. | | `document_back.fileKey` | string | No | `fileKey` in the form `{operationId}/TOKEN_BACK_DOCUMENT`. | | `face` | object | No | Holder's selfie asset. | | `face.type` | string | No | `TOKEN_FACE_IMAGE`. | | `face.fileKey` | string | No | `fileKey` in the form `{operationId}/TOKEN_FACE_IMAGE`. | The field `type` only accepts those three contexts, each in its corresponding slot. #### Request example ```json { "document_front": { "type": "TOKEN_FRONT_DOCUMENT", "fileKey": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_FRONT_DOCUMENT" }, "document_back": { "type": "TOKEN_BACK_DOCUMENT", "fileKey": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_BACK_DOCUMENT" }, "face": { "type": "TOKEN_FACE_IMAGE", "fileKey": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_FACE_IMAGE" } } ``` {% hint style="warning" %} The `fileKey` is sent **as returned by `POST /storage`**, in the form `{operationId}/{CONTEXTO}`. Adding the context yourself duplicates it and the asset does not resolve. The `type` of each slot must match the context declared by its `fileKey`. If they do not match, the request is rejected with `400`. {% endhint %} Document Validation **only accepts reference**: your request does not include the field `source` and the header `operation-id` is always required. ### Input validations * `document_front` is required, with `type = TOKEN_FRONT_DOCUMENT` and a `fileKey` resolvable. * If they are included `document_back` or `face`, their `type` must match the one expected in that slot and the context declared by its `fileKey`. * `consumer-id` and `operation-id` cannot be empty. * Each `fileKey` must have the form `{operationId}/{CONTEXTO}`, name the operation declared in the header, carry the context corresponding to its slot, and have an asset actually stored. * If the request is invalid (bad request), it is rejected with a `4xx` and no transaction is created. Other failures when starting processing create the transaction with `status = ERROR`. The key format and available contexts are in [Storage](/docs.facephi-en/rest-api/midapi-v2/storage.md). ### Responses #### `202` Accepted #### Response parameters | Parameter | Type | Description | | --------------- | ------ | ---------------------------------------------------------------------- | | `transactionId` | string | Unique identifier of the validation transaction. | | `status` | string | `PROCESSED` (accepted successfully) or `ERROR` (could not be started). | | `timestamp` | string | Creation timestamp of the transaction in format **ISO 8601**. | #### Response example ```json { "transactionId": "1c7d...e9", "status": "PROCESSED", "timestamp": "2026-06-26T12:00:00.000Z" } ``` #### Other responses | Code | Meaning | | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | The request does not pass input validations: missing required asset, `type` does not match the context of the key, empty header, key that does not have the form `{operationId}/{CONTEXTO}`, or context that does not correspond to that slot. No transaction is created. | | `401` | Missing, invalid, or expired Token. | | `403` | The consumer is not provisioned with the service `DOCUMENT_ANTIFRAUD`. | | `404` | The operation does not exist or belongs to another consumer. | | `409` | A referenced asset contains content that was already processed in another operation. | | `410` | The operation has expired. | | `422` | A `fileKey` names an operation different from the one declared in the header, or there is no asset stored in that context. | | `429` | The consumer has exceeded its request rate limit, or a referenced asset has exhausted its invocation budget on this Endpoint. In the first case the response includes `Retry-After`, `X-RateLimit-Limit` and `X-RateLimit-Burst`, and waiting resolves it; in the second it does not. | | `503` | The service persistence is temporarily unavailable. |