ID Analyzer Developer ID Analyzer Developer
  • Home
  • Portal
  • Support
ID Analyzer Developer ID Analyzer Developer
ID Analyzer Developer
  • Home
  • Portal
  • Support
  • Home
  • Core API
    • Overview
    • Quick Start
    • API Reference
  • DocuPass API
    • Overview
    • Quick Start
    • API Reference
  • Vault API
    • Overview
    • Quick Start
    • API Reference
  • AML API
    • Overview
    • Quick Start
    • API Reference
  • Client Library
    • PHP
    • .NET
    • NodeJS
    • Python
  • Guide
    • Web-based ID Scanner
    • DocuPass Custom UI Design
  • Change Log
  • ID Fort On-Premise

DocuPass API Reference

Creating DocuPass Identity Verification Session

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.

Key Value Description
apikey String Required Your private API key is available under your web portal.
type 0: Iframe Module
1: Mobile Module
2: Redirection Module
3: Live Mobile Module
Required DocuPass module
companyname Your company or product name Required Your company name will be displayed throughout verification page so that end-user knows they are submitting identity information to your company
callbackurl Webhook/Callback URL to receive verification result Required Images and identity data will be sent to this url whenever a user succeeds or fails a verification. You must either enable vault_save or specify a callbackurl so that you can process verification result.
biometric 0: Disabled (Default)
1: Photo Biometric Verification
2: Video Biometric Verification
OptionalAsk user to take a selfie photo or selfie video for face verification
biometric_threshold Number between 0 to 1 (Default: 0.4) Optional Specify the minimum score to pass facial biometric verification
authenticate_minscore Number between 0 to 1 (Default: 0.3) Optional Document must meet minimum authenticity score to pass validation. Set 0 to disable validity/authenticity check.
authenticate_module 1: Module v1
2: Module v2 (Default)
quick: Quick check against fake ID database
Optional Specify module used for validating the document.
maxattempt Number between 1 to 10 (Default: 2) Optional The number of maximum fail attempts for each verification request. When max attempt is reached, a failed callback will be sent to your server and user will not be able to re-attempt identity verification unless you create a new verification request.
successredir URL Optional Browser will be redirected to this URL when identity verification succeeds. DocuPass reference code and customid will be appended to the end of URL, e.g. https://www.yourwebsite.com/success.php?reference=XXXXXXXX&customid=XXXXXXXX
failredir URL Optional Browser will be redirected to this URL when identity verification failed. DocuPass reference code and customid will be appended to the end of URL, e.g. https://www.yourwebsite.com/failed.php?reference=XXXXXXXX&customid=XXXXXXXX
customid String Optional A custom string that will be sent back to your server's callback URL, and appended to redirection URLs set by successredir and failredir as a query string. It is useful for identifying your user within your database. This value will be stored under docupass_customid under Vault.
reusable Boolean (Default false) Optional Enabling this parameter will allow multiple users to verify their identity through the same URL, a new DocuPass reference code will be generated for each user automatically.
phoneverification Boolean (Default false) Optional Subscriber Only Whether to ask user to enter a phone number for verification, DocuPass supports both mobile or landline number verification. Verified phone number will be returned in callback JSON.
sms_verification_link Full international mobile number Optional Subscriber Only DocuPass will send SMS to this number containing DocuPass link to perform identity verification, the number provided will be automatically considered as verified if user completes identity verification. Number should be provided in international format such as +1333444555, if an invalid or unreachable number is provided error 1050 will be thrown. You should add your own thresholding mechanism to prevent abuse as you will be charged 1 quota to send the SMS.
documenttype P: Passport
D: Driver's License
I: Identity Card
Optional User must upload a specific type of document. For example "PD" would accept both passport and drivers license.
documentcountry ISO ALPHA-2 Country Code Optional User must upload document issued by specified country. Separate multiple values with comma. For example "US,CA" would accept documents from United States and Canada.
documentregion State/Region full name or abbreviation Optional User must upload document issued by specific state/region. Separate multiple values with comma. For example "CA,TX" would accept documents from California and Texas.
dualsidecheck Boolean (Default false) Optional Check if the names, document number and document type matches between the front and the back of the document when performing dual-side scan. If any information mismatches error 14 will be thrown.
verify_expiry Boolean (Default true) Optional Only accept document that has not expired
verify_documentno Document number requiring verification Optional User must upload document matching the document number supplied to pass verification.
verify_name Full name including first name and last name requiring verification Optional User must upload document matching the name supplied to pass verification.
verify_dob Date of birth requiring verification, in YYYY/MM/DD format Optional User must upload document matching the date of birth supplied to pass verification.
verify_age Age range, example: 18-40 Optional Uploaded document must show an age between the specified values to pass verification.
verify_address Full address requiring verification Optional User must upload document matching the address supplied to pass verification.
verify_postcode Full postcode requiring verification Optional User must upload document matching the postcode supplied to pass verification.
verify_phone Full internation mobile or landline number Optional Subscriber Only DocuPass will attempt to verify this phone number as part of the identity verification process, both mobile or landline are supported, if this value is provided phoneverification will be automatically enabled but users will not be able to enter their own numbers or change the provided number. Number should be provided in international format such as +1333444555.
aml_check Boolean (Default false) Optional Check document holder's name and document number against ID Analyzer AML Database.
aml_database String Optional Specify the source databases to perform AML check, if left blank, all source databases will be checked. Separate each database code with comma, for example: un_sc,us_ofac. For full list of source databases and corresponding code visit AML API Overview.
aml_strict_match Boolean (Default false) Optional By default, entities with identical name or document number will be considered a match even though their birthday or nationality may be unknown. Enable this parameter to reduce false-positives by only matching entities with exact same nationality and birthday.
contract_generate Template ID Optional Generate a document using information from uploaded ID, without user reviewing or signing the document.
contract_sign Template ID Optional Generate a document using information from uploaded ID, and have the user review and sign the document after identity verification.
contract_format PDF DOCX HTML Optional Output legal document format.
contract_prefill_data JSON String Optional JSON data in key-value pairs to autofill dynamic fields, data from user ID will be used first in case of a conflict. For example, passing {"myparameter":"abc"} would fill %{myparameter} in contract template with "abc".
vault_save Boolean (Default true) Optional Save user documents and parsed information into vault. This feature is particularly useful if you wish to inspect verification results. You must either enable vault_save or specify a callbackurl so that you can process verification result.
return_documentimage Boolean (Default true) Optional Return document image uploaded by user in the callback request.
return_faceimage Boolean (Default true) Optional Return face image uploaded by user in the callback request.
crop_document Boolean (Default false) Optional Attempt to crop the user document by removing irrelevant regions, only applies if return_documentimage is set to true.
return_type 0: Base64-encoded Image Content
1: Hosted Image URL (Default)
Optional Specify the type of image being returned, either base64-encoded image content or an URL to the image. (URL to image will be kept for only 7 days)
welcomemessage String Optional Replace generic greeting message on the first page with your customized text (max 1,000 characters)
nobranding Boolean (Default false) Optional Subscriber Only Hide branding logo on all DocuPass pages.
logo URL Optional Subscriber Only Custom branding logo.
customhtmlurl URL Optional Subscriber Only Use your own HTML page and CSS for DocuPass. Once you have made changes to the HTML and CSS you need to upload them to your own server, at the start of each session DocuPass will download the latest HTML page from your server. Read Full Guide
language en fr nl de es sr zh-TW zh-CN Optional DocuPass automatically detects user device language and displays corresponding language. Set this parameter to override automatic language detection.
expiry Number of seconds between 600 to 15552000 (Default 180 days) Optional Number of seconds before DocuPass session expires. Upon expiry, user will not be able to continue with the current session, a failed callback will also be sent.
qr_color 6 Digit Hex Color (Default 000000) Optional Color of the QR Code Foreground
qr_bgcolor 6 Digit Hex Color (Default FFFFFF) Optional Color of the QR Code Background
qr_size Integer 1-50 (Default 5) Optional Size of QR Code
qr_margin Integer 1-50 (Default 1) Optional Border thickness of QR Code
Supply Existing Document or Face Image

