Tap2iD VDS for Linux - API Reference

C++ API reference for the Linux VDS. Functions, operating modes, and JSON payloads.

Introduction

The Linux Verifier Device Service (VDS) is a software development kit from Credence ID that provides C++ application interfaces for developers/integrators to communicate with the Tap2iD® Verifier.

Service Overview

→Adds in-person identity verification to your business application.
→Provides C++ APIs to integrate the Tap2iD reader with a Linux client application.
→Adds digital ID verification to any Linux PC.
→Supports Tap2iD-initiated and operator-initiated verification flows.
→Distributed as a shared library (libvds.so) with C++ headers (vds.h).

Tap2iD Operating Modes

The Tap2iD device supports two operating modes:

STANDALONE

Standalone Mode

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

HOST_DRIVEN

Host Driven Mode

Tap2iD remains passive until the client application calls ReadIDInfo(). Once activated, it accepts NFC, mDL, or non-mDL QR scans. After the transaction completes, Tap2iD returns to its passive state.

ℹ

HOLDER_DRIVEN is deprecated and provided only for backward compatibility. Use HOST_DRIVEN or STANDALONE.

Overview of Functions

Category	API	Description
Device Mgmt.	`Init`	Initializes the VDS library and establishes the USB connection. Must be called first.
	`DeInit`	Releases all USB resources and stops background threads. Must be called before exit.
	`GetReaderInfo`	Returns Tap2iD reader info: device make/model, OS version, network status, reader profile, and more.
	`GetReaderConnectionStatus`	Returns the connectivity status of Tap2iD with the Linux PC.
	`SetDeviceMode`	Sets Tap2iD to `HOST_DRIVEN` or `STANDALONE`.
	`SetDeviceProfile`	Deprecated. Provided only for backward compatibility.
Verification	`ReadIDInfo`	Initiates Tap2iD to read a digital ID (mDL) or physical ID. Asynchronous via `ReadIDCallback`.
	`StopReadID`	Cancels an active `ReadIDInfo` session before the holder presents their credential.
	`SetBarcodeData`	Forwards externally-captured barcode/QR data to Tap2iD. Requires an active `ReadIDInfo` session.
Logging	`SetLogLevel`	Sets the VDS library logging verbosity (DEBUG, INFO, ERROR, NONE).

API Specifications

Public C++ APIs for accessing Tap2iD device settings, reading mDL/physical ID information, and managing the VDS library lifecycle.

device Init() Initialize VDS ›

Initializes the VDS library, sets up the libusb context, starts the event loop thread, and connects to the Tap2iD device over USB. If the device is not in AOA (Android Open Accessory) mode, Init() attempts to switch it. An internal retry waits for the Tap2iD Android application to be ready. Must be called once before any other VDS API.

STANDALONE HOST_DRIVEN

Input Parameters

None

ℹ

Init() returns void. Call GetReaderInfo() after Init() and inspect deviceState. "CONNECTED" means the device is ready. Anything else means the device was not found within the 15-second window. Call DeInit() before retrying.

Confirming successful initialization

cpp

Init();
nlohmann::json info = GetReaderInfo();
if (info != nullptr && info.value("deviceState", "") == "CONNECTED") {
  // Device is ready. Proceed with SetDeviceMode and ReadIDInfo.
} else {
  // Device not found or not yet ready.
  DeInit();
}

Output: GetReaderInfo() after successful Init()

json

{
  "applicationVersion": "2.0.1",
  "debugMode":         false,
  "deviceID":          "f35eaf3bd2e53785",
  "deviceMakeAndModel": "cIDReader",
  "deviceState":       "CONNECTED",
  "deviceType":        "Tap2iD",
  "networkSsidStatus": "CID-Main",
  "networkStatus":     true,
  "osVersion":         "cIDReader 11 user 1.0.0_14",
  "readerProfile":     "systemsteam",
  "serialNumber":      "000000001089",
  "usbMode":           "HOST_DRIVEN"
}

Error condition

If the device is not connected or not supported, GetReaderInfo() returns a JSON object with "deviceState": "NOT_CONNECTED" and the VDS library logs an error. No error JSON is returned by Init() itself.

device GetReaderInfo() Get Reader Info ›

Identifies the Credence ID Tap2iD device and reports its status: connectivity, OS/firmware versions, network status, reader profile, and operating mode.

