VDS · ICD v3.1.0

VDS Interface Control Document

Complete API reference for the Tap2iD Verifier Device Service — endpoints, request parameters, response schemas, and operating modes.

Version 3.1.0

February 2025

REST API

localhost:4215

7 Endpoints

Introduction

1.1 Objective

The objective of this document is to provide technical standards and protocols necessary for the Tap2iD verifier device to be used with customer's Windows applications and Windows kiosk-based ID verification infrastructure.

1.2 Target Audience

This is a Digital ID Verifier device (Tap2iD) specification document to help Tap2iD device users, integrators, and their developers in building mDL-compliant solutions using Tap2iD devices. It is assumed that readers are familiar with digital ID, mDL, and ISO 18013-5 specifications.

Service Overview

→Enables applications to easily integrate in-person identity verification into business workflows
→Provides APIs & endpoints to integrate Tap2iD reader with an existing Windows (thick or thin) client application
→Allows seamless integration of digital ID verification capabilities with any Windows PC
→Supports Tap2iD-initiated or operator-initiated verification flows
→Runs as a Windows Service on Windows 10/11

Overview of Functions

Category	API	Description
Device Mgmt.	`GetReaderInfo`	Obtains information from the Tap2iD reader — device make/model, OS version, network status/SSID, reader profile, etc.
	`GetReaderConnectionStatus`	Checks and gets the connection status of the reader to the Windows PC
	`SetReaderProperties`	Sets various device parameters such as USB operation mode, reader profile, WiFi settings, etc.
Verification	`ReadIDInfo`	Initiates and reads the digital ID (mDL) verification shared by the holder and collects ID attributes
Verification	`StopReadID`	Stops or cancels the Read ID operation if device engagement has not been initiated
Utilities	`Display`	Displays any text and image on the Tap2iD screen
Utilities	`UpgradeTap2iD`	Upgrades the Tap2iD Reader App via APK upload or remote version check

Tap2iD Operating Modes

The Tap2iD device supports the following operating modes:

STANDALONE

Standalone Mode

The scanned data is not transferred over USB to VDS. In this mode, VDS can still connect to the device and can GET/SET reader properties and change operating modes.

HOLDER_DRIVEN

Holder Driven Mode

Any data read by the Tap2iD is sent over USB to VDS. The Tap2iD reader is always ACTIVE and accepts any NFC, mDL, or non-mDL QR scans triggered by the holder.

HOST_DRIVEN

Host Driven Mode

Tap2iD is activated when VDS receives a ReadIDInfo API request from the client application. Once the transaction completes (or via Stop API), Tap2iD becomes passive.

ℹ️

In HOLDER_DRIVEN mode, the ID data received by VDS is pushed to the customer application through Server Sent Events (SSE). The SSE endpoint is https://localhost:4215/verifier-sdk/sse/read/{'{'}clientID{'}'}.

SSE Integration Example

javascript — HOLDER_DRIVEN SSE

var source = new EventSource("https://localhost:4215/verifier-sdk/sse/read/{clientID}");

// Data received has the same model as the ReadIDInfo API response
source.addEventListener('SCANNED_DATA', function(e) {
  var obj = JSON.parse(e.data);
}, false);

source.addEventListener('ERROR_DATA', function(e) {
  var obj = JSON.parse(e.data);
}, false);

API Specifications

All public APIs to access Tap2iD device settings, read mDL and physical ID information, and manage device facilities. Base URL: https://localhost:4215/verifier-sdk

GET /verifier-sdk/reader/info GetReaderInfo ›

Obtains information from the Tap2iD reader — device make/model, OS version, network status/SSID, reader profile, and current device state.

URL https://localhost:4215/verifier-sdk/reader/info

STANDALONE HOLDER_DRIVEN HOST_DRIVEN

Request Parameters

None

json — HTTP 200 OK

{
  "deviceMakeAndModel": "cIDReader",
  "osVersion":         "cIDReader 11 eng 1.0.0_8",
  "applicationVersion": "0.22.0-velociraptor",
  "vdsVersion":        "1.3.4",
  "usbMode":           "HOST_DRIVEN",
  "debugMode":         false,
  "readerProfile":     "ID Check",
  "networkStatus":     true,
  "networkSsidStatus": "WiFi-5G",
  "deviceState":       "CONNECTED"
}

