You need to create a verification session for every user requiring identity verification, to do so, submit a POST request to:

                      https://api.idanalyzer.com/docupass/create
                

Parameters

You can send parameters using x-www-form-urlencoded, application/json or multipart/form-data.

Successful Response

{
    "reference": "AFNWUQG9C2X",
    "type": 3,
    "customid": "testid123",
    "url": "https://docupass.app/AFNWUQG9C2X",
    "qrcode": "https://api.idanalyzer.com/qr/AFNWUQG9C2X.png",
    "base_url": "https://docupass.app",
    "html": "<h3>Scan QR Code below to start identity verification.</h3><p><img src=\"https://api.idanalyzer.com/qr/AFNWUQG9C2X.png\" alt=\"QR Code\"/></p><p>Or visit <strong>https://docupass.app</strong> on your mobile phone and enter reference code:</p><h3>AFNWUQG9C2</h3>"
    "expiry": 1634073205
}

Error Response

{
    "error": {
        "message": "Invalid value for `companyname`",
        "code": 1002
    }
}

Response Reference

You can create a signature session where user will review and e-sign legal document without identity verification. If you want to perform both identity verification and have your user sign some document, please create an identity verification session instead. To create a signature session, submit a POST request to:

                      https://api.idanalyzer.com/docupass/sign
                

Parameters

You can send parameters using x-www-form-urlencoded, application/json or multipart/form-data.

Successful Response

{
    "reference": "E8FMRX4JJT",
    "customid": "123",
    "url": "https:\/\/docupass.app\/E8FMRX4JJT",
    "qrcode": "https:\/\/api.idanalyzer.com\/qr\/E8FMRX4JJT.png",
    "base_url": "https:\/\/docupass.app",
    "html_qrcode": "<h3>Scan QR Code below to sign contract.<\/h3><p><img src=\"https:\/\/api.idanalyzer.com\/qr\/E8FMRX4JJT.png\" alt=\"QR Code\"\/><\/p><p>Or visit <strong>https:\/\/docupass.app<\/strong> on your mobile phone and enter reference code:<\/p><h3>E8FMRX4JJT<\/h3>",
    "html_iframe": "<iframe src=\"https:\/\/docupass.app\/E8FMRX4JJT\" frameborder=\"0\" allowtransparency=\"true\" style=\"width: 800px; height: 600px;\"><\/iframe>",
    "expiry": 1634073205
}

Error Response

{
    "error": {
        "message": "Invalid contract template ID",
        "code": 1002
    }
}

Response Reference

Once you have generated a DocuPass session, it is time to distribute it to your user so they can begin identity verification.

Direct Link

You can send the DocuPass URL directly to your user, through email, SMS or any other channel. You can also redirect the user from your website or mobile app to the DocuPass link.

QR Code

For DocuPass mobile and signature modules, a QR code will also be generated, you may display this QR Code for your users to scan with their mobile phone.

SMS

You can use sms_verification_link/sms_contract_link parameter to send the DocuPass link to user mobile number, allowing you to verify user mobile on the fly because without a valid mobile number they will not be able to being identity verification or signing of document.

Base URL

Ask your user to navigate to the base_url and enter the reference code.

Embedding into website

If you are using iframe module, you can embed the URL into your website so it appears to the user that the identity verification or document signing is conducted without leaving your website. The iframe module is also mobile friendly, and can be used with any mobile browser.

It is also possible to embed Live Mobile module into an iframe, with the following code <iframe src="https://docupass.app/XXXXXXXXXXX" frameborder="0" allow="camera;microphone" style="width: 800px; height: 600px;"></iframe>. However, user must open the webpage on a mobile device.

Embedding into mobile app

It is possible to embed DocuPass into your mobile applications.

For iOS, use WKWebView and navigate to the URL generated by DocuPass.

For Android, use WebView and navigate to the URL generated by DocuPass.

For Cordova, use InAppBrowser and navigate to the URL generated by DocuPass.

You can set successredir and failedredir parameter when creating DocuPass session, and listen for URL changes in your WebView. This way your app knows verification has been completed without having to poll your server for results.

DocuPass Live Mobile Limitations: For iOS 14 or earlier, it is not possible to embed this module into WKWebView due to lack of support for GetUserMedia API, therefore you should open verification URL with Safari. Nevertheless, full support is available after iOS 14 Beta 2.

