Skip to main content
POST
/
devices
/
{device_id}
/
users
/
{user_id}
/
enroll-finger
curl -X POST \
  https://your-server.com/devices/principal/users/123/enroll-finger \
  -H 'Content-Type: application/json' \
  -d '{
    "finger_index": 1
  }'

{
  "success": true,
  "message": "Modo enrolamiento activado. El usuario debe poner el dedo 3 veces.",
  "data": {
    "user_id": "123",
    "device_id": "principal",
    "finger_index": 1,
    "finger_name": "Indice derecho"
  }
}

​
Overview

This endpoint activates enrollment mode on the ZKTeco device, allowing a user to register their fingerprint. The user must place their finger on the scanner 3 times to complete the enrollment process.

​
Path Parameters

​
device_id
string
required
The unique identifier of the device
​
user_id
string
required
The user ID of the person enrolling their fingerprint

​
Request Body

​
finger_index
integer
required
The finger position to enroll (0-9). See the finger mapping table below.

​
Finger Index Mapping (DEDOS)

The finger_index parameter maps 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

​
Enrollment Process

  1. Send the POST request with the desired finger_index
  2. The device enters enrollment mode
  3. The user must place their finger on the scanner 3 consecutive times
  4. The device captures and stores the fingerprint template
  5. The device automatically exits enrollment mode after completion
curl -X POST \
  https://your-server.com/devices/principal/users/123/enroll-finger \
  -H 'Content-Type: application/json' \
  -d '{
    "finger_index": 1
  }'

{
  "success": true,
  "message": "Modo enrolamiento activado. El usuario debe poner el dedo 3 veces.",
  "data": {
    "user_id": "123",
    "device_id": "principal",
    "finger_index": 1,
    "finger_name": "Indice derecho"
  }
}

​
Response Fields

​
success
boolean
Indicates whether the enrollment mode was activated successfully
​
message
string
Human-readable message about the enrollment status
​
data
object
Contains enrollment details

​
Error Codes

  • 400: Invalid finger_index (must be 0-9) or missing required fields
  • 404: Device or user not found
  • 500: Connection error or device communication failure

​
Important Notes

  • The device is temporarily disabled during enrollment to prevent interference
  • The user must be present at the device to place their finger 3 times
  • Each finger can only be enrolled once per user
  • The enrollment process times out if the user doesn’t complete it within the device’s timeout period
  • After successful enrollment, the fingerprint can be used for attendance tracking

Build docs developers (and LLMs) love

Get started for freeTalk to us