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

Get started for freeTalk to us