> 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/api-rest/identity-api/identity-api-reference/onboarding/morphology/document-validation-v2/document-validation-data-v2.md). # Document validation Data V2 Obtiene los resultados del análisis morfológico del documento **una vez que el proceso de validación se ha completado exitosamente**. {% hint style="info" %} Los campos de la respuesta dependerán del proveedor de morfología configurado. {% endhint %} ### Endpoint ``` POST /verify/documentValidation/v2/data ``` ### Headers | Nombre | Tipo | Requerido | Descripción | | ------------- | ------ | --------- | ------------------------------------------------------------- | | **x-api-key** | string | **Sí** | API key de autorización de acceso. | | **family** | string | No | Valor: **OnBoarding**. Requerido con el servicio de tracking. | {% hint style="info" %} Todas las llamadas a los Endpoints para tracking con **Identity Platform** deben contener el header `family`. {% endhint %} ### Cuerpo de la solicitud **Content-Type:** `application/json` #### Parámetros | Parámetro | Tipo | Requerido | Descripción | | ---------------------- | ------ | --------- | ------------------------------------------------------------------------------------------------------- | | `scanReference` | string | **Sí** | **Número de referencia** del escaneo. | | `type` | string | No | ⚠️ Valor **obsoleto**. Será eliminado en futuras versiones. | | `tracking` | object | No | Objeto que representa la información de seguimiento necesaria. | | `tracking.extraData` | string | No | Token generado por el SDK Mobile/Web. Contiene información de seguimiento tokenizada con la Plataforma. | | `tracking.operationId` | string | No | Identificador de operación generado por el SDK Mobile/Web. | #### Ejemplo de solicitud ```json { "scanReference": "fe294c25-17e1-4d98-a958-710edbf00064", "tracking": { "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...", "operationId": "123e4567-e89b-12d3-a456-426614174000" } } ``` ### Respuestas #### `200` Éxito #### Parámetros de respuesta — raíz | Parámetro | Tipo | Descripción | | -------------- | ------ | ----------------------------------------------------------------------------------- | | `status` | string | Estado del servicio. Valores posibles: `success`, `fail` | | `verification` | object | Objeto con los resultados de la verificación. Ver tablas detalladas a continuación. | #### Parámetros de respuesta — `verification` | Parámetro | Tipo | Nullable | Descripción | | ----------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `acceptanceTime` | string | No | Marca de tiempo inicial en formato **YYYY-MM-DDThh**:flag\_mm:**ss.SSSZ**. | | `code` | integer | No | Código de estado correspondiente. Valores posibles: `7001`, `7002`, `9001`, `9102`, `9103`, `9104`, `9121`. Ver [Verification Results](#verification-results). | | `decisionTime` | string | No | Marca de tiempo correspondiente al momento de la **decisión final**. | | `merchantScanReference` | string | No | Número de referencia de la validación. | | `scanReference` | string | No | Referencia interna proporcionada en el estado de inicio. | | `status` | string | No | Estado del proceso de validación del documento. Valores posibles: `Started`, `Submitted`, `Approved`, `Declined`, `Resubmission`, `Expired/Abandoned`, `Review`. Ver [Verification Results](#verification-results). | | `reason` | string | Sí | Descripción del motivo de rechazo del documento (status declined). Null si el estado es approved. Ver [Service Result Code](#service-result-code). | | `reasonCode` | integer | Sí | Código asociado al motivo de rechazo. Null si el estado es approved. Ver [Reason Codes](#reason-codes). | | `document` | object | No | Información del documento. Ver tabla a continuación. | | `person` | object | No | Información de la persona. Ver tabla a continuación. | #### Parámetros de respuesta — `verification.document` | Parámetro | Tipo | Nullable | Descripción | | -------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------- | | `type` | string | No | Tipo de documento. Valores posibles: `PASSPORT`, `DRIVING_LICENSE`, `ID_CARD`, `VISA`, `UNSUPPORTED` | | `country` | string | No | Código del país emisor en formato **ISO 3166-1 alpha-3**. | | `number` | string | No | Número del documento. | | `validFrom` | string | Sí | Fecha de emisión del documento. | | `validUntil` | string | No | Fecha de expiración del documento. | | `placeOfIssue` | string | No | Lugar de emisión. | | `firstIssue` | string | No | Fecha de la primera emisión del documento. | | `issueNumber` | string | No | Número de emisión. | | `issuedBy` | string | No | Autoridad emisora. | #### Parámetros de respuesta — `verification.person` | Parámetro | Tipo | Nullable | Descripción | | -------------- | ------ | -------- | ---------------------------------------------- | | `firstName` | string | Sí | Nombre del usuario. | | `lastName` | string | Sí | Apellido del usuario. | | `idNumber` | string | Sí | Número de documento del usuario. | | `citizenship` | string | Sí | Ciudadanía. | | `nationality` | string | Sí | Nacionalidad. | | `gender` | string | Sí | Género. | | `dateOfBirth` | string | Sí | Fecha de nacimiento en formato **YYYY-MM-DD**. | | `yearOfBirth` | string | Sí | Año de nacimiento **YYYY**. | | `placeOfBirth` | string | Sí | Lugar de nacimiento. | #### Service Result Code El `serviceResultCode` indica el resultado general de la ejecución del servicio: | serviceResultCode | Descripción | Código HTTP | | ----------------- | ------------------------------------------------------------------------------------ | ----------- | | 0 | La ejecución del servicio fue exitosa, el módulo procesó la solicitud correctamente. | 200 | #### Verification Results El campo `verification.status` en la respuesta de Document Validation Data indica el resultado de la verificación: | Status | Código | Descripción | | --------------------- | ------ | ---------------------------------------------------------- | | **Started** | 7001 | El proceso de validación ha sido iniciado. | | **Submitted** | 7002 | Enviado para procesamiento de validación. | | **Approved** | 9001 | Verificado y aprobado exitosamente. | | **Declined** | 9102 | La validación falló y fue rechazada. | | **Resubmission** | 9103 | Requiere reenvío con correcciones o información adicional. | | **Expired/Abandoned** | 9104 | El proceso de validación ha expirado o fue abandonado. | | **Review** | 9121 | En revisión manual para verificación adicional. | #### Reason Codes La siguiente tabla contiene los códigos de motivo detallados que proporcionan contexto adicional para los resultados del servicio (`reasonCode`). {% hint style="info" %} Los códigos obsoletos de los rangos **200** y **600** han sido reemplazados/migrados a los rangos **500** y **900**. Consulta la tabla de [Migración de códigos](#migracion-de-codigos) para conocer las equivalencias. {% endhint %} | Código | Descripción | | ------ | --------------------------------------------------------------------------------------------------- | | 101 | Physical document not used | | 102 | Suspected document tampering | | 103 | Person showing the document does not appear to match document photo | | 104 | Name entered does not match name on document | | 105 | Suspicious behaviour | | 106 | Known fraud | | 107 | Velocity/abuse | | 108 | Velocity/abuse duplicated end-user | | 109 | Velocity/abuse duplicated device | | 110 | Velocity/abuse duplicated ID | | 111 | Session fraudulently accessed | | 112 | Restricted IP location | | 113 | Suspicious behaviour - Identity Farming | | 120 | Person on the portrait does not appear to match reference photo | | 121 | User ID missing | | 122 | No reference found | | 123 | Unable to pass registry checks | | 124 | Face already exists in the face collection | | 126 | Potential PEP match | | 127 | Face match with blocklist | | 128 | End User ID mismatch | | 501 | High probability of fraudulent attempt | | 502 | Multiple parties present in session | | 503 | Attempted deceit | | 504 | Attempted deceit, device screen used | | 505 | Attempted deceit, printout used | | 506 | Presented document tampered | | 507 | Presented document tampered, data cross reference | | 508 | Presented document tampered, document similarity to specimen | | 509 | Person showing the document does not match document photo | | 510 | Presented document type not supported | | 511 | Presented document expired | | 512 | Presented document annulled or damaged | | 513 | Presented document annulled | | 514 | Presented document is damaged | | 515 | Attempted deceit, device screen used for face image | | 516 | Attempted deceit, device screen used for document image | | 517 | Attempted deceit, device screen used for document front image | | 518 | Attempted deceit, device screen used for document back image | | 519 | Attempted injection attack | | 520 | Attempted deceit, printout used for face image | | 521 | Attempted deceit, printout used for document image | | 522 | Attempted deceit, printout used for document front image | | 523 | Attempted deceit, printout used for document back image | | 524 | Presented document tampered, data cross reference for document front and MRZ does not match | | 525 | Presented document tampered, data cross reference for document front and Barcode does not match | | 526 | Attempted deceit, photos streamed | | 527 | Unable to collect proof of address data | | 528 | Proof of address issue date too old | | 529 | Unable to validate National Id data | | 530 | Person is under 13 years old | | 531 | Person is under 14 years old | | 532 | Person is under 16 years old | | 533 | Person is under 18 years old | | 534 | Person is under 20 years old | | 535 | Person is under 21 years old | | 536 | Person is under 25 years old | | 537 | Unable to perform document media portrait cropping | | 538 | Unable to query CIFAS database | | 539 | Resubmission limit exceeded | | 540 | Low confidence score for the session | | 541 | Name on document does not match with name in session initialisation data | | 542 | Unable to validate CPF | | 543 | Reference face image has poor quality | | 544 | Registry did not respond | | 545 | Reference image missing | | 546 | Face image quality insufficient | | 547 | Face missing | | 548 | Attempted deceit, with face reference missing | | 549 | NFC validation failed | | 550 | The name on the address-related document does not match the name in the session initialisation data | | 551 | Document is not recognised | | 552 | Document front is missing | | 553 | Document back is missing | | 554 | Document front is not fully in frame | | 555 | Document back is not fully in frame | | 556 | Face image is not clearly visible | | 557 | Document data is not visible | | 558 | Unable to collect surname data | | 559 | Unable to collect first names data | | 560 | Unable to collect date of birth data | | 561 | Unable to collect document number data | | 562 | Unable to collect expiry date data | | 563 | Unable to collect personal number data | | 564 | Too many incorrect attempts or incomplete MFA | | 565 | Not supported drivers license category | | 566 | System processing failure | | 567 | Decision criteria not met | | 568 | Invalid input | | 569 | Unable to crop face from the face image | | 570 | Custom Decline | | 571 | Unable to identify country | | 572 | Document number on document does not match with document number in session initialisation data | | 573 | Address on document does not match with address in session initialisation data | | 574 | Address provided is missing mandatory fields | | 575 | Invalid certificate | | 576 | Date of birth on document does not match with date of birth in session initialisation data | | 577 | Personal number on document does not match with personal number in session initialisation data | | 578 | Gender on document does not match with gender in session initialisation data | | 579 | Unable to validate pdf signature | | 580 | Address matching failed due to regional restrictions | | 581 | The provided face image does not match with the face image in the registry | | 582 | The provided name does not match with the name in the registry | | 583 | The provided date of birth does not match with the date of birth in the registry | | 584 | The provided personal number does not match with the personal number in the registry | | 585 | Document issue date too old | | 586 | Missing mandatory input | | 587 | Occupation on document does not match with occupation in session initialisation data | | 643 | Unable to crop face image from a document front | | 655 | Unable to collect additional name | | 901 | Registry provider error occurred while connecting to the registry | | 902 | Unable to find the person in the registry | | 903 | Some personal information verification failed | | 904 | Document reported lost or stolen | | 905 | Digital identity provider session has expired | | 906 | Not all required digital identity fields and documents were shared | | 1001 | Query ID must be between 20 and 40 symbols | | 1002 | Query ID must be a valid UUID V4 | | 1003 | Query ID must be unique, it has already been used. | | 1102 | Mandatory parameters are missing from the request. | | 1104 | Request includes invalid parameters. | | 1201 | Invalid timestamp. Timestamp must not be older than one hour. | | 1202 | Timestamp format is incorrect. YYYY-MM-DDTHH:MM:S+Timezone Offset | | 1203 | Invalid ISO 8601 date. Date needs to be in format YYYY-MM-DD. | | 1301 | Requested features are not supported. | | 1302 | Only HTTPS return URLs are allowed. | | 1303 | Invalid status. | | 1304 | Cannot transition to "$STATUS" status. | | 1308 | ID number is missing. | | 1309 | SSN validation requires person firstName + lastName OR fullName to be provided. | | 1310 | SSN validation requires person.dateOfBirth or address data to be provided. | | 1400 | Image data not found. | | 1401 | Image is not in valid base64. | | 1402 | Image context is not supported. | | 1403 | Image property is missing. | | 1500 | vendorData field cannot be more than 1000 symbols. | | 1501 | vendorData must be a string. | | 2003 | Date of birth is not a valid date. | | 2101 | Document number has to be between 6 and 9 characters. | | 2102 | Document number may contain only characters and numbers A-Z, 0-9. | | 2103 | Document type is not supported. | | 2104 | Document from provided country is not supported. | #### Migración de códigos Los códigos obsoletos de los rangos **200** y **600** fueron reemplazados por nuevos códigos en el rango **500**. La siguiente tabla muestra las equivalencias entre los códigos antiguos y los nuevos: | Código anterior (obsoleto) | Descripción anterior | Código nuevo | Descripción nueva | | -------------------------- | ------------------------------------------ | ------------ | -------------------------------------- | | 605 | Face image missing | 547 / 545 | Face missing / Reference image missing | | 608 | Document front missing | 552 | Document front is missing | | 609 | Document back missing | 553 | Document back is missing | | 614 | Document front not fully in frame | 554 | Document front is not fully in frame | | 615 | Document back not fully in frame | 555 | Document back is not fully in frame | | 619 | Document data not visible | 557 | Document data is not visible | | 620 | Presented document expired | 511 | Presented document expired | | 625 | Unable to collect surname | 558 | Unable to collect surname data | | 626 | Unable to collect first names | 559 | Unable to collect first names data | | 627 | Unable to collect date of birth | 560 | Unable to collect date of birth data | | 629 | Unable to collect expiry date | 562 | Unable to collect expiry date data | | 631 | Unable to collect document number | 561 | Unable to collect document number data | | 632 | Unable to collect personal number | 563 | Unable to collect personal number data | | 636 | Presented document not real, screen used | 504 | Attempted deceit, device screen used | | 637 | Presented document not real, printout used | 505 | Attempted deceit, printout used | | 647 | Document not recognised | 551 | Document is not recognised | #### Ejemplo de respuesta ```json { "status": "success", "verification": { "acceptanceTime": "2019-11-06T07:15:27.000Z", "code": 9001, "decisionTime": "2019-11-06T07:18:36.916Z", "merchantScanReference": "12345678", "scanReference": "12df6045-3846-3e45-946a-14fa6136d79a", "status": "approved", "reason": null, "reasonCode": null, "document": { "type": "DRIVERS_LICENSE", "country": "ESP", "number": "PEREZ771116SM1AJ", "validFrom": null, "validUntil": "2024-04-20", "placeOfIssue": "MADRID", "firstIssue": "2015-03-21", "issueNumber": "01", "issuedBy": "ISSUER" }, "person": { "firstName": "MATIAS", "lastName": "PEREZ", "idNumber": null, "citizenship": null, "nationality": null, "gender": null, "dateOfBirth": "1973-03-30", "yearOfBirth": "1973", "placeOfBirth": "MADRID" } } } ``` #### `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" } ```