You can supply existing document or face photo to DocuPass. If you supply document images, your users will not be asked to take a photo of their document. Similarly, if you submit a face photo, the user will not be asked to take a selfie.

Key Value Description
document Image encoded in multipart/form-data Optional For Content-Type: multipart/form-data, upload a document image to skip document photo capturing steps.
document_base64 Base64-encoded image Optional Submit a base64 encoded document image to skip document photo capturing steps.
document_url Image URL Optional Submit a document image URL to skip document photo capturing steps.
document_back Image encoded in multipart/form-data Optional For Content-Type: multipart/form-data, upload a document back-side image to skip document photo capturing steps.
document_back_base64 Base64-encoded image Optional Submit a base64 encoded document back-side image to skip document photo capturing steps.
document_back_url Image URL Optional Submit a document back-side image URL to skip document photo capturing steps.
face Image encoded in multipart/form-data Optional For Content-Type: multipart/form-data, upload a face image to skip capturing selfie photo.
face_base64 Base64-encoded image Optional Submit a base64 encoded document image to skip capturing selfie photo.
face_url Image URL Optional Submit a document image URL to skip capturing selfie photo.

Identity Verification Session Response

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
Key Type Description
reference String A unique reference code for the DocuPass session.
type Number DocuPass module type created.
customid String Custom ID used when creating DocuPass session.
url String Unique URL to DocuPass web app. Send this link to your user, or embed it into your website or mobile app to begin identity verification.
qrcode String QR code image URL for your user to scan
base_url String You may send this link to your user and ask them to enter reference code to start verification.
html String Sample HTML that you can insert into your webpage.
smssent Number Contains the phone number as confirmation when SMS has been successfully sent via sms_verification_link parameter.
expiry String UTC UNIX timestamp indicating when this session will expire, upon expiry, user will no longer be able to use the link and a failed callback will be sent.