DocuPass will POST results to your server once your user completes identity verification or document signing. The results will be sent when:

• User has succeeded identity verification (or signed required document)
• User has failed identity verification and has reached maximum attempts specified
• DocuPass session has expired before completion

Therefore, it is essential to write a webhook script on your server to handle the verification results. For testing purposes, you may use Webhook.site to receive the verification data without implementing your own script. If you choose not to write a webhook script, you can save the verification results into vault for manual review.

POST Body

The POST request sent to your server will contain header Content-Type: application/json and JSON encoded POST body, in your script you should fetch the raw post content and decode it using a JSON decoder. The data returned by different modules of DocuPass are identical.

POST Body - Successful Identity Verification Session

{
    "success": true,
    "reference": "VQTAP6ZN",
    "hash": "42a817116b7bb257733221f53864d98a",
    "customid": "testid123",
    "data": {
        "documentNumber": "1234561",
        "firstName": "FIRSTNAME",
        "lastName": "LASTNAME",
        "fullName": "FIRSTNAME MIDDLENAME LASTNAME",
        "personalNumber": "123456789",
        "sex": "F",
        "dob_day": 12,
        "dob_month": 8,
        "dob_year": 1998,
        "expiry_day": 30,
        "expiry_month": 10,
        "expiry_year": 2028,
        "documentType": "P",
        "issuerOrg_iso2": "US",
        "issuerOrg_iso3": "USA",
        "issuerOrg_full": "United States",
        "nationality_iso2": "US",
        "nationality_iso3": "USA",
        "nationality_full": "United States",
        "dob": "1998\/08\/18",
        "expiry": "2028\/10\/30",
        "age": 22,
        "daysToExpiry": 2941,
        "documentSide": "BIODATA"
    },
    "contract": {
        "document_url": "https:\/\/objects.idanalyzer.com\/1f6e13d7298ac088490aacfb72c85235.pdf"
    },
    "phone": {
        "number": "+1234567899",
        "type": "mobile"
    },
    "face": {
        "isIdentical": true,
        "confidence": "0.901"
    },
    "verification": {
        "passed": true,
        "result": {
            "face": true,
            "notexpired": true,
            "name": true,
            "dob": true,
            "postcode": true,
            "address": true
        }
    },
    "authentication": {
        "score": 1,
        "breakdown": {
            "data_visibility": {
                "passed": true
            },
            "image_quality": {
                "passed": true
            },
            "feature_referencing": {
                "passed": true
            },
            "exif_check": {
                "passed": true,
            },
            "publicity_check": {
                "passed": true,
            },
            "text_analysis": {
                "passed": true
            },
            "biometric_analysis": {
                "passed": true
            },
            "security_feature_check": {
                "passed": true
            },
            "recapture_check": {
                "passed": true
            }
        }
    },
    "aml": [],
    "documentimage": [
        {
            "side": "FRONT",
            "type": "jpg",
            "content": "..."
        },
        {
            "side": "BACK",
            "type": "jpg",
            "content": "..."
        },
        {
            "side": "BIODATA",
            "type": "jpg",
            "content": "..."
        }
    ],
    "faceimage": [
        {
            "type": "jpg",
            "content": "..."
        }
    ]
}

POST Body - Successful Signature Session

{
    "success": true,
    "reference": "VQTAP6ZN",
    "hash": "42a817116b7bb257733221f53864d98a",
    "customid": "testid123",
    "contract": {
        "document_url": "https:\/\/objects.idanalyzer.com\/1f6e13d7298ac088490aacfb72c85235.pdf"
    }
}

POST Body - Failed Identity Verification Session

