How to call the endpoint

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

URL	API Version
https://api.w2globaldata.com/document-verification/verify	1.1+

Verify 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:

Property

Mandatory

Description

Pages (File)

🔒

An array of image data files that represent the images of the document.
- At least one page is required

File must be either JPEG, PNG or BMP

DocumentType (string)

🔒

A string representing the type of the document you are cropping

Must be either 'ID1' or 'ID3'

ClientReference (string)

A reference identifying this call for your reference.

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.

Property Name	Description
Alerts (array of objects)	Represents the alerts generated from verifying the document. See the table below for details.
Checked Regions (array of objects)	Shows the checked regions of the verified document. See the table below for details.
Meta Data (dictionary)	A dictionary of key value pairs representing data from the verified document. We cannot guarantee the existence of any values in this dictionary. For example, verifying one document may return the Name on the document, whereas verifying another may not.
Result	Represents the result of the verification. Possible values: - Pass Fail Refer
Photo	Represents a base 64 encoded image of the cut out photo on the verified document.
Signature	Represents a base 64 encoded image of the cut out signature on the verified document.

Alert

Property Name	Description
Name (string)	The name of the alert.
Description (string)	The description of the alert.
Mitigation (string)	The action(s) that can manually be performed to mitigate the alert.
Result (string)	The alert result: Failed: The alert indicates a failure of a document verification metric. Refer: The alert indicates the possible manual verification metric that could not confidently be guaranteed correct by automated checks.

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

Property Name	Description
Name (string)	The name of the document region.
Height (int)	The height of the document region.
Width (int)	The width of the document region.
xAxis (int)	The x-axis coordinate of the document region.
yAxis (int)	The y-axis coordinate of the document region.