deviceState Values

Value	Description
NOT_CONNECTED	The device is plugged out
CONNECTED_DEBUG	Device is plugged in but set into DEBUG mode (not for regular operation)
CONNECTED_MTP	Device is plugged in but cannot communicate with VDS yet — temporary state
CONNECTED	Device is connected and can communicate with Tap2iD — correct operational state

usbMode / readerProfile Values

Field	Possible Values
usbMode	`STANDALONE`, `HOLDER_DRIVEN`, `HOST_DRIVEN`
readerProfile	`ID Check Profile`, `AGE Check Profile`, `CUSTOM Profile`

json — HTTP 500 Internal Server Error

{ "errorCode": 513, "errorMessage": "Generic Error" }

json — HTTP 503 Service Unavailable

{ "errorCode": 515, "errorMessage": "Service busy with another operation, try after sometime" }

GET /verifier-sdk/reader/connection/status GetReaderConnectionStatus ›

Checks and returns the current connectivity status of the Tap2iD device with the Windows PC.

URL https://localhost:4215/verifier-sdk/reader/connection/status

STANDALONE HOLDER_DRIVEN HOST_DRIVEN

Request Parameters

None

json — HTTP 200 OK

{ "deviceState": "CONNECTED" }

POST /verifier-sdk/reader/properties SetReaderProperties ›

Sets device configuration including USB mode, reader profile, and WiFi settings.

URL https://localhost:4215/verifier-sdk/reader/properties

STANDALONE HOLDER_DRIVEN HOST_DRIVEN

Set Reader Profile

json

{
  "setting": "Reader_Profile",
  "value": {
    "profile": "ID_CHECK" // ID_CHECK, AGE_CHECK, CUSTOM_CHECK
  }
}

Set WiFi

json

{
  "setting": "Wifi",
  "value": {
    "SSID":     "xxxxxx",
    "Password": "xxxxxx",
    "Type":     "WPA" // WPA, WEP, None
  }
}

Set USB Mode

json

{
  "setting": "USB_mode",
  "value": {
    "mode": "HOST_DRIVEN" // HOST_DRIVEN, HOLDER_DRIVEN, STANDALONE
  }
}

— HTTP 200 OK (Success)

// Empty body — 200 OK indicates success

json — HTTP 500

{ "errorCode": 513, "errorMessage": "Generic Error" }

json — HTTP 503 Service Unavailable

{ "errorCode": 515, "errorMessage": "Service busy with another operation, try after sometime" }

GET /verifier-sdk/identity/info ReadIDInfo ›

Initiates and reads mDL data from the digital ID holder and collects various ID attributes as per the active reader profile of the Tap2iD device. Supports mDL (ISO18013), QR Code, and PDF417 (physical DL).

URL https://localhost:4215/verifier-sdk/identity/info?timeout=30&deviceEngagement=…

HOST_DRIVEN

Query Parameters

Parameter	Type	Required	Description
timeout	integer	Optional	USB Read Timeout in seconds. After this timeout, VDS sends a stop command to Tap2iD. Default is configured in `application.properties` (30s).
deviceEngagement	string	Optional	Device Engagement String from a 3rd-party barcode reader. URL-encode if it contains special characters.

json — HTTP 200 OK · ISO18013 mDL

{
  "docType":              "IDENTITY",
  "transactionID":       "",
  "deviceID":            "",
  "validationErrorCode": 100,
  "validationErrorMessage": "",
  "data": {
    "type":              "ISO18013",
    "familyName":       "Doe",
    "givenNames":       "Stefan",
    "birthDate":        "",
    "issueDate":        1678304350,
    "expiryDate":       1678304350,
    "issuingCountry":   "",
    "issuingAuthority": "CredenceID",
    "documentNumber":   "987654321",
    "portrait":         "", // JPEG encoded base64 string
    "drivingPrivileges": [
      {
        "vehicleCategory": "A",
        "issueDate":       1729382400,
        "expiryDate":      1729382400,
        "codes": [{ "code": "", "sign": "", "value": "" }]
      }
    ],
    "sex":              "Male",
    "isAgeOver18":      true,
    "isAgeOver21":      true,
    "residentAddress":  "",
    "residentCity":     "",
    "residentState":    "",
    "residentPostalCode": "",
    "residentCountry":  ""
    // ... additional fields available
  }
}

