Skip to main content
GET
/
devices
/
{device_id}
/
info
Get Device Info
curl --request GET \
  --url https://api.example.com/devices/{device_id}/info
{
  "success": true,
  "data": {
    "id": "<string>",
    "name": "<string>",
    "ip": "<string>",
    "serialnumber": "<string>",
    "device_name": "<string>",
    "platform": "<string>",
    "firmware_version": "<string>",
    "users_count": 123,
    "device_time": "<string>"
  },
  "error": "<string>"
}
Connects to the device and retrieves comprehensive technical information including hardware details, firmware version, and current statistics. The device is temporarily disabled during the query to ensure accurate data retrieval.

​
Path Parameters

​
device_id
string
required
The unique identifier of the deviceExample: "principal" or "bodega"

​
Response

​
success
boolean
required
Indicates whether the request was successful
​
data
object
Device technical information (present on success)
​
error
string
Error message if the operation failed

​
Example Request

curl -X GET https://your-server.com/devices/principal/info

​
Example Response

​
Success (200)

{
  "success": true,
  "data": {
    "id": "principal",
    "name": "Entrada Principal",
    "ip": "192.168.1.205",
    "serialnumber": "DGD9190019050335169",
    "device_name": "ZK-X628",
    "platform": "ZEM560",
    "firmware_version": "Ver 6.60 Apr 28 2016",
    "users_count": 45,
    "device_time": "2026-03-06 15:45:30"
  }
}

​
Error: Connection Failed (500)

{
  "success": false,
  "error": "[Errno 111] Connection refused"
}

​
Error: Device Not Found (404)

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

​
Error Codes

Status CodeDescription
200Device information retrieved successfully
404Device with the specified ID does not exist
500Internal server error (connection or communication failure)

​
Device Operation During Request

The device is temporarily disabled during the information retrieval process to ensure accurate data collection. It is automatically re-enabled before the connection closes.
The operation sequence is:
  1. Connect to device
  2. Disable device (prevents normal operations)
  3. Query all information fields
  4. Re-enable device (restores normal operation)
  5. Disconnect
The disable/enable cycle typically takes less than 1 second and minimally impacts device operation.

​
Information Fields Explained

FieldDescription
serialnumberUnique hardware identifier, useful for warranty and support
device_nameModel name (e.g., “ZK-X628”, “K40”)
platformHardware platform (e.g., “ZEM560”, “ZEM800”)
firmware_versionCurrent firmware with build date
users_countNumber of enrolled users (includes all users, active or not)
device_timeDevice’s internal clock (compare with server time to detect drift)

​
Use Cases

  • Device inventory: Collect serial numbers and models for asset management
  • Capacity planning: Monitor user counts to plan device allocation
  • Firmware management: Identify devices that need firmware updates
  • Time synchronization: Compare device time with server time
  • Support and troubleshooting: Gather device details for technical support
  • Compliance: Document hardware and firmware versions for audit purposes

​
Notes

  • This endpoint uses a thread lock to prevent concurrent operations
  • The connection is automatically closed after retrieving information
  • The device is always re-enabled, even if an error occurs during data collection
  • User count reflects all enrolled users, not just active users
  • Consider caching this data if you need to display it frequently, as each call requires a full device connection

Build docs developers (and LLMs) love

Get started for freeTalk to us