Skip to main content
GET
/
devices
/
{device_id}
/
users
/
{user_id}
/
fingers
curl -X GET \
  https://your-server.com/devices/principal/users/123/fingers
{
  "success": true,
  "user_id": "123",
  "name": "Juan Perez",
  "device_id": "principal",
  "total_fingers": 2,
  "data": [
    {
      "finger_index": 1,
      "finger_name": "Indice derecho",
      "valid": true
    },
    {
      "finger_index": 5,
      "finger_name": "Pulgar izquierdo",
      "valid": true
    }
  ]
}

Overview

This endpoint retrieves all fingerprint templates registered for a specific user on a ZKTeco device. Each fingerprint entry includes the finger index, finger name, and validation status.

Path Parameters

device_id
string
required
The unique identifier of the device
user_id
string
required
The user ID to retrieve fingerprints for
curl -X GET \
  https://your-server.com/devices/principal/users/123/fingers
{
  "success": true,
  "user_id": "123",
  "name": "Juan Perez",
  "device_id": "principal",
  "total_fingers": 2,
  "data": [
    {
      "finger_index": 1,
      "finger_name": "Indice derecho",
      "valid": true
    },
    {
      "finger_index": 5,
      "finger_name": "Pulgar izquierdo",
      "valid": true
    }
  ]
}

Response Fields

success
boolean
Indicates whether the request was successful
user_id
string
The user ID that was queried
name
string
The full name of the user
device_id
string
The device identifier
total_fingers
integer
The total number of fingerprints registered for this user
data
array
Array of registered fingerprint entries

Finger Index Mapping

The finger_index values correspond to specific fingers:
IndexFinger Name (Spanish)Finger Name (English)
0Pulgar derechoRight thumb
1Índice derechoRight index
2Medio derechoRight middle
3Anular derechoRight ring
4Meñique derechoRight pinky
5Pulgar izquierdoLeft thumb
6Índice izquierdoLeft index
7Medio izquierdoLeft middle
8Anular izquierdoLeft ring
9Meñique izquierdoLeft pinky

Error Codes

  • 404: Device or user not found
  • 500: Connection error or device communication failure

Implementation Details

This endpoint:
  1. Connects to the ZKTeco device
  2. Temporarily disables the device to prevent interference
  3. Retrieves all fingerprint templates from the device
  4. Filters templates to only include those belonging to the specified user
  5. Maps finger indices to human-readable names using the DEDOS dictionary
  6. Re-enables the device before returning the response

Use Cases

  • Verify Enrollment: Check which fingers a user has already enrolled
  • Enrollment UI: Display enrolled fingers to guide users in selecting available fingers
  • Audit: Review fingerprint registration status across users
  • Validation: Confirm successful fingerprint enrollment after calling the enroll endpoint

Build docs developers (and LLMs) love