Creating DocuPass Signature Session

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.

Key Value Description
apikey String Required Your private API key is available under your web portal.
companyname Your company or product name Required Your company name will be displayed throughout verification page so that end-user knows they are submitting identity information to your company
template_id String Optional Contract template ID to autofill with user data.
contract_format PDF DOCX HTML Optional Output document format.
contract_prefill_data JSON String Optional JSON data in key-value pairs to autofill dynamic fields, data from user ID will be used first in case of a conflict. For example, passing {"myparameter":"abc"} would fill %{myparameter} in contract template with "abc".
callbackurl Webhook/Callback URL to receive verification result Required Contract file will be sent to this url. You must either enable vault_save or specify a callbackurl so that you can save the generated document.
successredir URL Optional Browser will be redirected to this URL after the document has been reviewed and signed. DocuPass reference code and customid will be appended to the end of URL, e.g. https://www.yourwebsite.com/success.php?reference=XXXXXXXX&customid=XXXXXXXX
customid String Optional A custom string that will be sent back to your server's callback URL, and appended to redirection URLs set by successredir and failredir as a query string. It is useful for identifying your user within your database. This value will be stored under docupass_customid under Vault.
reusable Boolean (Default false) Optional Enabling this parameter will allow multiple users to review and sign documents through the same URL, a new DocuPass reference code will be generated for each user automatically.
sms_contract_link Full international mobile number Optional Subscriber Only DocuPass will send SMS to this number containing DocuPass link to review and sign document, the number provided will be automatically considered as verified if user completes identity verification. Number should be provided in international format such as +1333444555, if an invalid or unreachable number is provided error 1050 will be thrown. You should add your own thresholding mechanism to prevent abuse as you will be charged 1 quota to send the SMS.
vault_save Boolean (Default true) Optional Save generated document into vault. You must either enable vault_save or specify a callbackurl so that you can save generated document.
nobranding Boolean (Default false) Optional Subscriber Only Hide branding logo on all DocuPass pages.
customhtmlurl URL Optional Subscriber Only Use your own HTML page and CSS for DocuPass. Once you have made changes to the HTML and CSS you need to upload them to your own server, at the start of each session DocuPass will download the latest HTML page from your server. Read Full Guide
language en fr nl de es zh-TW zh-CN Optional DocuPass automatically detects user device language and displays corresponding language. Set this parameter to override automatic language detection.
expiry Number of seconds between 600 to 15552000 (Default 180 days) Optional Number of seconds before DocuPass session expires. Upon expiry, user will not be able to continue with the current session, a failed callback will also be sent.
qr_color 6 Digit Hex Color (Default 000000) Optional Color of the QR Code Foreground
qr_bgcolor 6 Digit Hex Color (Default FFFFFF) Optional Color of the QR Code Background
qr_size Integer 1-50 (Default 5) Optional Size of QR Code
qr_margin Integer 1-50 (Default 1) Optional Border thickness of QR Code

