> 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/identity-api/identity-api-reference/onboarding/morphology/document-pad-diagnostic.md). # Document PAD Diagnostic Service that allows verifying whether the material of an identity document is **genuine or not** through analysis of its image, in order to detect **presentation attacks** aimed at identity theft. The result of the validation can return the following values: * **Credible**: The document is genuine. * **Doubtful**: It cannot be determined whether the document is genuine. * **Spoof**: The document appears not to be genuine. * **Error**: The validation process encountered an error. The result is provided in the field **`decision`** of the service response, together with the field **`reason`** which specifies the cause of unsatisfactory validations. ### Image requirements #### Minimum requirements * HD images, minimum resolution: **720px** * Pixels showing the background around the document of at least **5% of its width** * Minimum compression level: **JPEG 70** * The text on the document must be readable by an OCR #### Recommended requirements * FullHD images, minimum resolution: **1080px** * Document centered in the image and occupying more than the **5% of the document** * Without compression, with formats such as **PNG** * Well-lit photo without blurring or light reflections ### Endpoint ``` POST /verify/pad/diagnostic ``` ### Headers | Name | Type | Required | Description | | ------------- | ------ | -------- | ---------------------------------------------------------- | | **x-api-key** | string | **Yes** | Access authorization API Key. | | **family** | string | No | Value: **Onboarding**. Required with the tracking service. | {% hint style="info" %} All calls to the Endpoints for tracking with **Identity Platform** must contain the header `family`. {% endhint %} ### Request body **Content-Type:** `application/json` #### Parameters | Parameter | Type | Required | Description | | ---------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `frontSideImage` | string | **Yes** | Image encoded in **Base64** of the front side of the document to be validated. | | `backSideImage` | string | **Yes** | Image encoded in **Base64** of the back side of the document to be validated. | | `face` | string | No | Image encoded in **Base64** of the person's face to be validated (optional). | | `tokenized` | boolean | **Yes** | Specifies whether the images are sent in **tokenized format** or in plain format. | | `countryCode` | string | **Yes** | Code **ISO Alpha-3** of the country issuing the identity document. | | `idType` | string | **Yes** | Type of document to validate. Possible values: `PASSPORT`, `ID_CARD`, `RESIDENCE_PERMIT`, `DRIVERS_LICENSE`, `DRIVING_LICENSE`, `VISA` | | `tracking` | object | No | Object representing the necessary tracking information. | | `tracking.extraData` | string | No | Token generated by the SDK Mobile/Web. Contains tokenized tracking information with the Platform. | | `tracking.operationId` | string | No | Operation identifier generated by the SDK Mobile/Web. | #### Request example ```json { "frontSideImage": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==", "backSideImage": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==", "face": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==", "tokenized": false, "countryCode": "ESP", "idType": "ID_CARD", "tracking": { "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...", "operationId": "123e4567-e89b-12d3-a456-426614174000" } } ``` ### Responses #### `200` Success #### Response parameters | Parameter | Type | Description | | ---------------------- | ------- | ------------------------------------------------------------------------ | | `serviceTransactionId` | string | Transaction identifier associated with the request processed by the API. | | `serviceResultCode` | integer | Code that indicates the **overall result** from service execution. | | `serviceResultLog` | string | Descriptive field of the execution result. | | `timestamp` | string | Response timestamp (UTC) in the format **ISO 8601**. | | `serviceResult` | object | Object with the validation result. See table below. | | `serviceDocumentData` | string | JSON string with the data extracted by OCR from the identity document. | | `serviceTime` | string | Processing time **(milliseconds)**. | #### Response parameters — `serviceResult.result` | Parameter | Type | Nullable | Description | | ---------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `decision` | string | No | Validation decision. Possible values: `Credible`, `Doubtful`, `Spoof`, `Error`. See [PAD Diagnostic Validation Results](#pad-diagnostic-validation-results). | | `reason` | string | Yes | Rejection reason (present when the decision is not Credible). See [PAD Diagnostic Rejection Reasons](#pad-diagnostic-rejection-reasons). | | `IQA` | object | Yes | Image quality assessment data (Image Quality Assessment). | #### Response parameters — `serviceResult` (additional) | Parameter | Type | Description | | ------------------------- | ------ | --------------------------------------- | | `api_version` | string | Version of the API used for processing. | | `processing_modules_time` | string | Processing modules execution time. | #### Service Result Code The `serviceResultCode` indicates the overall result of the service execution: | serviceResultCode | Description | HTTP Code | | ----------------- | --------------------------------------------------------------------------------- | --------- | | 0 | The service execution was successful, the module processed the request correctly. | 200 | #### PAD Diagnostic Validation Results The PAD (Presentation Attack Detection) diagnostic service returns the validation results in the field `decision`: | decision | Description | | ---------- | -------------------------------------------------------- | | `Credible` | The document is genuine. | | `Doubtful` | It cannot be determined whether the document is genuine. | | `Spoof` | The document appears not to be genuine. | | `Error` | The validation process encountered an error. | #### PAD Diagnostic Rejection Reasons When the validation result is not satisfactory, the field `reason` provides specific details: | reason | Description | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `Screen_Replay_Attack` | An attacker presents an image or video of a document in front of the camera. | | `Black_and_White_Printed_Copy_Attack` | Detection of documents printed on paper in grayscale or black and white. | | `Photo_Replacement_Attack` | The data region appears genuine but the portrait region has a printed photograph over it. It does not detect digital manipulations. | | `SECURITY_PHOTO_CHECK` | The portrait photo on the identity document is manipulated. | | `SECURITY_DATA_CHECK` | The document data show alterations in their content. | | `SECURITY_OCR_CHECK` | The comparison of common data between the front and back of the identity document fails. | | `NOT_PROCESSED_OCR` | The OCR data could not be extracted from the identity document. | | `NOT_PROCESSED_PHOTO_CHECK` | The portrait photo verification of the identity document could not be performed. | | `NOT_PROCESSED_DATA_CHECK` | The verification of the values of the identity document fields could not be performed. | #### Response example — Successful validation ```json { "serviceTransactionId": "24f7451f-9bc2-483b-xxxx-a8421d98c664", "serviceResultCode": 0, "serviceResultLog": "Executed OK", "timestamp": "2022-12-15T16:00:00.000Z", "serviceResult": { "result": { "decision": "Credible", "IQA": { "FTA": "DOCUMENT_TOO_CLOSE" } }, "api_version": "pad_cards_v1_1_1", "processing_modules_time": "" }, "serviceDocumentData": "{\"CHECKS\":{\"BIRTH_DATE_SIDE_MATCH\":false,\"SEX_SIDE_MATCH\":true,\"SURNAME_SIDE_MATCH\":true,\"PERSONAL_NUMBER_SIDE_MATCH\":true,\"EXPIRATION_DATE_SIDE_MATCH\":true,\"NAME_SIDE_MATCH\":true,\"NATIONALITY_SIDE_MATCH\":true},\"SUBTYPE\":null,\"BACKSIDE\":{\"FIELD_DATA\":{\"ADDRESS\":[\"\",\"\"],\"CUIL\":\"\"},\"MRZ_DATA\":{\"NATIONALITY\":\"\",\"SERIAL_NUMBER\":\"\",\"SURNAME\":\"\",\"EXPIRATION_DATE\":\"\",\"SEX\":\"\",\"BIRTH_DATE\":\"\",\"ISSUING_COUNTRY\":\"\",\"IDENTITY_NUMBER\":\"\",\"PERSONAL_NUMBER\":\"\",\"NAME\":\"\"}},\"FRONTSIDE\":{\"FIELD_DATA\":{\"NATIONALITY\":\"\",\"SURNAME\":\"\",\"EXPIRATION_DATE\":\"\",\"BARCODES\":[],\"SEX\":\"\",\"BIRTH_DATE\":\"\",\"PERSONAL_NUMBER\":\"\",\"EXPEDITION_DATE\":\"\",\"EXEMPLAR\":\"\",\"NAME\":\"\"}},\"SCORING\":{\"FIELDS_TOTAL\":0,\"FIELDS_RETURNED\":0,\"OVERALL_RATING\":0},\"DOC_MODEL\":\"\"}", "serviceTime": "20784" } ``` #### Response example — Error ```json { "serviceTransactionId": "6b308748-9898-4833-a7d4-85ff8b5d518f", "serviceResultCode": -13, "serviceResultLog": "Service Exception", "timestamp": "2025-08-29T03:50:02Z", "serviceResult": { "result": { "IQA": null, "decision": "Error", "reason": "NOT_PROCESSED_OCR" }, "api_version": "", "processing_modules_time": "" }, "serviceTime": "4234" } ``` #### `400` Bad Request ```json { "status": 400, "title": "Bad Request", "detail": "Invalid request.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400", "errors": [] } ``` #### `401` Unauthorized ```json { "message": "Unauthorized" } ``` #### `403` Forbidden ```json { "Message": "User is not authorized to access this resource with an explicit deny" } ``` #### `502` Bad Gateway ```json { "status": 502, "title": "Bad Gateway", "detail": "Server got an invalid response.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502" } ``` #### `504` Gateway Timeout ```json { "message": "Endpoint request timed out" } ```