Overview
This endpoint permanently deletes a user from the specified ZKTeco biometric device. This operation removes all user data including fingerprint templates, card associations, and attendance records linked to the user’s internal UID.
This is a destructive operation. Deleted users cannot be recovered. All fingerprint templates associated with the user will be permanently removed from the device.
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 delete. This must match an existing user on the device.
Response
Success Response (200)
{
"success": true,
"message": "Usuario '123' eliminado."
}
Error Responses
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 Request
curl -X DELETE "https://your-server.com/devices/principal/users/123" \
-H "Content-Type: application/json"
Implementation Details
Deletion Process
- Device is temporarily disabled during deletion
- System retrieves all users and locates the user by
user_id
- If user is not found, returns 404 error immediately
- User is deleted using the pyzk
delete_user() method with the user’s internal uid
- Device is automatically re-enabled after operation
- Connection is closed automatically
What Gets Deleted
When a user is deleted, the following data is permanently removed:
- User profile: Name, privilege level, password
- Fingerprint templates: All enrolled fingerprints for this user
- Card associations: RFID card number assignments
- Internal UID: The device’s internal unique identifier
What Is NOT Deleted
Attendance records are preserved. Historical attendance logs for this user remain in the device memory. They can still be retrieved using the attendance endpoints, but they will reference a user_id that no longer exists.
Thread Safety
The operation uses device-specific locks to prevent concurrent modifications to the same device.
Use Cases
- Employee termination: Remove access when an employee leaves
- User cleanup: Delete test users or incorrectly created accounts
- Access revocation: Immediately remove a user’s ability to access controlled areas
- Duplicate resolution: Remove duplicate user entries
Example Workflow: Offboarding an Employee
# 1. Verify the user exists
curl -X GET "https://your-server.com/devices/principal/users"
# 2. Check user's attendance history (optional)
curl -X GET "https://your-server.com/devices/principal/attendance?user_id=123"
# 3. Delete the user from all devices
curl -X DELETE "https://your-server.com/devices/principal/users/123"
curl -X DELETE "https://your-server.com/devices/entrance/users/123"
curl -X DELETE "https://your-server.com/devices/warehouse/users/123"
# 4. Verify deletion
curl -X GET "https://your-server.com/devices/principal/users"
Important Notes
Multi-device consideration: If the same user is registered on multiple devices, you must delete them from each device separately. Deleting a user from one device does not affect their registration on other devices.
No confirmation required: This endpoint performs immediate deletion without additional confirmation. Implement confirmation dialogs in your client application if needed.
Re-registration: If you delete a user and later need to re-add them, you can use the same user_id to create a new user. However, they will need to re-enroll all fingerprints.
Error Handling Best Practices
# Check if user exists before deletion
USER_EXISTS=$(curl -s -X GET "https://your-server.com/devices/principal/users" | \
jq -r ".data[] | select(.user_id==\"123\") | .user_id")
if [ "$USER_EXISTS" = "123" ]; then
curl -X DELETE "https://your-server.com/devices/principal/users/123"
echo "User deleted successfully"
else
echo "User not found, skipping deletion"
fi
Recovery Options
No built-in recovery: Once a user is deleted, there is no undo operation. Consider these preventive measures:
- Maintain user backups in your application database
- Log all deletion operations with timestamps
- Implement soft deletes in your application layer
- Export user data before deletion for audit purposes