Skip to content
On this page

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 api's 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 two endpoints: Crop and Verify.

EndpointDescription
CropThis endpoint is used to remove the background from an image of a document. This is helpful when you wish to display the document back to your customer as part their journey.
VerifyThe Verify endpoint performs the document verification.
Classify and verifyClassifies and verifies documents.

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:

Api VersionUrl
1.1 and greaterhttps://api.w2globaldata.com/document-verification/crop

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:

PropertyMandatoryDescription
Page (int)🔒Represents the page of the document you are cropping.
- Must be between 1 and 3
- 1 for the front page of the document
- 2 for the back page of the document
- 3 for additional page of the document
DocumentType (string)🔒A string representing the type of the document you are cropping.
- Must be either 'ID1' or 'ID3'
Image (file)🔒Image data representing the image you wish to crop
- File must be either JPEG, PNG or BMP
ClientReference (string)-A reference identifying this call for your reference.
- Optional

Crop Response

Example of a full document verification crop response:

json
{
    "image": "{Base 64 data removed for documentation}",
    "metadata": {
        "glare": 0,
        "sharpness": 62
    }
}
Property NameDescription
Image(string)Base 64 string representing the cropped document image.
Meta Data (object)Represents extended data obtained from cropping the image. The values provided are not guaranteed to exist on each request.

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:

Api VersionURL
1.1 and greaterhttps://api.w2globaldata.com/document-verification/verify

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:

PropertyMandatoryDescription
Pages (File)🔒An array of image data files that represent the images of the document.
- At least one page 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:

json
{
    "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 NameDescription
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 where as verifying another may not.
ResultRepresents the result of the verification.
Possible values:
- Pass
- Fail
- Refer
PhotoRepresents a base 64 encoded image of the cut out photo on the verified document.
SignatureRepresents a base 64 encoded image of the cut out signature on the verified document.

Alert

Property NameDescription
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 NameDescription
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 co-ordinate or the document region
yAxis (int)The y-axis co-ordinate of the document region

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:

Api VersionURL
1.3 and greaterhttps://api.w2globaldata.com/document-verification/classifyAndVerify

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:

PropertyMandatoryDescription
Pages (File)An array of image data files that represent the images of the document.
- At least one page required
- File must be either JPEG, PNG or BMP
DocumentType (string)A string representing the type of the document you are cropping.
- Required
- Must be either 'ID1' or 'ID3'
ClientReference (string)A reference identifying this call for your reference.
- Optional
AutoVerify (boolean)A boolean flag indicating whether to perform automatic verification on successful classification.

Classify and verify response

Example of a full document verification response:

json
{
    "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.

Property NameDescription
ClassificationRepresents the classification result of the document.
VerificationRepresents the verification result of the document. Please refer to the response properties here.

Classification

Property NameDescription
ClassificationResult (string)The classification result:
Pass - Indicates a successful classification of the document.
Fail - Indicates a unsuccessful classification of the document.
ClassificationDetails (dictionary)A dictionary of key value pairs representing data from the classified document. We cannot guarantee the existence of any values in this dictionary. For example, classifying one document may return the Version on the document where as verifying another may not. However, we do guarantee the existence of ClassificationName - when ClassificationResult of Fail is present ClassificationName will always be Unknown.

ClassificationDetails

Property NameDescription
ClassificationName (string)General category of the document type.
Version (string)The series - such as year, letter, or integer - to which the document belongs.
Type (string)Document subtype, such as Driver License, Driver License Under 21, Identification Card, Over 21, and Under 21.
IssuerCode (string)Code of the Government jurisdiction (country, state, or province) that issued the document.
IssuerName (string)Government jurisdiction (country, state, or province) that issued the document.

Verification

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