Overview
This endpoint creates a new user on the specified ZKTeco biometric device. The user is immediately registered and can be used for attendance tracking. Fingerprint enrollment must be done separately using the enroll-finger endpoint.
Path Parameters
The unique identifier of the device where the user will be created. This ID must match a registered device in the system.
Request Body
The unique enrollment ID for the user (badge number). This must be unique within the device. Common formats include numeric strings like “123” or “001”.
The full name of the user. This will be displayed on the device and in attendance reports.
Optional PIN/password for device access. Leave empty if not using password authentication.
User privilege level:
0 = Standard user (employee)14 = Administrator
Administrators have access to device management functions. RFID card number for card-based authentication. Set to 0 if the user doesn’t have a card.
Request Example
{
"user_id": "123",
"name": "Juan Perez",
"password": "1234",
"privilege": 0,
"card": 12345
}
Response
Success Response (200)
{
"success": true,
"message": "Usuario registrado.",
"data": {
"user_id": "123",
"name": "Juan Perez",
"device_id": "principal"
}
}
Error Responses
Missing Required Fields (400)
{
"success": false,
"error": "user_id y name son requeridos."
}
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 Already Exists (409)
{
"success": false,
"error": "user_id '123' ya existe."
}
Connection Error (500)
{
"success": false,
"error": "Connection timeout to device 192.168.1.205:4370"
}
Example Request
curl -X POST "https://your-server.com/devices/principal/users" \
-H "Content-Type: application/json" \
-d '{
"user_id": "123",
"name": "Juan Perez",
"password": "1234",
"privilege": 0,
"card": 12345
}'
Implementation Details
Validation
- user_id is converted to string and trimmed of whitespace
- name is converted to string and trimmed of whitespace
- Both
user_id and name must be non-empty after trimming
- The system checks for existing users with the same
user_id before creating
Device Operations
- Device is temporarily disabled during user creation
- Existing users are queried to check for duplicates
- User is created using the pyzk
set_user() method
- Device is automatically re-enabled after operation
- Connection is closed automatically
Thread Safety
The operation uses device-specific locks to prevent concurrent modifications to the same device.
Next Steps
After creating a user, you typically want to:
- Enroll fingerprints: Use
POST /devices/{device_id}/users/{user_id}/enroll-finger
- Verify creation: Use
GET /devices/{device_id}/users to list all users
- Test access: Have the user attempt to clock in/out on the device
Notes
The user_id must be unique within each device. If you need to register the same person on multiple devices, you must call this endpoint for each device separately.
Setting uid=None in the internal implementation allows the device to automatically assign the next available internal UID.