Overview
This endpoint updates an existing user’s information on the specified ZKTeco biometric device. You can modify the user’s name, password, privilege level, or card number. All fields in the request body are optional - only provided fields will be updated.
Path Parameters
The unique identifier of the device containing the user. This ID must match a registered device in the system.
The enrollment ID (badge number) of the user to update. This must match an existing user on the device.
Request Body
All fields are optional. Only include the fields you want to update. Omitted fields will retain their current values.
The updated full name for the user. This will be displayed on the device and in attendance reports.
Updated PIN/password for device access. Pass an empty string to remove the password.
Updated user privilege level:
0 = Standard user (employee)14 = Administrator
Use caution when granting administrator privileges. Updated RFID card number. Set to 0 to remove card access.
Request Examples
Update Name Only
{
"name": "Juan Carlos Perez"
}
Update Multiple Fields
{
"name": "Juan Carlos Perez",
"password": "5678",
"card": 67890
}
Response
Success Response (200)
{
"success": true,
"message": "Usuario '123' actualizado."
}
Error Responses
No JSON Body (400)
{
"success": false,
"error": "Body JSON requerido."
}
Device Not Found (404)
{
"success": false,
"error": "Dispositivo 'bodega' no encontrado.",
"disponibles": ["principal", "entrada"]
}
User Not Found (404)
{
"success": false,
"error": "Usuario '123' no encontrado."
}
Connection Error (500)
{
"success": false,
"error": "Connection timeout to device 192.168.1.205:4370"
}
Example Requests
Update User Name
curl -X PUT "https://your-server.com/devices/principal/users/123" \
-H "Content-Type: application/json" \
-d '{
"name": "Juan Carlos Perez"
}'
curl -X PUT "https://your-server.com/devices/principal/users/123" \
-H "Content-Type: application/json" \
-d '{
"privilege": 14
}'
Update Card Number
curl -X PUT "https://your-server.com/devices/principal/users/123" \
-H "Content-Type: application/json" \
-d '{
"card": 67890
}'
Implementation Details
Update Logic
- Device is temporarily disabled during the update
- System retrieves all users and locates the user by
user_id
- Current values are preserved for any fields not included in the request
- User is updated using the pyzk
set_user() method with the existing uid
- Device is automatically re-enabled after operation
- Connection is closed automatically
Field Preservation
The implementation uses the following pattern to preserve existing values:
conn.set_user(
uid=u.uid, # Internal UID (required, unchanged)
name=body.get("name", u.name), # Use new or keep existing
privilege=int(body.get("privilege", u.privilege)),
password=body.get("password", u.password),
group_id=u.group_id, # Always preserved
user_id=u.user_id, # Always preserved
card=int(body.get("card", u.card))
)
Thread Safety
The operation uses device-specific locks to prevent concurrent modifications to the same device.
Important Notes
You cannot change the user_id (enrollment ID) through this endpoint. The user_id is the unique identifier and must remain constant. To change a user’s ID, you must delete and recreate the user.
Changing a user’s privilege from 0 to 14 grants them administrator access on the physical device, allowing them to modify device settings and manage other users directly on the hardware.
Fingerprint templates are not affected by user updates. They remain associated with the user’s internal uid and will continue to work after updating user information.
Use Cases
- Correct misspelled names
- Update RFID card assignments when cards are replaced
- Promote employees to administrator status
- Reset user passwords
- Remove card access while keeping fingerprint authentication