{
    "success": false,
    "reference": "VQTAP6ZN",
    "hash": "42a817116b7bb257733221f53864d98a",
    "customid": "testid123",
    "failreason": "Face photo does not match with provided document.",
    "failcode": 3,
    "data": {
        "documentNumber": "1234568",
        "firstName": "TEST",
        "middleName": "CARD",
        "lastName": "SAMPLE",
        "fullName": "TEST CARD SAMPLE",
        "sex": "M",
        "height": "176",
        "weight": "58.0",
        "dob_day": 3,
        "dob_month": 8,
        "dob_year": 1989,
        "expiry_day": 30,
        "expiry_month": 11,
        "expiry_year": 2017,
        "issued_day": 30,
        "issued_month": 11,
        "issued_year": 2012,
        "address1": "1989\n910 GOVERNMENT STREET",
        "address2": "VICTORIA BC",
        "postcode": "V8W 3Y8",
        "internalId": "1068",
        "documentSide": "FRONT",
        "documentType": "D",
        "issuerOrg_region_full": "British Columbia",
        "issuerOrg_region_abbr": "BC",
        "issuerOrg_full": "Canada",
        "issuerOrg_iso2": "CA",
        "issuerOrg_iso3": "CAN",
        "nationality_full": "Canada",
        "nationality_iso2": "CA",
        "nationality_iso3": "CAN",
        "dob": "1989\/08\/03",
        "age": 31,
        "expiry": "2017\/11\/30",
        "daysToExpiry": -1046,
        "issued": "2012\/11\/30",
        "daysFromIssue": 2873
    },
    "phone": {
        "number": "+1234567899",
        "type": "mobile"
    },
    "face": {
        "isIdentical": false,
        "confidence": "0.091"
    },
    "verification": {
        "passed": false,
        "result": {
            "face": false,
            "notexpired": false,
            "name": true,
            "dob": true,
            "postcode": true,
            "address": false
        }
    },
    "authentication": {
        "score": 0.1,
        "breakdown": {
            "data_visibility": {
                "passed": true
            },
            "image_quality": {
                "passed": true
            },
            "feature_referencing": {
                "passed": true
            },
            "exif_check": {
                "passed": false,
                "reason": "Image edited in Photoshop"
            },
            "publicity_check": {
                "passed": false,
                "reason": "This document could be obtained in the public domain"
            },
            "text_analysis": {
                "passed": true
            },
            "biometric_analysis": {
                "passed": true
            }
        },
        "warning": [
            "Image edited in Photoshop",
            "This document could be obtained in the public domain"
        ],
    },
    "aml": [
        {
            "entity": "person",
            "fullname": [
                "IMA CARDHOLDER"
            ],
            "firstname": [
                "IMA"
            ],
            "lastname": [
                "CARDHOLDER"
            ],
            "alias": [
                "IMA CARDHOLDER",
                "CARDHOLDER SAMPLE"
            ],
            "dob": [
                "1967"
            ],
            "address": [
                "2570 24TH STREET ANYTOWN, CA, US(possibly)"
            ],
            "nationality": [
                "US"
            ],
            "documentnumber": [
                {
                    "id": "I1234568",
                    "id_formatted": "I1234568",
                    "country": "us",
                    "type": "I"
                }
            ],
            "program": [
                "SDN List"
            ],
            "note": [
                "Executive Order 13224 (Terrorism)"
            ],
            "time": "2019-09-03T22:00:00.000Z",
            "source": [
                "https:\/\/www.treasury.gov\/resource-center\/sanctions\/Pages\/default.aspx"
            ],
            "database": "us_ofac",
            "schema": "sanction"
        }
    ],
    "documentimage": [
        {
            "type": "jpg",
            "content": "..."
        }
    ],
    "faceimage": [
        {
            "type": "jpg",
            "content": "..."
        }
    ]
    "vaultid": "I3MS6XjOqsB7Zbye54ohG9F7rtvW02Zv"
}

POST Body - Expired DocuPass Session

{
    "success": false,
    "reference": "VQTAP6ZN",
    "hash": "42a817116b7bb257733221f53864d98a",
    "customid": "testid123",
    "failreason": "Session expired",
    "failcode": 0
}

Response Data Fields

Server Configuration

DocuPass callback returns document and face images in hosted URL by default, if you do not wish to store user document images on our server, you can set return_type to 0 and the API will post image contents encoded in base64 to your server. The payload size could reach as large as 20+ MB. You will be required to adjust default server configurations for most servers in order to receive the callback.

For servers running PHP, you should make changes to the follow two directives in php.ini

post_max_size=30M
upload_max_filesize=30M

Failed Callbacks

If your server returns http code 200, the callback will be considered sent successfully, you are not required to return any specific content within your callback script.

