Send Commands

The Commands API enables queuing preset commands across devices under a location and inspecting command execution status and response logs.

Endpoints Overview

Method	Endpoint	Description
`POST`	`/api/commands`	Queue a preset command for execution on a device
`GET`	`/api/commands/{command_id}`	Retrieve status and execution details for a command

Send Command

POST /api/commands

Send a new preset command for execution on a specific device.

Request Parameters (`CommandCreate`)

Parameter	Type	Required	Default	Description
`command`	String	Yes	None	Preset command identifier (e.g. `reboot`, `door-open`, `enroll-biometric`).
`sn`	String	Yes	None	Target device serial number.
`priority`	Integer	No	`0`	Command execution priority (`0` to `100`). Higher numbers process first.
`params`	Object	No	`null`	Parameters required by specific command (see parameters reference below).

Response Attributes (`CommandResponse`)

Attribute	Type	Description
`id`	Integer	Unique command database ID.
`command`	String	Preset command name (e.g. `"reboot"`, `"door-open"`).
`priority`	Integer	Command execution priority (`0`-`100`).
`location_id`	Integer \| Null	Location ID.
`location`	LocationBasic \| Null	Basic object containing location `id` and `name`.
`sn`	String \| Null	Target device serial number.
`status`	String	Execution status (`"pending"`, `"sent"`, `"success"`, `"failed"`).
`response`	String \| Null	Device raw ACK output string upon execution completion.
`error_message`	String \| Null	Error detail string if command failed.
`sent_at`	String (ISO 8601) \| Null	Timestamp when dispatched to device.
`acknowledged_at`	String (ISO 8601) \| Null	Timestamp when ACK received from device.
`is_active`	Boolean	Active status flag.
`created_at`	String (ISO 8601)	Timestamp command was queued.
`updated_at`	String (ISO 8601) \| Null	Timestamp command was updated.

Response Example

201 Created

json

{
  "id": 1052,
  "command": "reboot",
  "priority": 5,
  "location_id": 1,
  "location": {
    "id": 1,
    "name": "Headquarters Office"
  },
  "sn": "AFK921400123",
  "status": "pending",
  "response": null,
  "error_message": null,
  "sent_at": null,
  "acknowledged_at": null,
  "is_active": true,
  "created_at": "2026-08-26T17:50:00Z",
  "updated_at": null
}

System Commands

Commands for querying device hardware state, resetting hardware, and reloading system configurations.

`reboot` v2.x, v3.x

Restart device hardware (alias: restart).

Required Parameters: None (params: null)

json

{
  "command": "reboot",
  "sn": "AFK921400123",
  "priority": 5
}

`info` v2.x, v3.x

Fetch options, system metrics, firmware versions, and serial number options.

Required Parameters: None (params: null)

json

{
  "command": "info",
  "sn": "AFK921400123",
  "priority": 0
}

`check` v2.x, v3.x

Perform hardware connectivity check and ping status.

Required Parameters: None (params: null)

json

{
  "command": "check",
  "sn": "AFK921400123",
  "priority": 0
}

`reload-options` v2.x, v3.x

Force device to reload stored configuration parameters and options.

Required Parameters: None (params: null)

json

{
  "command": "reload-options",
  "sn": "AFK921400123",
  "priority": 0
}

Access Control Commands

Commands for door relay operations, passage modes, alarms, and emergency overrides.

`door-open` v3.x

Trigger door relay unlock for specified index and duration.

Parameters

Parameter	Type	Required	Default	Description
`door_id`	Integer	Yes	`1`	Door relay index (`1` to `4`).
`duration`	Integer	Yes	`5`	Unlock duration in seconds.

json

{
  "command": "door-open",
  "sn": "AFK921400123",
  "priority": 10,
  "params": {
    "door_id": 1,
    "duration": 5
  }
}

`door-close` v3.x

Close active door relay immediately.

Required Parameters: None (params: null)

json

{
  "command": "door-close",
  "sn": "AFK921400123",
  "priority": 0
}

`door-lock` v3.x

Force lock door relay (restricts access until unlocked).

Required Parameters: None (params: null)

json

{
  "command": "door-lock",
  "sn": "AFK921400123",
  "priority": 0
}

`door-unlock` v2.x, v3.x

Unlock door relay.

Required Parameters: None (params: null)

json

{
  "command": "door-unlock",
  "sn": "AFK921400123",
  "priority": 0
}

`normal-open` v3.x

Set door to passage mode (unlocked state for unrestricted entry).

Required Parameters: None (params: null)

json

{
  "command": "normal-open",
  "sn": "AFK921400123",
  "priority": 0
}

`cancel-alarm` v3.x

Cancel active tamper or breach alarm.

Required Parameters: None (params: null)

json

{
  "command": "cancel-alarm",
  "sn": "AFK921400123",
  "priority": 0
}

`clear-alarm` v2.x, v3.x

Reset alarm state on device.

Required Parameters: None (params: null)

json

