Skip to main content
GET
/
devices
/
{device_id}
/
users
List Users
curl --request GET \
  --url https://api.example.com/devices/{device_id}/users

​
Overview

This endpoint retrieves all users registered on the specified ZKTeco biometric device. The device is temporarily disabled during the operation to ensure data consistency.

​
Path Parameters

​
device_id
string
required
The unique identifier of the device to query users from. This ID must match a registered device in the system.

​
Response

​
Success Response (200)

Returns a JSON object with user information: 
{
  "success": true,
  "total": 2,
  "data": [
    {
      "uid": 1,
      "user_id": "123",
      "name": "Juan Perez",
      "privilege": 0,
      "card": 12345,
      "device_id": "principal"
    },
    {
      "uid": 2,
      "user_id": "456",
      "name": "Maria Garcia",
      "privilege": 14,
      "card": 0,
      "device_id": "principal"
    }
  ]
}

​
Response Fields

  • success (boolean): Indicates if the operation was successful
  • total (integer): Number of users found on the device
  • data (array): Array of user objects
    • uid (integer): Internal unique identifier assigned by the device
    • user_id (string): User’s enrollment ID (badge number)
    • name (string): User’s full name
    • privilege (integer): User privilege level (see note below)
    • card (integer): RFID card number (0 if no card assigned)
    • device_id (string): ID of the device this user belongs to

​
Error Responses

​
Device Not Found (404)

{
  "success": false,
  "error": "Dispositivo 'bodega' no encontrado.",
  "disponibles": ["principal", "entrada"]
}

​
Connection Error (500)

{
  "success": false,
  "error": "Connection timeout to device 192.168.1.205:4370"
}

​
Privilege Levels

Privilege Levels:
  • 0 = Standard user (employee)
  • 14 = Administrator user
Administrators typically have access to device management functions on the physical device.

​
Example Request

curl -X GET "https://your-server.com/devices/principal/users" \
  -H "Content-Type: application/json"

​
Implementation Details

  • The device is temporarily disabled during the operation to prevent conflicts
  • The device is automatically re-enabled after the operation completes
  • Thread-safe: Uses device-specific locks to prevent concurrent operations
  • Connection is automatically closed after the operation

​
Use Cases

  • Display all employees enrolled in a specific access point
  • Audit user access permissions across devices
  • Export user lists for reporting
  • Verify user enrollment status

Build docs developers (and LLMs) love

Get started for freeTalk to us