Fingerspot HubAPI

Welcome to the Fingerspot HubAPI — an async device command API for controlling Fingerspot biometric devices (fingerprint, face, palm-vein) from any HTTP client.

Architecture

Every command endpoint responds 200 immediately with an acknowledgement:

{
  "referenceId": "my-ref-123",
  "status": "queued",
  "deviceStatus": "connected",
  "message": "command queued successfully",
  "webhookUrls": ["http://your-server.com/webhook"]
}

The actual result is delivered asynchronously via a webhook POST to your registered callback URL. This means your HTTP request never blocks on the device — devices can take anywhere from milliseconds to minutes depending on the operation (e.g. live fingerprint capture).

Client                     HubAPI                     Device
  │                          │                          │
  ├── POST /v2/{cloud_id}/command ──────────────────────►│
  │◄── 200 ack (queued)       │                          │
  │                          │                          │
  │         [device processes command async]             │
  │                          │◄── result ───────────────│
  │                          │                          │
  │◄── POST webhook to your URL                         │

Webhook Delivery

The result is POSTed to up to 3 extra URLs (configurable via V2_WEBHOOK_MAX_URLS) sent in the X-Webhook-URL header as a comma-separated list, PLUS the device's registered webhook URL. All sends are concurrent.

Property	Value
Base URL	http://localhost:8080
Format	application/json
Authentication	Bearer Token (X-API-Key)
Command Timeout	30 minutes
Webhook Retries	5 (exponential backoff)
Webhook HTTP Timeout	10 seconds

API Version

Current version: v2.0.0. Breaking changes are communicated through the changelog.