{
  "command": "clear-alarm",
  "sn": "AFK921400123",
  "priority": 0
}

`emergency-on` v3.x

Trigger emergency mode (unlocks all doors / triggers emergency protocol).

Required Parameters: None (params: null)

json

{
  "command": "emergency-on",
  "sn": "AFK921400123",
  "priority": 100
}

`emergency-off` v3.x

Release emergency mode and resume normal hardware operations.

Required Parameters: None (params: null)

json

{
  "command": "emergency-off",
  "sn": "AFK921400123",
  "priority": 100
}

User Management Commands

Commands for fetching and syncing user profile data.

`load-users` v2.x, v3.x

Fetch user profiles from device hardware memory to server.

Parameters

Parameter	Type	Required	Default	Description
`user_id`	Integer	No	`null`	Database user ID if fetching specific user.
`pin`	Integer	No	`null`	Target user PIN number. If omitted, loads all users.

json

{
  "command": "load-users",
  "sn": "AFK921400123",
  "priority": 0,
  "params": {
    "user_id": 84,
    "pin": 10042
  }
}

`sync-users` v2.x, v3.x

Push pending user profiles from database to device hardware.

Required Parameters: None (params: null)

json

{
  "command": "sync-users",
  "sn": "AFK921400123",
  "priority": 0
}

Biometric Enrollment Commands

Commands for initiating remote biometric enrollment on edge hardware.

`enroll-biometric` v2.x, v3.x

Initiate remote biometric fingerprint or face enrollment scan on hardware.

Parameters

Parameter	Type	Required	Default	Options / Enums	Description
`pin`	Integer	Yes	None	`1` to `99999999`	User PIN number to associate biometric with.
`user_id`	Integer	Yes	None	Numeric	Target user database ID.
`type`	String	Yes	`"fingerprint"`	`"fingerprint"`, `"face"`	Biometric template type.
`fid`	Integer	No	`0`	`0`-`9` (Finger position) or `111` (Face)	Finger index (`0`=Right Thumb, `1`=Right Index, `2`=Right Middle, etc.) or `111` for face scan.
`retry`	Integer	No	`3`	`1`, `2`, `3`	Number of scan verification passes required.
`overwrite`	Integer	No	`1`	`1` (Yes), `0` (No)	Overwrite existing template if present.

Fingerprint EnrollmentFace Enrollment

json

{
  "command": "enroll-biometric",
  "sn": "AFK921400123",
  "priority": 0,
  "params": {
    "user_id": 84,
    "pin": 10042,
    "type": "fingerprint",
    "fid": 1,
    "retry": 3,
    "overwrite": 1
  }
}

json

{
  "command": "enroll-biometric",
  "sn": "AFK921400123",
  "priority": 0,
  "params": {
    "user_id": 84,
    "pin": 10042,
    "type": "face",
    "fid": 111,
    "retry": 1,
    "overwrite": 1
  }
}

Log Management Commands

Commands for extracting transaction logs and attendance records.

`check-attendance` v2.x, v3.x

Fetch attendance transaction logs from device memory.

Parameters

Parameter	Type	Required	Default	Description
`startDate`	String	No	`null`	Start date filter (`YYYY-MM-DD`).
`endDate`	String	No	`null`	End date filter (`YYYY-MM-DD`). If omitted, loads all logs.

json

{
  "command": "check-attendance",
  "sn": "AFK921400123",
  "priority": 0,
  "params": {
    "startDate": "2026-08-01",
    "endDate": "2026-08-26"
  }
}

Clear Commands (Destructive)

Destructive commands for clearing device memory partitions.

WARNING

Clear commands permanently purge stored records from device memory. Proceed with caution.

`clear-log` v2.x, v3.x

Delete attendance transaction log records from device storage.

Required Parameters: None (params: null)

json

{
  "command": "clear-log",
  "sn": "AFK921400123",
  "priority": 0
}

`clear-photo` v2.x, v3.x

Delete attendance photo capture images from device hardware.

Required Parameters: None (params: null)

json

{
  "command": "clear-photo",
  "sn": "AFK921400123",
  "priority": 0
}

`clear-biodata` v2.x, v3.x

Delete fingerprint and face biometric templates from device hardware.

Required Parameters: None (params: null)

json

{
  "command": "clear-biodata",
  "sn": "AFK921400123",
  "priority": 0
}

`clear-data` v2.x, v3.x

Delete ALL stored device data (user profiles, biometric templates, transaction logs).

Required Parameters: None (params: null)

json

{
  "command": "clear-data",
  "sn": "AFK921400123",
  "priority": 100
}

Advanced Commands

Commands for system administration, firmware flashing, and direct protocol interaction.

`firmware-upgrade` v2.x, v3.x

Remotely flash device hardware firmware binary via download URL.

CAUTION

Ensure firmware binary URL and MD5 checksum are valid before issuing.

Parameters