STANDALONE HOST_DRIVEN

Input Parameters

None

Success: JSON response

json

{
  "applicationVersion": "2.0.1",
  "debugMode":         false,
  "deviceID":          "f35eaf3bd2e53785",
  "deviceMakeAndModel": "cIDReader",
  "deviceState":       "CONNECTED",
  "deviceType":        "Tap2iD",
  "networkSsidStatus": "CID-Main",
  "networkStatus":     true,
  "osVersion":         "cIDReader 11 user 1.0.0_14",
  "readerProfile":     "systemsteam",
  "serialNumber":      "000000001089",
  "usbMode":           "HOST_DRIVEN"
}

Error: JSON with null fields

json

{
  "applicationVersion": "null",
  "debugMode":         null,
  "deviceID":          "null",
  "deviceMakeAndModel": "null",
  "deviceState":       "NOT_CONNECTED",
  "deviceType":        "null",
  "networkSsidStatus": "null",
  "networkStatus":     null,
  "osVersion":         "null",
  "readerProfile":     "null",
  "serialNumber":      "null",
  "usbMode":           "null"
}

Field values

Field	Possible values
deviceState	`NOT_CONNECTED`: Tap2iD is not connected. `CONNECTED`: the device is connected and can communicate with Tap2iD.
usbMode	`STANDALONE`: scanned ID data is not transferred over USB. `HOST_DRIVEN`: Tap2iD is waiting for a VDS command to activate device reading.

device GetReaderConnectionStatus() Get Connection Status ›

Returns the connectivity status of Tap2iD with the Linux PC.

STANDALONE HOST_DRIVEN

Input Parameters

None

Success

json

{ "Device status": "CONNECTED" }

Error

json

{ "Device status": "NOT_CONNECTED" }

device SetDeviceMode(eDevMode) Set Device Mode ›

Sets Tap2iD to the desired operating mode.

STANDALONE HOST_DRIVEN

Input parameter (enum)

cpp

typedef enum {
  HOST_DRIVEN,
  STANDALONE,
  HOLDER_DRIVEN  // Deprecated and provided for backward compatibility.
} eDevMode;

device SetDeviceProfile(eDevProfile) Set Device Profile (deprecated) ›

Deprecated and provided only for backward compatibility. The profile is now set through Verify with Credence (VwC).

STANDALONE HOST_DRIVEN

Input parameter (enum)

cpp

typedef enum {
  ID_CHECK,
  AGE_CHECK
} eDevProfile;

verify ReadIDInfo(ReadIDCallback) Read ID Info ›

Asynchronous API that triggers Tap2iD to initiate an ID read session: mDL (ISO 18013-5), QR code, or PDF417 barcode. Returns immediately and delivers the result exactly once via the ReadIDCallback function pointer. The callback is invoked from an internal libusb event thread, so any shared state must be properly synchronized.

HOST_DRIVEN

Input Parameters

A function pointer of type ReadIDCallback. Invoked exactly once per call, delivering identity data or an error JSON.

ℹ

Operates in HOST_DRIVEN mode only. Set the device to HOST_DRIVEN via SetDeviceMode() before calling this API.

ℹ

Only one session may be active at a time. A concurrent call is rejected with error code 515 ("ID Verification service busy"). Wait for the callback to fire before calling again.

ℹ

Internal timeout is 60 seconds. If no response arrives, the VDS library sends StopReadID internally and delivers the result to the ReadID callback.

Error JSON codes

Code	Message and condition
511	`"Tap2iD is not connected"`: device not connected when called.
512	`"ID READ operation is terminated"`: `StopReadID()` was called and confirmed the stop.
513	`"Unexpected Error."`: USB transfer cancelled or device disconnected mid-scan. Call `DeInit()` + `Init()` to recover.
514	`"Tap2iD is not in HOST_DRIVEN mode..."`: call `SetDeviceMode()` first.
515	`"ID Verification service busy. Please try again shortly."`: concurrent session rejected.
516	`"Operation not permitted"`

Success: mDL (ISO 18013) JSON

json

