Skip to main content

Driver License Verification

A fast and accurate method of verifying the information on your user's driver's license and ID cards, BlockID Driver License Verification can be set up and integrated into your environment with a few simple steps.

Using our helper SDKs, developers can initiate the driver license verification process by sending an SMS containing a URL (and matching session) to our web-based application. Users follow the instructions on the application to take a photo of the front and back of their license, followed by a selfie photo.

Our servers are fully integrated with AAMVA - the American Association of Motor Vehicle Administrators. Using AAMVA, our systems verify the information on your driver's license or identification card with the issuing Department of Motor Vehicles.

caution

Please note that AAMVA verifications are a paid service and have a cost associated with each scan. Please contact developers@1kosmos.com for more information

Please see our Driver License Verification Demo Application in our developer sandbox for a hands on demo of the driver's license verification process. This article is focused on configuring the backend to create the session and URL that users will use to access the driver's license verification scan.

Create a new Driver License Verification Session​

Parameters​

  • dns: tenant domain as shown in the dashboard
  • communityName: tenant community as shown in the dashboard
  • licenseKey: tenant license key as shown in the dashboard
  • dvcId: tenant document verification configuration as shown in the dashboard
  • documentType: set as dl_object
  • smsTo: phone number, including area code
  • smsISDCode: international subscriber dialing code of the phone number
  • smsTemplateB64: base64-encoded SMS message to send, along with the URL to initiate the web-based driver license scan (see example below)
  • sessionId: session ID returned by the API server for the driver license scan

Request Format​

tip

All requests are plug-and-play, not copy-paste. Please ensure that you are replacing the parameters in the request format below with the actual values

To begin, we first need to create a new session for the driver's license verification. We've outlined the request format.

  • Set tenant info and document verification configuration (dvcID)
const BIDVerifyDocument = require('blockid-nodejs-helpers/BIDVerifyDocument');
const BIDMessaging = require('blockid-nodejs-helpers/BIDMessaging');
const dvcId = "<dvcId>";
const documentType = "dl_object";

const tenantInfo = {
    dns: "<tenant dns>",
    communityName: "<community name>",
    licenseKey: "<user license key>"
}
  • Define the SMS message to send to users with the URL to initiate the driver's license verification web application
const sample_sms_template = "Hello Developer, Please complete your document verification scan for Company by visiting <link>"
tip

The <link> parameter is just a placeholder and will be replaced with the actual URL below

  • Create a session and generate a URL to initiate the web-based driver's license verification
async function createSessionAndTriggerSMS() {
    let createdSessionResponse = await BIDVerifyDocument.createDocumentSession(tenantInfo, dvcId, documentType);

    // Replace the URL placeholder in sms template.
    console.log('createdSessionResponse:', createdSessionResponse);
    
    const templateText = sample_sms_template
        .toString()
        .replace(/<link>/, createdSessionResponse.url);
    const smsTemplateB64 = Buffer.from(templateText).toString('base64');

    // Trigger SMS with DL Scan link to the provided phone number
    let smsResponse = await BIDMessaging.sendSMS(tenantInfo, smsTo = "<smsTo>", smsISDCode = "<smsISDCode>", smsTemplateB64);
}
  • Start polling session for driver license verification, start face compare when SUCCESS is returned
note

The polling function will run until a SUCCESS status is returned. See example polling responses

async function pollSession(sessionId) {
    // Start poll session for DL scan + Live Id verirfication Response
    let pollSessionResponse = await BIDVerifyDocument.pollSessionResult(tenantInfo, dvcId, sessionId);
    console.log('pollSessionResponse:', pollSessionResponse);

    // After receiving Success Response, start face_compare of dl image and liveid object 
    if (documentResponse.responseStatus === "SUCCESS") {
        let document = {
            id: pollSessionResponse.liveid_object.id,
            type: "dl",
            image1: pollSessionResponse.dl_object.face,
            image2: pollSessionResponse.liveid_object.face,
            purpose: "dl_verification"
        };
        
        const faceCompareResponse = await BIDVerifyDocument.verifyDocument(tenantInfo, dvcId, ["face_compare"], document);
        console.log('faceCompareResponse::', faceCompareResponse);
    }
}
  • Create session and trigger SMS
var sessionResponse = createSessionAndTriggerSMS();
await pollSession(sessionResponse.sessionId)

Example Request​

tip

Dummy information is provided in this example

const BIDVerifyDocument = require('blockid-nodejs-helpers/BIDVerifyDocument');
const BIDMessaging = require('blockid-nodejs-helpers/BIDMessaging');
const dvcId = "devx_57010000-ea00-4500-ab00-b86d22000000";
const documentType = "dl_object";
const tenantInfo = {
    dns: "blockid-trial.1kosmos.net",
    communityName: "default",
    licenseKey: "00000000-0000-0000-0000-000000000000"
}

//Define SMS message
const sample_sms_template = "Hello Developer, Please complete your document verification scan for Company by visiting <link>"