Signature Session Response

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
Key Type Description
reference String A unique reference code for the DocuPass session.
customid String Custom ID used when creating DocuPass session.
url String Unique URL to DocuPass web app. Send this link to your user, or embed it into your website or mobile app to review and sign document.
qrcode String QR code image URL for your user to scan
base_url String You may send this link to your user and ask them to enter reference code to sign documents.
html_qrcode String Sample HTML to display QR Code on your webpage.
html_iframe String Sample HTML to insert iframe into your webpage.
smssent String Contains the phone number as confirmation when SMS has been successfully sent via sms_contract_link parameter.
expiry Number UTC UNIX timestamp indicating when this session will expire, upon expiry, user will no longer be able to use the link and a failed callback will be sent.

User Distribution

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.

Processing Callback

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
Key Type Description
success Boolean Whether the user has passed identity verification
reference String Reference code for the DocuPass session
hash String Hash is used to validate the authenticity of the request
customid String Custom string passed when creating the verification request.
failreason String Reason for a failed verification
failcode Integer 0 - Session expired
1 - Document not recognized or supported
2 - Authenticity check failed
3 - Biometric verification failed
4 - Document expired
5 - Name verification failed
6 - Date of birth verification failed
7 - Address verification failed
8 - Postcode verification failed
9 - Age verification failed
10 - Key information missing from document
11 - Information mismatch between front and back of document
12 - Document was not issued by one of the specified countries
13 - Document was not issued by one of the specified regions
14 - Document of this type is not accepted
15 - Phone verification failed
16 - ID number verification failed
99 - Other error
data Array Key-value pairs containing information on user uploaded document, for specific list of keys and values please refer to Core API documentation.
contract Array Contains a sub-key document_url, with an URL to signed/generated document.
phone Array Phone verification results if you have enabled phone verification, contains verified phone number and number type (landline or mobile) in number and type respectively.
face Array Face verification results, for specific details refer to Core API documentation.
verification Array Various verification results, for specific details refer to Core API documentation.
authentication Array Authentication results, for specific details refer to Core API documentation.
aml Array Array containing list of AML matches, returns an empty array if no match was found. For specific details refer to AML API Reference. Non-empty AML result warrants a manual review however will not alter the outcome of DocuPass verifications.
documentimage Array Contains a list of document image uploaded by the user, including the document side, image type, and image content(URL or base64). It is possible to receive more than one image if the user has uploaded front and back of the documents.
faceimage Array Contains a list of selfie photo uploaded by the user, including the image type, and image content(URL or base64). If user uploads a video for video biometric verification, a single frame photo will be extracted.
vaultid String Unique identifier to the vault entry if vault_save is enabled.
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.

Validating Callback

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
Key Value Description
apikey API key Required Your private API key is available under your web portal.
reference String Required Reference code received in POST BODY
hash String Required Hash received in POST BODY
Successful Response
{
    "success": true,
    "reference": "VQTAP6ZN"
}
Failed Response
{
    "error": {
        "message": "Invalid reference or hash",
        "code": 1003
    }
}

Code Examples

Create DocuPass Session
  • PHP
  • Python
$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
  • PHP
$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);
    }
}
On this page:
Creating Identity Verification Session Identity Verification Session Response Creating Signature Session Signature Session Response User Distribution Processing Callback Validating Callback Code Examples

© 2023 All Rights Reserved by ID Analyzer