> 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-validation-v2/document-validation-data-v2.md). # Document validation Data V2 Gets the results of the document's morphological analysis **once the validation process has been successfully completed**. {% hint style="info" %} The response fields will depend on the configured morphology provider. {% endhint %} ### Endpoint ``` POST /verify/documentValidation/v2/data ``` ### 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 | | ---------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------- | | `scanReference` | string | **Yes** | **Reference number** of the scan. | | `type` | string | No | ⚠️ Value **deprecated**. Will be removed in future versions. | | `tracking` | object | No | Object representing the required tracking information. | | `tracking.extraData` | string | No | Token generated by the SDK Mobile/Web. It contains tokenized tracking information with the Platform. | | `tracking.operationId` | string | No | Operation identifier generated by the SDK Mobile/Web. | #### Request example ```json { "scanReference": "fe294c25-17e1-4d98-a958-710edbf00064", "tracking": { "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...", "operationId": "123e4567-e89b-12d3-a456-426614174000" } } ``` ### Responses #### `200` Success #### Response parameters — root | Parameter | Type | Description | | -------------- | ------ | ---------------------------------------------------------------- | | `status` | string | Service status. Possible values: `success`, `fail` | | `verification` | object | Object with the verification results. See detailed tables below. | #### Response parameters — `verification` | Parameter | Type | Nullable | Description | | ----------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `acceptanceTime` | string | No | Initial timestamp in format **YYYY-MM-DDThh**:flag\_mm:**ss.SSSZ**. | | `code` | integer | No | Corresponding status code. Possible values: `7001`, `7002`, `9001`, `9102`, `9103`, `9104`, `9121`. See [Verification Results](#verification-results). | | `decisionTime` | string | No | Timestamp corresponding to the moment of the **final decision**. | | `merchantScanReference` | string | No | Validation reference number. | | `scanReference` | string | No | Internal reference provided in the start status. | | `status` | string | No | Document validation process status. Possible values: `Started`, `Submitted`, `Approved`, `Declined`, `Resubmission`, `Expired/Abandoned`, `Review`. See [Verification Results](#verification-results). | | `reason` | string | Yes | Description of the reason for document rejection (status declined). Null if the status is approved. See [Service Result Code](#service-result-code). | | `reasonCode` | integer | Yes | Code associated with the rejection reason. Null if the status is approved. See [Reason Codes](#reason-codes). | | `document` | object | No | Document information. See the table below. | | `person` | object | No | Person information. See the table below. | #### Response parameters — `verification.document` | Parameter | Type | Nullable | Description | | -------------- | ------ | -------- | ----------------------------------------------------------------------------------------------- | | `type` | string | No | Document type. Possible values: `PASSPORT`, `DRIVING_LICENSE`, `ID_CARD`, `VISA`, `UNSUPPORTED` | | `country` | string | No | Issuer country code in format **ISO 3166-1 alpha-3**. | | `number` | string | No | Document number. | | `validFrom` | string | Yes | Document issue date. | | `validUntil` | string | No | Document expiration date. | | `placeOfIssue` | string | No | Place of issue. | | `firstIssue` | string | No | Date of the document's first issue. | | `issueNumber` | string | No | Issue number. | | `issuedBy` | string | No | Issuing authority. | #### Response parameters — `verification.person` | Parameter | Type | Nullable | Description | | -------------- | ------ | -------- | --------------------------------------- | | `firstName` | string | Yes | User's first name. | | `lastName` | string | Yes | User's last name. | | `idNumber` | string | Yes | User document number. | | `citizenship` | string | Yes | Citizenship. | | `nationality` | string | Yes | Nationality. | | `gender` | string | Yes | Gender. | | `dateOfBirth` | string | Yes | Date of birth in format **YYYY-MM-DD**. | | `yearOfBirth` | string | Yes | Year of birth **YYYY**. | | `placeOfBirth` | string | Yes | Place of birth. | #### 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 | #### Verification Results The field `verification.status` in the Document Validation Data response indicates the verification result: | Status | Code | Description | | --------------------- | ---- | ----------------------------------------------------------------- | | **Started** | 7001 | The validation process has been initiated. | | **Submitted** | 7002 | Submitted for validation processing. | | **Approved** | 9001 | Verified and approved successfully. | | **Declined** | 9102 | Validation failed and was declined. | | **Resubmission** | 9103 | Requires resubmission with corrections or additional information. | | **Expired/Abandoned** | 9104 | The validation process has expired or was abandoned. | | **Review** | 9121 | Under manual review for additional verification. | #### Reason Codes The following table contains the detailed reason codes that provide additional context for the service results (`reasonCode`). {% hint style="info" %} The obsolete codes in the ranges **200** and **600** have been replaced/migrated to the ranges **500** and **900**. See the table of [Code migration](#migracion-de-codigos) for the equivalents. {% endhint %} | Code | Description | | ---- | --------------------------------------------------------------------------------------------------- | | 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. | #### Code migration The obsolete codes in the ranges **200** and **600** were replaced by new codes in the range **500**. The following table shows the equivalents between the old and new codes: | Old code (deprecated) | Old description | New code | New description | | --------------------- | ------------------------------------------ | --------- | -------------------------------------- | | 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 | #### Response example ```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" } ```