Document Verification ​

This section describes how the Document Verification API endpoint functions

This section is for consuming the service W2-DATA-DOCUMENT_CHECK-039.
If using W2 Data IDV Check 013 please refer to Upload Document

Document Type ​

When using W2's document verification APIs, you will be asked to supply the Document Type of the document you are verifying.

This refers to the size standards for identification documents specified by ISO. You can read more about the standard here. W2 currently Supports ID1 or ID3 documents.

Endpoints ​

The document verification API is broken down into the following endpoints:

Crop ​

This endpoint is used to remove the background from a document image.

How to call the endpoint ​

To call the endpoint you will need to perform a HTTP POST request to this URL:

Crop Request ​

Content Type: The crop endpoint expects the body of requests to be in the form-data format. Responses will be in application/json format

These are the properties the endpoint accepts:

Crop Response ​

Example of a full document verification crop response:

{
    "image": "{Base 64 data removed for documentation}",
    "metadata": {
        "glare": 0,
        "sharpness": 62
    }
}

Glare and Sharpness Scores ​

• The Sharpness score will give an indication of the quality of the image. The score is between 0 and 100, and the higher the value, the better the quality of the image detected. If the score is too low, the image may not be successfully classified, and you will need to use an alternative image to attempt the verification.
• The Glare score will give an indication of how much glare has been detected on the image. The score is between 0 and 100, and the lower the value, the better the image (the less glare was detected). If the score is too high, the image may not be successfully classified, and you will need to use an alternative image to attempt the verification.

Verify ​

The Verify endpoint is used to verify documents.

How to call the endpoint ​

To call the endpoint you will need to perform a HTTP POST request to the URL:

Verify Request ​

Content Type: The verify endpoint expects the body of requests to be in the form-data format. Responses will be in application/json format.

These are the properties the endpoint accepts:

Verify Response ​

Example of a full document verification response:

{
    "alerts": [
        {
            "name": "Document Expired",
            "description": "Checked if the document is expired.",
            "mitigation": "The document has expired",
            "result": "Refer"
        },
        {
            "name": "Visible Pattern",
            "description": "Verified the presence of a pattern on the visible image.",
            "mitigation": "A visible pattern was not found",
            "result": "Failed"
        }
        // Additional data removed for brevity.....
    ],
    "checkedRegions": [        
        {
            "name": "Document Number",
            "height": 46,
            "width": 177,
            "xAxis": 544,
            "yAxis": 2
        },
        {
            "name": "Expiration Date",
            "height": 31,
            "width": 166,
            "xAxis": 243,
            "yAxis": 150
        }
        // Additional data removed for brevity.....
    ],
    "metaData": {
        "name": "Tyrion Lannister",
        "dateOfBirth": "1990-08-01T00:00:00.0000000Z",
        "mrz": "IRGGRJF321822427<<<<<<<<<<<<1234010M1511114KEN<<<<<<<<<<<8ICTHREEMALE<<TECH<REFRESH<<<<<",
        "documentNumber": "123456789",
        "documentExpiryDate": "31/05/2022"
    },
    "result": "Refer",
    "photo": "<Base 64 encoded image removed for documentation>",
    "signature": "<Base 64 encoded image removed for documentation"
}

Verify response breakdown ​

This table describes the properties of the response.

Alert

Alert table
On a document verification, the number of security checks completed varies from document to document, based on the number of security features that the document contains. To achieve an overall Pass, not every check needs to pass, and this alert table will highlight the checks that were not passed.

Checks that do not pass, are broken down into 2 categories – ‘Refer’ and ‘Failed’.

A ‘Refer’ simply refers to a potential warning or information alert that normally indicates that the quality of the image did not allow the check to be completed. Users normally find on human inspection of these, they are passed, and most clients will simply ignore these alerts if the overall result of the Document verification is a Pass.

The ‘Failed’ checks indicate that the check was completed, but there was an element of the check that failed the verification. This will normally be associated with referred or failed checks; however, the visual checks can also fail depending on document classification. These should normally result in some human inspection, but again, are normally only checked in circumstances where the overall document check has not passed.

Regions checked
This table gives co-ordinates of the areas of the document that have been assessed and automatically reviewed. W2 provides these regions so clients can extract the specific regions of the document that relate to the checks that have been completed and inspect/review if they see fit. If clients are storing the documents, these regions can also be used as marker for ‘redacting’ Personal Identifiable Information (PII).

Meta Data
This is the region where extracted information from the document is reported on via optical data recognition (OCR). W2 currently only reports on the Name, Date of birth, Machine-Readable zone (MRZ), Document Number and Document Expiry Date of a document. We are looking to expand these offerings to include document classification, address etc soon.

Result
This is the overall result of the document verification. This is the final, overall recommendation from W2 regarding how the document verification should be treated.

Photo
This is the photo that is extracted by the document verification. It is this photo that is normally used by the facial comparison SDK to compare the selfie picture against.

Signature
If a signature is included on the document, this is the region that will extract the image of the signature.

Checked Regions

Classify And Verify ​

The Classify And Verify endpoint is used to perform document classification and verification.

How to call the endpoint ​

To call the endpoint you will need to perform a HTTP POST request to the URL:

Classify and verify request ​

Content Type: The classifyAndVerify endpoint expects the body of requests to be in the form-data format. Responses will be in application/json format.

These are the properties the endpoint accepts:

Classify and verify response ​

Example of a full document verification response:

{
    "classification": {
        "classificationResult": "Pass",
        "classificationDetails": {
            "classificationName": "Passport",
            "version": "2006",
            "type": "ePassport",
            "issuerCode": "GBR",
            "issuerName": "United Kingdom (Citizen)"
        }
    },
    "verification": {
        "alerts": [
            {
                "name": "Document Expired",
                "description": "Checked if the document is expired.",
                "mitigation": "Check if the document has expired",
                "result": "Refer"
            },
            {
                "name": "Birth Date Check Digit",
                "description": "Verified that the birth date check digit is correct.",
                "mitigation": "The birth date check digit is correct",
                "result": "Passed"
            }
            // Additional data removed for brevity.....
        ],
        "checkedRegions": [
            {
                "name": "Background",
                "height": 270,
                "width": 574,
                "xAxis": 1337,
                "yAxis": 466
            },
            {
                "name": "Background Bird",
                "height": 324,
                "width": 486,
                "xAxis": 986,
                "yAxis": 702
            }
            // Additional data removed for brevity.....
        ],
        "metaData": {
            "name": "Tyrion Lannister",
            "dateOfBirth": "1990-08-01T00:00:00.0000000Z",
            "mrz": "IRGGRJF321822427<<<<<<<<<<<<1234010M1511114KEN<<<<<<<<<<<8ICTHREEMALE<<TECH<REFRESH<<<<<",
            "documentNumber": "123456789",
            "documentExpiryDate": "31/05/2022"
        },
        "result": "Refer",
        "photo": "<Base 64 encoded image removed for documentation>",
        "signature": "<Base 64 encoded image removed for documentation>"
    }
}

Classify response breakdown ​

This table describes the properties of the response.

Classification

ClassificationDetails

Verification

The verification response is the same as the Verify endpoint. Please refer to the response properties in the verify endpoint documentation.