Device Management

The Devices API allows location administrators to register, query, monitor status, and queue commands for ZKTeco biometric edge hardware.

Endpoints Overview

Method	Endpoint	Description
GET	/api/devices	Retrieve a paginated list of devices
POST	/api/devices	Assign a device to location
GET	/api/devices/{device_serial}	Retrieve detailed information for a device
GET	/api/devices/{device_serial}/status	Get real-time connection status
DELETE	/api/devices/{device_serial}	Unassign a device from location

List Devices

GET /api/devices

Retrieve a paginated list of devices assigned to the authenticated location.

Query Parameters

Parameter	Type	Required	Default	Description
page	Integer	No	1	Page number (1-indexed).
limit	Integer	No	15	Number of records per page.
search	String	No	null	Filter by device name or serial number.
is_active	Boolean	No	null	Filter by online/active status (true or false).

Response Attributes

Pagination Response Wrap

Attribute	Type	Description
data	Array[DeviceResponse]	List of device records for current page.
total	Integer	Total count of devices matching criteria.
page	Integer	Current page number.
limit	Integer	Limit per page.
total_pages	Integer	Calculated total number of pages.
has_next	Boolean	true if next page exists.
has_prev	Boolean	true if previous page exists.

DeviceResponse Attributes

Attribute	Type	Description
id	Integer	Device internal database ID.
name	String	Device display name (e.g., "Device AFK921400123").
serial_number	String	Device hardware serial number (SN).
location_id	Integer | Null	ID of assigned location.
location	LocationBasic | Null	Basic object containing id and name of location.
registry_code	String | Null	Device registration code.
session_id	String | Null	Active iClock session identifier.
registered_at	String (ISO 8601) | Null	Timestamp when device first registered with server.
options	Object | Null	Key-value dictionary of device options reported during handshake.
version	String | Null	Push SDK protocol version ("2.0.0" or "3.0.0").
last_seen	String (ISO 8601) | Null	Timestamp of last heartbeat request received from device.
is_active	Boolean	Device online status (true if connected within threshold).
created_at	String (ISO 8601)	Timestamp when record was created.
updated_at	String (ISO 8601) | Null	Timestamp when record was last updated.

Response Example

200 OK

{
  "data": [
    {
      "id": 12,
      "name": "Main Entrance Gate",
      "serial_number": "AFK921400123",
      "location_id": 1,
      "location": {
        "id": 1,
        "name": "Headquarters Office"
      },
      "registry_code": "REG-88231",
      "session_id": "sess_9941a",
      "registered_at": "2026-02-10T11:00:00Z",
      "options": {
        "~DeviceName": "SpeedFace-V5L",
        "FirmVer": "Ver 8.0.4.3-2024",
        "UserNum": "142",
        "FPNum": "210"
      },
      "version": "3.0.0",
      "last_seen": "2026-08-26T17:45:10Z",
      "is_active": true,
      "created_at": "2026-02-10T11:00:00Z",
      "updated_at": "2026-08-26T17:45:10Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 15,
  "total_pages": 1,
  "has_next": false,
  "has_prev": false
}

Assign Device

POST /api/devices

Assign a device (identified by serial number) to the authenticated location and automatically initiate user synchronization.

Request Body Parameters

Parameter	Type	Required	Description
sn	String	Yes	Device hardware serial number (SN).
name	String	No	Custom display name for the device (defaults to "Device {SN}").

Response Attributes

Returns the assigned DeviceResponse object.

Response Example

Request Body

{
  "sn": "AFK921400123",
  "name": "Front Gate SpeedFace"
}

201 Created

{
  "id": 12,
  "name": "Device AFK921400123",
  "serial_number": "AFK921400123",
  "location_id": 1,
  "location": {
    "id": 1,
    "name": "Headquarters Office"
  },
  "registry_code": null,
  "session_id": null,
  "registered_at": null,
  "options": null,
  "version": "3.0.0",
  "last_seen": null,
  "is_active": false,
  "created_at": "2026-08-26T17:49:00Z",
  "updated_at": "2026-08-26T17:49:00Z"
}

Get Device Details

GET /api/devices/{device_serial}

Retrieve detailed information for a specific device by its serial number.

Path Parameters

Parameter	Type	Required	Description
device_serial	String	Yes	Serial number of the target device.

Response Attributes

Returns DeviceResponse object.

Response Example

200 OK

{
  "id": 12,
  "name": "Main Entrance Gate",
  "serial_number": "AFK921400123",
  "location_id": 1,
  "location": {
    "id": 1,
    "name": "Headquarters Office"
  },
  "registry_code": "REG-88231",
  "session_id": "sess_9941a",
  "registered_at": "2026-02-10T11:00:00Z",
  "options": {
    "~DeviceName": "SpeedFace-V5L"
  },
  "version": "3.0.0",
  "last_seen": "2026-08-26T17:45:10Z",
  "is_active": true,
  "created_at": "2026-02-10T11:00:00Z",
  "updated_at": "2026-08-26T17:45:10Z"
}

Get Device Status

GET /api/devices/{device_serial}/status

Get light-weight real-time connection status and last heartbeat timestamp for a device.

Path Parameters

Parameter	Type	Required	Description
device_serial	String	Yes	Serial number of the target device.

Response Attributes

Attribute	Type	Description
device_id	Integer	Device internal database ID.
serial_number	String	Device hardware serial number.
is_online	Boolean	Online status flag (true if active).
last_seen	String (ISO 8601) | Null	Timestamp of last heartbeat.
status	String	Operational status string ("online" or "offline").

Response Example

200 OK

{
  "device_id": 12,
  "serial_number": "AFK921400123",
  "is_online": true,
  "last_seen": "2026-08-26T17:45:10Z",
  "status": "online"
}

Unassign Device

DELETE /api/devices/{device_serial}

Unassign and remove a device from the authenticated location. Operation is idempotent.

Path Parameters

Parameter	Type	Required	Description
device_serial	String	Yes	Serial number of device to unassign.

Response Example

204 No Content

{}