Getting Started

Follow these steps to send your first API request.

Step 1 — Prerequisites

• A Fingerspot device connected to the platform
• A cloud_id assigned to your device
• Your API token (Bearer token)

Step 2 — Synchronous Request

Some endpoints return data directly. Example: get device info:

curl -X POST https://developer.fingerspot.io/api/get_device \
  -H "Authorization: Bearer your-api-token" \
  -H "Content-Type: application/json" \
  -d '{"trans_id": "1", "cloud_id": "XXXXX"}'

Response:

{
  "success": true,
  "trans_id": "1",
  "data": {
    "cloud_id": "XXXXX",
    "device_name": "device 1",
    "webhook_url": "https://yourserver.example.com/webhook",
    "created_at": "2025-01-01 13:00:00",
    "last_activity": "N/A"
  }
}

Step 3 — Asynchronous Request

For asynchronous operations, the API returns an immediate confirmation. The actual result is delivered via webhook to your device's configured URL:

curl -X POST https://developer.fingerspot.io/api/get_userinfo \
  -H "Authorization: Bearer your-api-token" \
  -H "Content-Type: application/json" \
  -d '{"trans_id": "1", "cloud_id": "XXXXX", "pin": "1"}'

Ack response:

{
  "success": true,
  "trans_id": "1"
}

The webhook callback arrives at your registered URL with a matching trans_id:

{
  "type": "get_userinfo",
  "cloud_id": "XXXXX",
  "trans_id": "1",
  "data": {
    "pin": "1",
    "name": "john",
    "privilege": "1",
    "finger": "1",
    "face": "0",
    "password": "111",
    "rfid": "",
    "vein": "0",
    "template": "5345dsfd33242423asdas"
  }
}

More Webhook Examples

Attlog (Real-time Attendance Event)

Attendance events are sent spontaneously whenever a user performs a scan. There is no trans_id because this event is not triggered by an API call.

{
  "type": "attlog",
  "cloud_id": "XXXXX",
  "data": {
    "pin": "1",
    "scan": "2020-07-21 10:11",
    "verify": "1",
    "status_scan": "0"
  }
}

Field	Description
pin	User ID
scan	Scan time (YYYY-MM-DD HH:mm)
verify	Verification method: 1=finger, 2=password, 3=card, 4=face, 6=vein
status_scan	Status: 0=scan in, 1=scan out, 2=break in, 3=break out

Get User ID List

Result of a query for all user IDs registered on the device:

{
  "type": "get_userid_list",
  "cloud_id": "XXXXX",
  "trans_id": "1",
  "data": {
    "total": 3,
    "pin_arr": ["1", "2", "3"]
  }
}

Field	Description
total	Total number of registered users
pin_arr	Array containing all user IDs

Webhook URL

Each device has a configured webhook URL. Callbacks for asynchronous operations are delivered via POST to that URL. You can view and update it via the customer portal or the get_device API.