Parameter	Type	Required	Description
`url`	String	Yes	Download URL for firmware binary (`https://...`).
`checksum`	String	Yes	MD5 checksum hash of firmware file.
`size`	Integer	Yes	File size in bytes (e.g. `12582912`).

json

{
  "command": "firmware-upgrade",
  "sn": "AFK921400123",
  "priority": 50,
  "params": {
    "url": "https://firmware.example.com/v8.0.4.bin",
    "checksum": "e10adc3949ba59abbe56e057f20f883e",
    "size": 12582912
  }
}

`shell-command` v2.x, v3.x

Execute raw OS shell command string on hardware device Linux environment.

Parameters

Parameter	Type	Required	Description
`command`	String	Yes	System command string to execute (e.g. `"ls -la"`).

json

{
  "command": "shell-command",
  "sn": "AFK921400123",
  "priority": 10,
  "params": {
    "command": "ls -la"
  }
}

`custom` v2.x, v3.x

Pass raw ZKTeco Push SDK protocol command string directly to hardware.

Parameters

Parameter	Type	Required	Description
`command`	String	Yes	Raw device Push SDK protocol command string (e.g. `"DATA DELETE user"`).

json

{
  "command": "DATA DELETE user",
  "sn": "AFK921400123",
  "priority": 0
}

Get Command Details

GET /api/commands/{command_id}

Retrieve status and execution details for a queued command by ID.

Path Parameters

Parameter	Type	Required	Description
`command_id`	Integer	Yes	Unique ID of command to inspect.

Response Attributes

Returns CommandResponse object (see attribute table above). Security policy guarantees that internal device protocol commands are reverted back to preset identifiers before returning.

Response Example

200 OK

json

{
  "id": 1052,
  "command": "reboot",
  "priority": 5,
  "location_id": 1,
  "location": {
    "id": 1,
    "name": "Headquarters Office"
  },
  "sn": "AFK921400123",
  "status": "success",
  "response": "OK",
  "error_message": null,
  "sent_at": "2026-08-26T17:50:02Z",
  "acknowledged_at": "2026-08-26T17:50:05Z",
  "is_active": true,
  "created_at": "2026-08-26T17:50:00Z",
  "updated_at": "2026-08-26T17:50:05Z"
}

Send Commands ​

Endpoints Overview ​

Send Command ​

Request Parameters (CommandCreate) ​

Response Attributes (CommandResponse) ​

Response Example ​

System Commands ​

reboot v2.x, v3.x ​

info v2.x, v3.x ​

check v2.x, v3.x ​

reload-options v2.x, v3.x ​

Access Control Commands ​

door-open v3.x ​

Parameters ​

door-close v3.x ​

door-lock v3.x ​

door-unlock v2.x, v3.x ​

normal-open v3.x ​

cancel-alarm v3.x ​

clear-alarm v2.x, v3.x ​

emergency-on v3.x ​

emergency-off v3.x ​

User Management Commands ​

load-users v2.x, v3.x ​

Parameters ​

sync-users v2.x, v3.x ​

Biometric Enrollment Commands ​

enroll-biometric v2.x, v3.x ​

Parameters ​

Log Management Commands ​

check-attendance v2.x, v3.x ​

Parameters ​

Clear Commands (Destructive) ​

clear-log v2.x, v3.x ​

clear-photo v2.x, v3.x ​

clear-biodata v2.x, v3.x ​

clear-data v2.x, v3.x ​

Advanced Commands ​

firmware-upgrade v2.x, v3.x ​

Parameters ​

shell-command v2.x, v3.x ​

Parameters ​

custom v2.x, v3.x ​

Parameters ​

Get Command Details ​

Path Parameters ​

Response Attributes ​

Response Example ​

Send Commands

Endpoints Overview

Send Command

Request Parameters (`CommandCreate`)

Response Attributes (`CommandResponse`)

Response Example

System Commands

`reboot` v2.x, v3.x

`info` v2.x, v3.x

`check` v2.x, v3.x

`reload-options` v2.x, v3.x

Access Control Commands

`door-open` v3.x

Parameters

`door-close` v3.x

`door-lock` v3.x

`door-unlock` v2.x, v3.x

`normal-open` v3.x

`cancel-alarm` v3.x

`clear-alarm` v2.x, v3.x

`emergency-on` v3.x

`emergency-off` v3.x

User Management Commands

`load-users` v2.x, v3.x

Parameters

`sync-users` v2.x, v3.x

Biometric Enrollment Commands

`enroll-biometric` v2.x, v3.x

Parameters

Log Management Commands

`check-attendance` v2.x, v3.x

Parameters

Clear Commands (Destructive)

`clear-log` v2.x, v3.x

`clear-photo` v2.x, v3.x

`clear-biodata` v2.x, v3.x

`clear-data` v2.x, v3.x

Advanced Commands

`firmware-upgrade` v2.x, v3.x

Parameters

`shell-command` v2.x, v3.x

Parameters

`custom` v2.x, v3.x

Parameters

Get Command Details

Path Parameters

Response Attributes

Response Example