{
  "docType": "IDENTITY",
  "transactionID": "",
  "deviceID": "",
  "validationErrorCode": 100,
  "validationErrorMessage": "",
  "data": {
    "type": "ISO18013",
    "familyName": "Doe",
    "givenNames": "Stefan",
    "birthDate": "",
    "issueDate": 1678304350,
    "expiryDate": 1678304350,
    "issuingAuthority": "CredenceID",
    "documentNumber": "987654321",
    "sex": "Male",
    "isAgeOver18": true,
    "isAgeOver21": true
    // ... additional fields
  }
}

Success: QR Code JSON

json

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

Success: PDF417 (AAMVA) JSON

json

{
  "docType": "IDENTITY",
  "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",
    "isAgeOver21": true
    // ... additional fields
  }
}

verify StopReadID() Stop Read ID ›

Cancels a ReadIDInfo() operation that is currently waiting for the ID holder to present their credential. Synchronous: sends a stop command and blocks for up to 1 second waiting for confirmation. If Tap2iD has already begun transmitting mDL data, the stop cannot be honoured. The mDL data is delivered normally to ReadIDCallback and StopReadID() returns error 517.

HOST_DRIVEN

Input Parameters

None

ℹ

Error 512 is delivered to the ReadIDCallback registered during ReadIDInfo(): not to the caller of StopReadID(). StopReadID()'s own return value indicates whether the stop request was acknowledged.

ℹ

Do not call unless an active ReadIDInfo() session is in progress. With no active session, StopReadID() returns 517 immediately without sending any USB command.

Success / cancellation cases

json

// Code 512: delivered to ReadIDCallback after a confirmed stop
{
  "errorCode": "512",
  "errorMessage": "ID READ operation is terminated"
}

// Code 0: returned by StopReadID() itself on success
{
  "errorCode": "0",
  "errorMessage": "ID READ operation is terminated"
}

Error codes

Code	Message and condition
511	`"Tap2iD is not connected"`: device not connected when called.
517	`"STOP cannot be invoked."`: no active `ReadIDInfo` session.
518	`"Tap2iD is busy, please try again."`: Tap2iD is currently transmitting mDL data.

verify SetBarcodeData(std::string) Set Barcode Data ›

Forwards externally-captured barcode or QR code data to the Tap2iD device for ID verification. Intended for workflows where barcode capture is performed by an external device (for example, a POS) rather than by Tap2iD itself.

HOST_DRIVEN

Input Parameters

The raw barcode or QR code string captured by the external device, in either mdoc or a valid PDF417 format.

ℹ

Requires an active ReadIDInfo() session. If called without one, the SetBarcodeData call is silently discarded.

ℹ

If Tap2iD has already begun receiving mDL data (the holder presented their mDL before SetBarcodeData() was called), the call is silently discarded and the mDL data is delivered normally via ReadIDCallback.

SetBarcodeData() returns void and provides no error callback or return value. All precondition failures (device not connected, wrong mode, no active session, mDL already in progress) are silently discarded. The verification result is delivered asynchronously via the ReadIDCallback registered in the preceding ReadIDInfo() call.

device DeInit() De-initialize VDS ›

Releases all VDS library resources: closes the USB device handle, releases the libusb context, and stops the event loop background thread. Call before application exit or before calling Init() again to reset the library state. If a ReadIDInfo() session is active, DeInit() waits up to 60 seconds for it to conclude before tearing down.

STANDALONE HOST_DRIVEN

Input Parameters

None

ℹ

Always call DeInit() before application exit to avoid resource leaks. After DeInit(), all subsequent API calls (except Init()) are no-ops or return error 511 until Init() is called again.

ℹ

Init() calls DeInit() implicitly in two situations: (1) if the library is already initialised when Init() is invoked, and (2) if the device fails to become ready within the 15-second internal retry window. In both cases the application does not need to call DeInit() explicitly first.

log SetLogLevel(LogLevel) Set Log Level ›

Sets the verbosity of VDS library logging output. Log output is written to stdout via spdlog. Adjust the log level to control diagnostic information emitted during development and production.

STANDALONE HOST_DRIVEN

Input parameter

cpp

enum class LogLevel {
  DEBUG, // Verbose: all internal state changes, USB bytes, JSON payloads.
  INFO,  // General: connection events, mode changes, session start/stop.
  ERROR, // Errors only: connection failures, USB errors, JSON parse failures.
  NONE   // No output. Recommended for production.
};

Example

cpp

SetLogLevel(LogLevel::NONE);  // Production: no log output.
SetLogLevel(LogLevel::DEBUG); // Development: full diagnostic output.