json — HTTP 200 OK · QR Code

{
  "docType":       "QR_CODE",
  "transactionID": "",
  "deviceID":      "",
  "data": {
    "qrCodeData": ""
  }
}

json — HTTP 200 OK · PDF417 Physical DL (AAMVA)

{
  "docType":              "IDENTITY",
  "transactionID":       "",
  "deviceID":            "",
  "validationErrorCode": 100,
  "data": {
    "type":            "AAMVA_DL_ID",
    "familyName":     "DAVID",
    "givenNames":     "AVA NONE",
    "birthDate":      "1992-01-10",
    "issuingCountry": "USA",
    "documentNumber": "G4841292",
    "sex":            "FEMALE",
    "residentAddress": "123 N CAPITOL AVE",
    "residentCity":   "SAN JOSE",
    "residentPostalCode": "95133",
    "isAgeOver18":    false,
    "isAgeOver21":    true
  }
}

json — HTTP 500 (verification failure, biometric check failure, timeout)

{ "errorCode": 513, "errorMessage": "Generic Error" }

json — HTTP 503 Service Unavailable

{ "errorCode": 515, "errorMessage": "Service busy with another operation, try after sometime" }

GET /verifier-sdk/identity/stop StopReadID ›

Cancels a READ ID operation initiated earlier. Tap2iD may or may not be able to stop depending on whether mDL has already been scanned.

URL https://localhost:4215/verifier-sdk/identity/stop

HOST_DRIVEN

⚠️

Two cases:

mDL not yet scanned: Tap2iD stops READ ID and switches to "Waiting for host" screen. ReadIDInfo returns HTTP 500.
mDL already scanned: Tap2iD cannot stop. The mDL data is sent to VDS but VDS does not forward it to the client. ReadIDInfo still returns HTTP 500.

Request Parameters

None

text — HTTP 200 OK

"ID READ stop request has been successfully submitted"

text — HTTP 400 Bad Request

"STOP cannot be invoked"
// Occurs when no pending ReadIDInfo operation exists or STOP API cannot be invoked

POST /verifier-sdk/reader/display Display ›

Displays any text or image sent to Tap2iD on its screen.

URL https://localhost:4215/verifier-sdk/reader/display

STANDALONE HOLDER_DRIVEN HOST_DRIVEN

json — Request Body

{
  "image":    "",  // (String) JPEG image encoded as base64 — max 100kb
  "text1":    "",  // (String) Line 1 of message — max 15 chars
  "text2":    "",  // (String) Line 2 of message — max 15 chars
  "duration": 10   // (Integer) Duration in seconds — min 1, max 60
}

Field	Type	Constraint
image	string	JPEG base64 — max 100 KB
text1	string	Max 15 characters
text2	string	Max 15 characters
duration	integer	Min 1, Max 60 seconds

json — HTTP 500

{ "errorCode": 513, "errorMessage": "Error occurred during display" }

json — HTTP 503 Service Unavailable

{ "errorCode": 515, "errorMessage": "Service busy with another operation, try after sometime" }

POST /verifier-sdk/reader/upgrade UpgradeTap2iD ›

Upgrades the Tap2iD Reader App. Supports direct APK upload or remote version check via VwC backend.

URL https://localhost:4215/verifier-sdk/reader/upgrade

STANDALONE HOLDER_DRIVEN HOST_DRIVEN

ℹ️

Content-Type: multipart/form-data. The app field takes precedence over checkUpdates — if an APK is uploaded, VDS will not check for remote updates.

Field	Type	Description
app	MultiPartFile	APK file to upload directly to the HTML form. Takes precedence over `checkUpdates`.
checkUpdates	string	`"yes"` — VDS checks VwC backend for the latest Tap2iD version and downloads it. `"no"` — skip remote check.

— HTTP 200 OK (Success)

// Empty body — 200 OK indicates upgrade initiated successfully

json — HTTP 500

{ "errorCode": 513, "errorMessage": "Error occurred" }

json — HTTP 503 Service Unavailable

{ "errorCode": 515, "errorMessage": "Service busy with another operation, try after sometime" }