Tap2iD VDS for Windows - API Reference

Reference for the Windows VDS REST API: endpoints, request and response formats, and operating modes.

Introduction

The Windows Verifier Device Service (VDS) is a software development kit from Credence ID that provides a REST API for developers/integrators to communicate with the Tap2iD® Verifier from Windows applications.

Service Overview

→Adds in-person identity verification to your business application.
→Provides APIs to integrate the Tap2iD reader with a Windows (thick or thin) client application.
→Adds digital ID verification to any Windows PC.
→Supports Tap2iD-initiated and operator-initiated verification flows.
→Runs as a Windows Service on Windows 10/11.

Overview of Functions

Category	API	Description
Device Mgmt.	`GetReaderInfo`	Returns Tap2iD reader information: device make/model, OS version, network status/SSID, reader profile, etc.
	`GetReaderConnectionStatus`	Returns the connection status between the reader and the Windows PC.
	`SetReaderProperties`	Sets device parameters such as USB operation mode, reader profile, and WiFi settings.
Verification	`ReadIDInfo`	Reads the digital ID (mDL) the holder shares and collects ID attributes.
Verification	`StopReadID`	Stops or cancels a Read ID operation before the device has engaged.
Utilities	`Display`	Displays text and an 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 these operating modes:

STANDALONE

Standalone Mode

Scanned data is not sent to VDS over USB. VDS can still connect to the device, GET/SET reader properties, and change operating modes.

HOLDER_DRIVEN

Holder Driven Mode

Data read by the Tap2iD is sent to VDS over USB. The reader is always ACTIVE and accepts any NFC, mDL, or non-mDL QR scan the holder triggers.

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.

Workflows

HOLDER_DRIVEN Workflow

HOST_DRIVEN Workflow

API Specifications

Public APIs for Tap2iD device settings, mDL and physical ID reads, and device management. Base URL: https://localhost:4215/verifier-sdk

GET /verifier-sdk/reader/info GetReaderInfo ›

Returns Tap2iD reader information: 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 the Verify with Credence (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" }

How to Receive Scan Data in HOLDER_DRIVEN

In HOLDER_DRIVEN mode, the ID data received by the VDS is pushed to the customer application through Server Sent Events (SSE) and WebSocket endpoints.

Server Sent Events (SSE)

The call below establishes a long-lasting HTTP connection with the VDS web service. It can be invoked automatically, for example as part of an HTML onload event. Listeners should listen to the specific events shown.

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
// Developer can parse the data to fill up a web form or further process it
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);

WebSocket Endpoints

Primary WebSocket Connection

URL	`wss://localhost:4215/verifier-sdk/ws/{'{'}clientID{'}'}` (if SSL is enabled)
Protocol	WebSocket
clientID	Unique identifier for the client (e.g. `client1`)

Connection URL Example

bash

# For HTTPS mode (if SSL is enabled)
wss://localhost:4215/verifier-sdk/ws/client1

Management Endpoints

`GET /verifier-sdk/ws/status/{'{'}clientID{'}'}`	Check connection status
`GET /verifier-sdk/ws/clients`	Get connected clients count
`GET /verifier-sdk/ws/disconnect/{'{'}clientID{'}'}`	Force disconnect a client

Message Format

Outbound Messages (Server to Client)

json

{
  "type": "SCANNED_DATA",
  "data": {
    // HolderIDInfoResponse object containing scanned ID data
  },
  "timestamp": 1697299200000
}{'

'}{  
  "type": "ERROR_DATA",
  "data": {
    // Error object containing error details
  },
  "timestamp": 1697299200000
}

Inbound Messages (Client to Server)

"ping" — Client ping message; server responds with "connected"
Text messages — Connection health monitoring