In case your server is temporary down or an error has occurred resulting in a response other than code 200, e.g. 404 page not found or 500 internal server error. We will automatically try to resend the callback in the following intervals: 10 minutes, 1 hour, 12 hours and 24 hours, up to a maximum of 4 retries will be attempted.

To check if callbacks have been sent successfully, or detailed error messages for callbacks that failed to send, visit the Web Portal DocuPass page.

To make sure the data was sent from our server, you should send HTTP POST with reference code and hash to the following URL:

https://api.idanalyzer.com/docupass/validate

Parameters

Successful Response

{
    "success": true,
    "reference": "VQTAP6ZN"
}

Failed Response

{
    "error": {
        "message": "Invalid reference or hash",
        "code": 1003
    }
}

Create DocuPass Session

$url = "https://api.idanalyzer.com/docupass/create";
$apikey = "Your API Key";
$companyname = "Your Company";
$type = 3;
$callbackurl = "https://mywebsite.com/callback.php";
$customid = "testid123";

$fields = array('callbackurl' => $callbackurl, 'customid' => $customid, 'companyname' => $companyname, 'type' =>  $type, 'apikey' => $apikey);
$resource = curl_init();
curl_setopt($resource, CURLOPT_URL, $url);
curl_setopt($resource, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($resource, CURLOPT_POST, 1);
curl_setopt($resource, CURLOPT_POSTFIELDS, $fields);
$result = json_decode(curl_exec($resource),true);
curl_close($resource);

if(!array_key_exists('error', $result)){
	//success
	print_r($result);
}else{
	//failed
	echo("Error #" . $result['error']['code'] . " " . $result['error']['message']);
}

import requests

apikey = "Your API Key"
companyname = "Your Company"
type = 3
callbackurl = "https://mywebsite.com/callback.php"
customid = "testid123"

payload = {'callbackurl': callbackurl, 'customid': customid, 'companyname': companyname, 'type':  type, 'apikey': apikey}
r = requests.post("https://api.idanalyzer.com/docupass/create", data=payload)
result = r.json()
if "error" in result:
    #failed
    print("Error #" + str(result['error']['code']) + " " + result['error']['message'])
else:
    #success
    print(result['result'])

Processing Callback

$apikey = "Your API Key";
//get the entire POST body
$input_raw = file_get_contents('php://input');

//convert string into associative array
$data = json_decode($input_raw, TRUE);

//validate hash to make sure the result wasn't spoofed
$fields = array('reference' => $data['reference'], 'hash' => $data['hash'], 'apikey' => $apikey);
$resource = curl_init();
curl_setopt($resource, CURLOPT_URL, "https://api.idanalyzer.com/docupass/validate");
curl_setopt($resource, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($resource, CURLOPT_POST, 1);
curl_setopt($resource, CURLOPT_POSTFIELDS, $fields);
$validation_result = json_decode(curl_exec($resource),true);
curl_close($resource);

if($validation_result['success']!==true){
    die("Validation failed!");
}

if($data['success']){
    //verification passed
    echo("Verification passed!");
}else{
    //verification failed
    echo("Verification failed!");
}

// Save user's document images
foreach($data['documentimage'] as $image){
    $savePath = $data['reference'] . "_" . $image['side']. ".jpg";
    if($image['url']!=""){
        // Download image from remote url
        downloadUrlToFile($image['url'],$savePath);
    }else if($image['content']!=""){
        // Save base64 content as file
        file_put_contents($savePath, base64_decode($image['content']));
    }
}

// Save user's face image
foreach($data['faceimage'] as $image){
    $savePath = $data['reference'] . "_face.jpg";
    if($image['url']!=""){
        // Download image from remote url
        downloadUrlToFile($image['url'],$savePath);
    }else if($image['content']!=""){
        // Save base64 content as file
        file_put_contents($savePath, base64_decode($image['content']));
    }
}

function downloadUrlToFile($url, $outFileName)
{
    if(is_file($url)) {
        copy($url, $outFileName);
    } else {
        $options = array(
            CURLOPT_FILE    => fopen($outFileName, 'w'),
            CURLOPT_TIMEOUT =>  30,
            CURLOPT_URL     => $url
        );

        $ch = curl_init();
        curl_setopt_array($ch, $options);
        curl_exec($ch);
        curl_close($ch);
    }
}