// Create verification session and URL 
async function createSessionAndTriggerSMS() {
    let createdSessionResponse = await BIDVerifyDocument.createDocumentSession(tenantInfo, dvcId, documentType);

    // Switch URL placeholder with actual verification link in sms template
    console.log('createdSessionResponse:', createdSessionResponse);
    
    const templateText = sample_sms_template
        .toString()
        .replace(/<link>/, createdSessionResponse.url);
    const smsTemplateB64 = Buffer.from(templateText).toString('base64');

    // Trigger SMS with verification link to the provided phone number
    let smsResponse = await BIDMessaging.sendSMS(tenantInfo, smsTo = "1234567890", smsISDCode = "1", smsTemplateB64);
	return createdSessionResponse;
}

// Start poll session for DL scan + Live ID verification response
async function pollSession(sessionId) {  
    let pollSessionResponse = await BIDVerifyDocument.pollSessionResult(tenantInfo, dvcId, sessionId);
    console.log('pollSessionResponse:', pollSessionResponse);

    // After receiving Success Response, start face_compare of dl image and liveid object 
    if (documentResponse.responseStatus === "SUCCESS") {
        let document = {
            id: pollSessionResponse.liveid_object.id,
            type: "dl",
            image1: pollSessionResponse.dl_object.face,
            image2: pollSessionResponse.liveid_object.face,
            purpose: "dl_verification"
        };
        
        const faceCompareResponse = await BIDVerifyDocument.verifyDocument(tenantInfo, dvcId, ["face_compare"], document);
        console.log('faceCompareResponse::', faceCompareResponse);
    }
}
 
var sessionResponse = createSessionAndTriggerSMS();
await pollSession(sessionResponse.sessionId)

Server Responses​

tip

Responses include dummy data as an example of a typical response

A successful request should return a session ID, along with the URL that users should visit on their mobile device to initiate the driver's license verification scan.

Driver License Verification Responses​

200 OK

{
 "url": "https://multieastt.reauthid.com/MWA/index.html?token=c575f661-905f-49d9-bcf9-261ca0000000",
 "sessionId": "c575f661-905f-49d9-bcf9-261ca0000000"
}

The API accepted the request and has returned a session ID and link to initiate the document verification process.

Polling Function Responses​

SUCCESS
{
    "responseStatus": "SUCCESS",
    "sessionId": "0acc3890-7df9-4867-afda-0b5000000000",
    "dl_object": 
    {
        "type": "dl",
        "documentType": "DL",
        "category": "identity_document",
        "documentId": "W599Z0673B",
        "id": "W599Z0673B",
        "firstName": "CAMEMON",
        "lastName": "ABBA",
        "familyName": "ABBA",
        "middleName": "HASSAN",
        "givenName": "CAMEMON HASSAN",
        "fullName": "CAMEMON HASSAN ABBA",
        "doe": "20270620",
        "doi": "20210605",
        "face": "",
        "image": "",
        "imageBack": "",
        "gender": "1",
        "height": "5'9",
        "eyeColor": "Brown",
        "street": "19821 NE 185TH ST",
        "city": "WOODINVILLE",
        "restrictionCode": "WOODINVILLE",
        "residenceCity": "WOODINVILLE",
        "state": "WA",
        "country": "USA",
        "zipCode": "980779426",
        "residenceZipCode": "980779426",
        "county": "King",
        "classificationCode": "WA",
        "complianceType": "1",
        "placeOfBirth": null
    },
    "liveid_object": {
        "id": "com.blockid.liveid",
        "type": "liveid",
        "category": "identity_document",
        "face": "fgRuQ1Lqkcn3cni76M77ER9iBfYNQ5vwf0qfPvHyWFiMAAAAASUVORK5CYII="
    },
    "token": "iVBORw0KGgoAAAAN/SUhEUgAAACAAAAAg="
}

Face Compare Responses​

{
    "docId": "com.blockid.liveid",
    "docType": "dl",
    "certifications": [
        {
            "docType": "dl",
            "docId": "com.blockid.liveid",
            "type": "face_compare",
            "ts": 1651751289793,
            "verified": true,  
            "result": {
                "id": "com.blockid.liveid",
                "type": "dl",
                "category": "identity_document",
                "confidence": 0.9920617938041687,
                "minScore": 0.9
            },
            "metadata": {
                "transactionId": "f4b48944-5476-430e-9487-291c612b990b",
                "similarity": 0.9920617938041687
            },
            "token": "BZevuyUqEN4pUEJWMnhrPWiZyiAI+Il1FsrZNPzUqG5RjAKb5bVRdTGnl2LW/QOKE3YL+Aj4vegHOOQN9hFZssfuWKgNtHIEbST2uH7AqTbuW6CU+Ckli4SZTz75FGbSCDC38VmsdVlhCw+UVMExLq9Hb3J6u8oFyaA/HVuuxj0qo3CABXx/YEPv/8M/r0Ehn4IJuausX+aBap5z0iLCMfGrrphWy55KrbOiJj4bQfcqmtIkq2CqZHWA0l06oN9lw+hVUeyRdYYz0hIrhsazbT4NBQ4lEwXFc8SqrTSOLpQsgn3n3Hx7gbNmG0idD4wp2ZDy5NNoN7LmpahvUeFkYIBNscY5r16XoZmeRjYlwUZpc1cUJdRPQbGnu2f53M+Rhg3y5m4wIXRdMjkn+b6u8/fROp1O52jRRrrm2WNnb4OZhV3lryNPi9H6wc+58qvpfWcKu0BN0qobrAOm1//fp/X98446oSHMnDpXWM6yCGa/4A=="
        }
    ]
}