AiFace Device Web API Protocol Documentation (English)

Version: 1.0

Based on: webserver.cpp source code analysis

Protocol: HTTP + JSON

⚠️ Protocol Role Note: In the WebServer API, the device acts as an HTTP server, and browsers or other clients access the device as requesters. Therefore, this protocol is restricted to Local Area Network (LAN) use only — clients must be on the same network segment as the device to access it.

1. Overview

This document describes the HTTP API protocol of the embedded web server in AiFace facial recognition access control devices.

1.1 Server Architecture

• Maximum concurrent connections: 20
• Idle connection timeout: 10 seconds
• Timeout response: HTTP 408 Timeout
• Server busy response: HTTP 503 Busy

2. Connection & Authentication

2.1 Login Flow

Except for the getlang command, all /api commands require a password field in the request. The password is configured in the device's settings menu (mapped to DI_WEBSERVER_PWD).

Note: If no password has been set on the device (empty password), all password-required endpoints will return an error.

2.2 Request Endpoint

All JSON API requests are sent to:

POST http://<device_IP>:<port>/api
Content-Type: application/json

3. Common Request Format

JSON{
  "cmd": "<command_name>",
  "password": "<device_password>",
  // ... command-specific parameters
}

4. Common Response Format

JSON{
  "ret": "<command_name>",
  "sn": "<device_serial_number>",
  "result": true/false,
  // ... command-specific response data
}

5. Error Codes

6. HTTP Route Endpoints

7. JSON API Command Reference

7.1 Authentication & Device Info

7.1.1 `getlang` — Get Current Language

No password required

Request:

JSON{ "cmd": "getlang" }

Response:

JSON{
  "ret": "getlang",
  "sn": "SN123456",
  "result": true,
  "lang": "English"
}

7.1.2 `getlangoption` — Get Available Language List

Request:

JSON{ "cmd": "getlangoption", "password": "xxx" }

Response:

JSON{
  "ret": "getlangoption",
  "sn": "SN123456",
  "result": true,
  "lang": "English",
  "langs": [
    { "lvalue": 0, "ltitle": "English" },
    { "lvalue": 1, "ltitle": "简体中文" }
  ]
}

7.1.3 `login` — Login Verification

Request:

JSON{
  "cmd": "login",
  "username": "admin",
  "password": "xxx"
}

Response (success):

JSON{
  "ret": "login",
  "sn": "SN123456",
  "result": true
}

Response (failure):

JSON{
  "ret": "login",
  "sn": "SN123456",
  "result": false,
  "reason": 1,
  "msg": "username error"
}

7.1.4 `reg` — Get Full Device Registration Info

Request:

JSON{ "cmd": "reg", "password": "xxx" }

Response devinfo field breakdown:

7.1.5 `getdevinfo` — Get Device Configuration Parameters

Request:

JSON{ "cmd": "getdevinfo", "password": "xxx" }

Response: Returns all DI_* configuration key-value pairs.

Response Example:

JSON{
  "ret": "getdevinfo",
  "sn": "SN123456",
  "result": true,
  "deviceid": 1,
  "language": 0,
  "managers": 1,
  "verifymode": 0,
  "volume": 80,
  "netipaddress": "192.168.1.100",
  "serverip": "192.168.1.200",
  "wlan_ssid": "MyWiFi",
  "door_opentime": 5,
  "live_detect": 1,
  "fcmatch_level": 60
}

Complete Configuration Parameter List:

##### General Settings

##### Biometric Settings

##### Serial & Network Settings

##### Server Settings

##### Door Access Settings

##### Wiegand Settings

##### Card & Security Settings

##### Other Settings

Type Notes: number = numeric, IP = IP address string (e.g. "192.168.1.100"), string = plain string.

7.1.6 `setdevinfo` — Set Device Configuration Parameters

Request:

JSON{
  "cmd": "setdevinfo",
  "password": "xxx",
  "nowtime": 1700000000,
  "deviceid": 1,
  "volume": 80,
  "live_detect": 1,
  "fcmatch_level": 60
}

Type Rules:
- IP-type fields (e.g. netipaddress, serverip, etc.) accept IP address strings like "192.168.1.100"
- String-type fields (e.g. wlan_ssid, excel_password, cpucard_key, etc.) accept string values
- All other fields are numeric and accept numbers

7.1.7 `getdevcap` — Get Device Capacity Info

Request:

JSON{ "cmd": "getdevcap", "password": "xxx" }

Response:

JSON{
  "ret": "getdevcap",
  "sn": "SN123456",
  "result": true,
  "usersize": 10000,
  "facesize": 10000,
  "avatarsize": 10000,
  "fpsize": 30000,
  "palmsize": 30000,
  "cardsize": 10000,
  "pwdsize": 10000,
  "logsize": 100000,
  "useduser": 150,
  "usedface": 148,
  "usedavatar": 100,
  "usedfp": 10,
  "usedpalm": 0,
  "usedcard": 50,
  "usedpwd": 20,
  "usedlog": 5000,
  "usednewlog": 100,
  "usedrtlog": 5
}

7.2 User Management

7.2.1 `getuserlist` — Get User List (Paginated)

Request:

JSON{
  "cmd": "getuserlist",
  "password": "xxx",
  "stn": 1
}

Response:

JSON{
  "ret": "getuserlist",
  "sn": "SN123456",
  "result": true,
  "count": 100,
  "to": 50,
  "record": [
    {
      "id": "1001",
      "name": "John Doe",
      "department": "Engineering",
      "shift": 0,
      "admin": 0,
      "fingerprint": 2,
      "palm": 0,
      "face": 1,
      "password": 0,
      "card": 12345678,
      "weekzone": 0,
      "group": 0,
      "access_times": 0,
      "verifymode": 0,
      "enable": 1,
      "birthday": "01-15",
      "starttime": "2024-01-01 00: 00",
      "endtime": "2025-12-31 23: 59",
      "photourl": "/photos/LF00001001.jpg"
    }
  ]
}

Returns up to 50 records per call. Call repeatedly with stn=0 until to >= count or to == 0.

7.2.2 `getuserids` — Get All User IDs

Request:

JSON{ "cmd": "getuserids", "password": "xxx" }

Response:

JSON{
  "ret": "getuserids",
  "sn": "SN123456",
  "result": true,
  "count": 3,
  "record": ["1001", "1002", "1003"]
}

7.2.3 `getunuserdid` — Get Next Available User ID

Request:

JSON{ "cmd": "getunuserdid", "password": "xxx" }

Response:

JSON{
  "ret": "getunuserdid",
  "sn": "SN123456",
  "result": true,
  "enrollid": "1004"
}

7.2.4 `checkuserid` — Check If User ID Exists

Request:

JSON{
  "cmd": "checkuserid",
  "password": "xxx",
  "enrollid": "1001"
}

Response:

JSON{
  "ret": "checkuserid",
  "sn": "SN123456",
  "result": true,
  "exists": true
}

7.2.5 `getuserinfo` — Get Single User Details

Request:

JSON{
  "cmd": "getuserinfo",
  "password": "xxx",
  "enrollid": "1001",
  "backupnum": 50
}

Response (with face photo, backupnum=50):

JSON{
  "ret": "getuserinfo",
  "sn": "SN123456",
  "result": true,
  "enrollid": "1001",
  "name": "John Doe",
  "department": "Engineering",
  "admin": 0,
  "pwd": 0,
  "card": 12345678,
  "fpflag": 3,
  "fpcnt": 2,
  "palmflag": 1,
  "palmcnt": 1,
  "faceflag": 1,
  "birthday": "01-15",
  "starttime": "2024-01-01 00: 00: 00",
  "endtime": "2025-12-31 23: 59: 59",
  "photourl": "/photos/LF00001001.jpg",
  "backupnum": 50,
  "record": "<Base64-encoded face photo>"
}

Response (user not found):

JSON{
  "ret": "getuserinfo",
  "sn": "SN123456",
  "result": false,
  "reason": 1,
  "msg": "can not find the user",
  "enrollid": "1001"
}

record format by backupnum:

An exported record can be pushed verbatim to another device with setuserinfo (using the same backupnum) to migrate biometric templates.

7.2.6 `setuserinfo` — Add or Update User Information

Request:

JSON{
  "cmd": "setuserinfo",
  "password": "xxx",
  "enrollid": "1001",
  "name": "John Doe",
  "admin": 0,
  "pwd": 123456,
  "card": 12345678,
  "department": "Engineering",
  "birthday": "01-15",
  "starttime": "2024-01-01 00: 00: 00",
  "endtime": "2025-12-31 23: 59: 59",
  "verifymode": 0,
  "shiftid": 1,
  "zoneid": 1,
  "groupid": 0,
  "access_times": 0,
  "enable": 1,
  "face": "<Base64-encoded face photo>"
}

How each biometric type is pushed:

⚠️ The fingerprint record is not Base64 — it is a "hex + zero run-length" text string. Only palm vein and face feature use Base64. The decoded length must match the table exactly, otherwise the device replies "xxx data error".

record encoding rules:

Recommended call order: create the user first with a setuserinfo call that carries no biometric data, then push each template by backupnum. Pushing backupnum=51 for a non-existent user fails with "face error".

Response (success):

JSON{
  "ret": "setuserinfo",
  "sn": "SN123456",
  "result": true,
  "enrollid": "1001",
  "backupnum": 50
}

Response (failure):

JSON{
  "ret": "setuserinfo",
  "sn": "SN123456",
  "result": false,
  "reason": 5,
  "msg": "no face",
  "enrollid": "1001"
}

Face enrollment failure reason codes:

Example 1 — push a face photo (face field, device extracts the feature on site):

JSON{
  "cmd": "setuserinfo",
  "password": "xxx",
  "enrollid": "1001",
  "name": "John Doe",
  "face": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL..."
}

JSON{
  "ret": "setuserinfo",
  "sn": "SN123456",
  "result": true,
  "enrollid": "1001"
}

Example 2 — push a fingerprint (slot 0, backupnum=0, record is the compressed hex string):

JSON{
  "cmd": "setuserinfo",
  "password": "xxx",
  "enrollid": "1001",
  "backupnum": 0,
  "record": "0a1f2b(807)"
}

The sample above is a complete, format-valid payload: 3 hex bytes followed by (807) (807 0x00 bytes), which decodes to exactly 810 bytes. Minimal testable payload: "record": "(810)", which decodes to 810 0x00 bytes and passes format validation. To push a real template, export the same encoding from an enrolled device with getuserinfo (backupnum=0) or bioread.

Example 3 — push a palm vein template (left hand, backupnum=40; right hand is 41):

JSON{
  "cmd": "setuserinfo",
  "password": "xxx",
  "enrollid": "1001",
  "backupnum": 40,
  "record": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA..."
}

record is standard Base64 and must decode to exactly 1548 bytes (the Base64 string is always 2064 characters). Minimal testable payload: Base64 of 1548 0x00 bytes (2064 A characters).

Example 4 — push a face feature with key points (backupnum=51, record is Base64):

JSON{
  "cmd": "setuserinfo",
  "password": "xxx",
  "enrollid": "1001",
  "backupnum": 51,
  "record": "CAYAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA..."
}

record is standard Base64 and must decode to exactly 1074 bytes. Minimal testable payload: 08 06 + 1072 0x00 bytes, i.e. a Base64 string starting with CAYA followed by 1428 A characters (1432 characters in total); on BOARD_CORE_810 use the 08 10 header instead (Base64 starts with CBAA). Export real features from an enrolled device with getuserinfo (backupnum=51) and feed them back to other devices unchanged.

Response (success):

JSON{
  "ret": "setuserinfo",
  "sn": "SN123456",
  "result": true,
  "enrollid": "1001",
  "backupnum": 51
}

The response echoes backupnum whenever it was present in the request.

Response (failures):

JSON{
  "ret": "setuserinfo",
  "sn": "SN123456",
  "result": false,
  "reason": 12,
  "msg": "finger already used,id=1002",
  "finger": 0,
  "enrollid": "1001",
  "backupnum": 0
}

JSON{
  "ret": "setuserinfo",
  "sn": "SN123456",
  "result": false,
  "reason": 1,
  "msg": "palm data error",
  "palm": 0,
  "enrollid": "1001",
  "backupnum": 40
}

The reason=12 duplicate checks (face / fingerprint / palm vein / card) are controlled by the device duplicate-check switch; when it is off, no check is made and the data overwrites the existing entry.

7.2.7 `deleteuser` — Delete User or Specific Biometric Data

Request:

JSON{
  "cmd": "deleteuser",
  "password": "xxx",
  "enrollid": "1001",
  "backupnum": 12
}

Response:

JSON{
  "ret": "deleteuser",
  "sn": "SN123456",
  "result": true,
  "backupnum": 12,
  "enrollid": "1001"
}

7.2.8 `deleteuserface` — Delete User Face

Request:

JSON{
  "cmd": "deleteuserface",
  "password": "xxx",
  "enrollid": "1001"
}

Response:

JSON{
  "ret": "deleteuserface",
  "sn": "SN123456",
  "result": true,
  "enrollid": "1001"
}

7.2.9 `deleteuserfp` — Delete All User Fingerprints

Request:

JSON{
  "cmd": "deleteuserfp",
  "password": "xxx",
  "enrollid": "1001"
}

Response:

JSON{
  "ret": "deleteuserfp",
  "sn": "SN123456",
  "result": true,
  "enrollid": "1001"
}

7.2.10 `deleteuserpalm` — Delete All User Palm Prints

Request:

JSON{
  "cmd": "deleteuserpalm",
  "password": "xxx",
  "enrollid": "1001"
}

Response:

JSON{
  "ret": "deleteuserpalm",
  "sn": "SN123456",
  "result": true,
  "enrollid": "1001"
}

7.2.11 `deleteusers` — Batch Delete Users

Request:

JSON{
  "cmd": "deleteusers",
  "password": "xxx",
  "list": ["1001", "1002", "1003"]
}

Response:

JSON{
  "ret": "deleteusers",
  "sn": "SN123456",
  "result": true
}

7.2.12 `cleanuser` — Delete All Users

Request:

JSON{ "cmd": "cleanuser", "password": "xxx" }

⚠️ DESTRUCTIVE: Removes all enrolled users from the device.

Response:

JSON{
  "ret": "cleanuser",
  "sn": "SN123456",
  "result": true
}

7.2.13 `enableuser` — Enable or Disable a User

Request:

JSON{
  "cmd": "enableuser",
  "password": "xxx",
  "enrollid": "1001",
  "enflag": 1
}

Response:

JSON{
  "ret": "enableuser",
  "sn": "SN123456",
  "result": true,
  "enrollid": "1001"
}

7.3 Biometric Enrollment (Device-Side)

7.3.1 `adduser` — Trigger On-Device Biometric Enrollment

Triggers the device's local screen to perform fingerprint/palm/face enrollment.

Request:

JSON{
  "cmd": "adduser",
  "password": "xxx",
  "enrollid": "1001",
  "name": "John Doe",
  "admin": 0,
  "backupnum": 50,
  "flag": 0
}

Response (success):

JSON{
  "ret": "adduser",
  "sn": "SN123456",
  "result": true,
  "backupnum": 50,
  "enrollid": "1001"
}

Response (cancel):

JSON{
  "ret": "adduser",
  "result": true,
  "cancel": true
}

Response (failure):

JSON{
  "ret": "adduser",
  "sn": "SN123456",
  "result": false,
  "reason": 3,
  "msg": "device busy",
  "backupnum": 50,
  "enrollid": "1001"
}

Failure reason codes:

7.3.2 `checkregstatus` — Query Enrollment Status

Request:

JSON{ "cmd": "checkregstatus", "password": "xxx" }

Response:

JSON{
  "ret": "checkregstatus",
  "sn": "SN123456",
  "result": true,
  "status": 1,
  "msg": "success",
  "image": "<Base64-encoded preview image>"
}

7.4 Log Management

7.4.1 `getlog` — Get Historical Logs (Paginated)

Request:

JSON{
  "cmd": "getlog",
  "password": "xxx",
  "index": 0,
  "enrollid": "1001",
  "from": "2024-06-01",
  "to": "2024-12-31"
}

Response (up to 50 records per page):

JSON{
  "ret": "getlog",
  "sn": "SN123456",
  "result": true,
  "count": 500,
  "from": 0,
  "to": 50,
  "record": [
    {
      "enrollid": "1001",
      "name": "John Doe",
      "time": "2024-06-01 09: 00: 00",
      "mode": 1,
      "inout": 1,
      "event": 0,
      "note": "remark",
      "photourl": "/logphotos/logimage123.jpg"
    }
  ]
}

Call repeatedly with incrementing index until to >= count.

7.4.2 `getrtlog` — Get Real-Time Logs (Consumed on Read)

Request:

JSON{ "cmd": "getrtlog", "password": "xxx", "index": 0 }

Response:

JSON{
  "ret": "getrtlog",
  "sn": "SN123456",
  "result": true,
  "count": 25,
  "from": 0,
  "to": 20,
  "record": [
    {
      "enrollid": "1001",
      "name": "John Doe",
      "time": "2024-06-01 09: 00: 00",
      "mode": 1,
      "inout": 1,
      "event": 0,
      "note": "remark"
    }
  ]
}

Real-time logs are removed from the queue once read. Up to 20 records per page. Call repeatedly with incrementing index until to >= count.

7.4.3 `setlogs` — Mark Logs as Synced

Request:

JSON{
  "cmd": "setlogs",
  "password": "xxx",
  "records": [
    { "id": "1001", "event": 0, "mode": 1, "time": "2024-06-01 09: 00: 00" }
  ]
}

Response:

JSON{
  "ret": "setlogs",
  "sn": "SN123456",
  "result": true
}

7.4.4 `cleanlog` — Clear All Logs

Request:

JSON{ "cmd": "cleanlog", "password": "xxx" }

⚠️ DESTRUCTIVE: Removes all historical attendance logs.

Response:

JSON{
  "ret": "cleanlog",
  "sn": "SN123456",
  "result": true
}

7.4.5 `cleanlogphoto` — Clear All Log Photos

Request:

JSON{ "cmd": "cleanlogphoto", "password": "xxx" }

Response:

JSON{
  "ret": "cleanlogphoto",
  "sn": "SN123456",
  "result": true
}

7.5 System Management

7.5.1 `gettime` — Get Device Time

Request:

JSON{ "cmd": "gettime", "password": "xxx" }

Response:

JSON{
  "ret": "gettime",
  "sn": "SN123456",
  "time": "2024-06-01 10: 00: 00"
}

7.5.2 `settime` — Set Device Time

Method 1 (string format):

JSON{
  "cmd": "settime",
  "password": "xxx",
  "cloudtime": "2024-06-01 10: 00: 00"
}

Method 2 (Unix timestamp in seconds):

JSON{
  "cmd": "settime",
  "password": "xxx",
  "nowtime": 1717200000
}

Response (success):

JSON{
  "ret": "settime",
  "sn": "SN123456",
  "result": true
}

Response (failure):

JSON{
  "ret": "settime",
  "sn": "SN123456",
  "result": false,
  "reason": 1
}

Validates year >= 2021, month 1-12, day, hour, minute, second ranges. Returns reason 1 on failure.

7.5.3 `reboot` — Reboot Device

Request:

JSON{ "cmd": "reboot", "password": "xxx" }

⚠️ No response — the device reboots immediately. The HTTP connection will be dropped.

7.5.4 `disabledevice` — Disable Device (Pause Recognition)

Request:

JSON{ "cmd": "disabledevice", "password": "xxx" }

Response:

JSON{
  "ret": "disabledevice",
  "sn": "SN123456",
  "result": true
}

The response is sent first, then the device disables face/fingerprint/palm/ID card recognition.

7.5.5 `enabledevice` — Enable Device (Resume Recognition)

Request:

JSON{ "cmd": "enabledevice", "password": "xxx" }

Response:

JSON{
  "ret": "enabledevice",
  "sn": "SN123456",
  "result": true
}

7.5.6 `initsys` — Full System Initialization (Clear All Data)

⚠️ DESTRUCTIVE: Clears all users, logs, and settings (language setting is preserved). Also removes bell schedules, post data, attendance settings, and lock data. Backs up WiFi configuration.

Request:

JSON{ "cmd": "initsys", "password": "xxx" }

Response:

JSON{
  "ret": "initsys",
  "sn": "SN123456",
  "result": true
}

7.5.7 `initmenu` — Reset Menu Settings (Preserve User Data)

Request:

JSON{ "cmd": "initmenu", "password": "xxx" }

Response:

JSON{
  "ret": "initmenu",
  "sn": "SN123456",
  "result": true
}

Same as initsys but does NOT clear user database or log database.

7.5.8 `cleandatebase` — Clear Log Database

Request:

JSON{ "cmd": "cleandatebase", "password": "xxx" }

⚠️ DESTRUCTIVE: Clears entire database and sets a reboot flag. Device will reboot after this operation.

Response:

JSON{
  "ret": "cleandatebase",
  "sn": "SN123456",
  "result": true
}

7.5.9 `cleanadmin` — Remove All Administrator Privileges

Request:

JSON{ "cmd": "cleanadmin", "password": "xxx" }

Response:

JSON{
  "ret": "cleanadmin",
  "sn": "SN123456",
  "result": true
}

7.5.10 `cleaninactiveuser` — Remove Users Without Biometric Data

Request:

JSON{ "cmd": "cleaninactiveuser", "password": "xxx" }

Response:

JSON{
  "ret": "cleaninactiveuser",
  "sn": "SN123456",
  "result": true
}

7.5.11 `setscreensaver` — Set Screensaver Parameters

Request:

JSON{
  "cmd": "setscreensaver",
  "password": "xxx",
  "filename": "logo.jpg",
  "photo": "<Base64-encoded image>",
  "duration": 60,
  "remove": false,
  "removeall": false
}

Response:

JSON{
  "ret": "setscreensaver",
  "sn": "SN123456",
  "result": true
}

7.5.12 `upgrade` — Trigger OTA Firmware Upgrade via JSON API

Request:

JSON{
  "cmd": "upgrade",
  "password": "xxx",
  "filename": "ai230_product.zip",
  "md5": "d41d8cd98f00b204e9800998ecf8427e",
  "allcount": 100,
  "index": 0,
  "count": 50,
  "record": "<Base64-encoded firmware chunk>"
}

Response (success):

JSON{
  "ret": "upgrade",
  "sn": "SN123456",
  "result": true
}

Response (failure):

JSON{
  "ret": "upgrade",
  "sn": "SN123456",
  "result": false,
  "reason": 1,
  "msg": "file mismatch or insufficient space"
}

Failure reason codes:

7.5.13 `setvoice` — Configure Voice Prompts

Request:

JSON{
  "cmd": "setvoice",
  "password": "xxx",
  "index": 0,
  "voice": "<Base64-encoded WAV audio>",
  "play": true
}

Response:

JSON{
  "ret": "setvoice",
  "sn": "SN123456",
  "result": true
}

7.5.14 `keypad` — Activate/Deactivate Keypad Mode

Request:

JSON{
  "cmd": "keypad",
  "password": "xxx",
  "password": true,
  "keep": false,
  "timeout": 30,
  "on": true
}

Response:

JSON{
  "ret": "keypad",
  "sn": "SN123456",
  "result": true
}

7.6 Door Access Control

7.6.1 `opendoor` — Remote Door Open

Request:

JSON{
  "cmd": "opendoor",
  "password": "xxx",
  "enrollid": "1001",
  "floor": 3,
  "msg": "Welcome"
}

Response:

JSON{
  "ret": "opendoor",
  "sn": "SN123456",
  "result": true
}

7.6.2 `lockctrl` — Door Lock State Control

Request:

JSON{
  "cmd": "lockctrl",
  "password": "xxx",
  "fuc": 1
}

Response:

JSON{
  "ret": "lockctrl",
  "sn": "SN123456",
  "result": true
}

7.6.3 `getdoorstatus` — Get Door Status

Request:

JSON{ "cmd": "getdoorstatus", "password": "xxx" }

Response:

JSON{
  "ret": "getdoorstatus",
  "sn": "SN123456",
  "result": true,
  "doorstatus": 1
}

7.6.4 `setdevlock` — Configure Door Access Parameters

Request (all fields optional):

JSON{
  "cmd": "setdevlock",
  "password": "xxx",
  "opendelay": 5,
  "doorsensor": 1,
  "alarmdelay": 30,
  "InputAlarm": 0,
  "antpass": 0,
  "interlock": 0,
  "mutiopen": 0,
  "tryalarm": 5,
  "access_times": 0,
  "punchtimes": 0,
  "tamper": 0,
  "wgformat": 26,
  "wgoutput": 0,
  "cardformat": 0,
  "dayzone": [],
  "weekzone": [],
  "lockgroup": [],
  "nopentime": [],
  "visitortime": []
}

Response:

JSON{
  "ret": "setdevlock",
  "sn": "SN123456",
  "result": true
}

7.6.5 `getdevlock` — Get Door Access Parameters

Request:

JSON{ "cmd": "getdevlock", "password": "xxx" }

Response:

JSON{
  "ret": "getdevlock",
  "sn": "SN123456",
  "result": true,
  "opendelay": 5,
  "doorsensor": 1,
  "alarmdelay": 30,
  "InputAlarm": 0,
  "antpass": 0,
  "interlock": 0,
  "mutiopen": 0,
  "tryalarm": 5,
  "access_times": 0,
  "tamper": 0,
  "wgformat": 26,
  "wgoutput": 0,
  "cardformat": 0,
  "dayzone": [],
  "weekzone": [],
  "lockgroup": [],
  "nopentime": [],
  "visitortime": []
}

7.6.6 `getuserlock` — Get User-Level Access Settings

Request:

JSON{
  "cmd": "getuserlock",
  "password": "xxx",
  "enrollid": "1001"
}

Response (found):

JSON{
  "ret": "getuserlock",
  "sn": "SN123456",
  "result": true,
  "enrollid": "1001",
  "birthday": "01-15",
  "verifymode": 0,
  "enable": 1,
  "weekzone": 0,
  "group": 0,
  "access_times": 0,
  "starttime": "2024-01-01 00: 00: 00",
  "endtime": "2025-12-31 23: 59: 59"
}

Response (not found):

JSON{
  "ret": "getuserlock",
  "sn": "SN123456",
  "result": false,
  "reason": 1,
  "msg": "can not find the user",
  "enrollid": "1001"
}

7.6.7 `setuserlock` — Set User-Level Access Parameters (Batch)

Request:

JSON{
  "cmd": "setuserlock",
  "password": "xxx",
  "count": 2,
  "record": [
    {
      "enrollid": "1001",
      "birthday": "01-15",
      "verifymode": 0,
      "weekzone": 0,
      "group": 0,
      "access_times": 0,
      "starttime": "2024-01-01 00: 00: 00",
      "endtime": "2025-12-31 23: 59: 59"
    },
    {
      "enrollid": "1002",
      "birthday": "06-20",
      "verifymode": 1,
      "weekzone": 1,
      "group": 0,
      "access_times": 5,
      "starttime": "2024-01-01 00: 00: 00",
      "endtime": "2025-12-31 23: 59: 59"
    }
  ]
}

Response (success):

JSON{
  "ret": "setuserlock",
  "sn": "SN123456",
  "result": true
}

Response (failure):

JSON{
  "ret": "setuserlock",
  "sn": "SN123456",
  "result": false,
  "reason": 1,
  "msg": "setuserlock fail"
}

7.6.8 `deleteuserlock` — Delete User Access Settings

Request:

JSON{
  "cmd": "deleteuserlock",
  "password": "xxx",
  "enrollid": "1001"
}

Response:

JSON{
  "ret": "deleteuserlock",
  "sn": "SN123456",
  "result": true,
  "enrollid": "1001"
}

7.6.9 `cleanuserlock` — Clear All User Access Settings

Request:

JSON{ "cmd": "cleanuserlock", "password": "xxx" }

Response:

JSON{
  "ret": "cleanuserlock",
  "sn": "SN123456",
  "result": true
}

7.6.10 `openallfloors` — Open All Floors

Request:

JSON{ "cmd": "openallfloors", "password": "xxx" }

Response:

JSON{
  "ret": "openallfloors",
  "sn": "SN123456",
  "result": true
}

7.6.11 `closeallfloors` — Close All Floors

Request:

JSON{ "cmd": "closeallfloors", "password": "xxx" }

Response:

JSON{
  "ret": "closeallfloors",
  "sn": "SN123456",
  "result": true
}

7.6.12 `openselectfloors` — Open Selected Floors

Request:

JSON{
  "cmd": "openselectfloors",
  "password": "xxx",
  "profile": "1,2,5"
}

Response:

JSON{
  "ret": "openselectfloors",
  "sn": "SN123456",
  "result": true
}

7.6.13 `closeselectfloors` — Close Selected Floors

Request:

JSON{
  "cmd": "closeselectfloors",
  "password": "xxx",
  "profile": "3,4"
}

Response:

JSON{
  "ret": "closeselectfloors",
  "sn": "SN123456",
  "result": true
}

7.7 Shifts & Attendance

7.7.1 `getshift` — Get Shift Configuration

Request:

JSON{ "cmd": "getshift", "password": "xxx" }

Response:

JSON{
  "ret": "getshift",
  "sn": "SN123456",
  "result": true,
  "shifts": [
    {
      "name": "Shift 1",
      "cutoftime": 10,
      "sections": [
        { "start": "09: 00", "end": "12: 00", "type": 0 },
        { "start": "13: 00", "end": "18: 00", "type": 0 },
        { "start": "", "end": "", "type": 0 }
      ]
    }
  ]
}

7.7.2 `setshift` — Set Shift Configuration

Request:

JSON{
  "cmd": "setshift",
  "password": "xxx",
  "shifts": [
    {
      "name": "Shift 1",
      "cutoftime": 10,
      "sections": [
        { "start": "09: 00", "end": "12: 00", "type": 0 },
        { "start": "13: 00", "end": "18: 00", "type": 0 },
        { "start": "", "end": "", "type": 0 }
      ]
    }
  ]
}

Response:

JSON{
  "ret": "setshift",
  "sn": "SN123456",
  "result": true
}

7.7.3 `getbelltime` — Get Bell Schedule

Request:

JSON{ "cmd": "getbelltime", "password": "xxx" }

Response:

JSON{
  "ret": "getbelltime",
  "sn": "SN123456",
  "result": true,
  "belltimes": [
    { "time": "09: 00", "flag": 1 },
    { "time": "12: 00", "flag": 0 },
    { "time": "13: 00", "flag": 1 },
    { "time": "18: 00", "flag": 0 }
  ]
}

7.7.4 `setbelltime` — Set Bell Schedule

Request:

JSON{
  "cmd": "setbelltime",
  "password": "xxx",
  "belltimes": [
    { "time": "09: 00", "flag": 1 },
    { "time": "12: 00", "flag": 0 },
    { "time": "13: 00", "flag": 1 },
    { "time": "18: 00", "flag": 0 }
  ]
}

Response:

JSON{
  "ret": "setbelltime",
  "sn": "SN123456",
  "result": true
}

7.7.5 `getholiday` — Get Holiday Settings

Request:

JSON{ "cmd": "getholiday", "password": "xxx" }

Response:

JSON{
  "ret": "getholiday",
  "sn": "SN123456",
  "result": true,
  "holidays": [
    {
      "name": "New Year",
      "startday": "01-01",
      "endday": "01-03",
      "shift": 0,
      "dayzone": 0
    }
  ]
}

7.7.6 `setholiday` — Set Holiday Settings

Request:

JSON{
  "cmd": "setholiday",
  "password": "xxx",
  "holidays": [
    {
      "name": "New Year",
      "startday": "01-01",
      "endday": "01-03",
      "shift": 0,
      "dayzone": 0
    }
  ]
}

Response:

JSON{
  "ret": "setholiday",
  "sn": "SN123456",
  "result": true
}

7.8 Reports

7.8.1 `getreport` — Get Attendance Report Data

Request:

JSON{
  "cmd": "getreport",
  "password": "xxx",
  "enrollid": "1001",
  "from": "2024-01-01",
  "to": "2024-12-31"
}

Response (success):

JSON{
  "ret": "getreport",
  "sn": "SN123456",
  "result": true
}

Response (no logs found):

JSON{
  "ret": "getreport",
  "sn": "SN123456",
  "result": false,
  "reason": 1,
  "msg": "can not find logs"
}

Response contains dynamic report data fields depending on the report type and date range.

7.8.2 `generatereport` — Generate Report Files

Request:

JSON{
  "cmd": "generatereport",
  "password": "xxx",
  "enrollid": "1001",
  "from": "2024-01-01",
  "to": "2024-12-31"
}

Response (success):

JSON{
  "ret": "generatereport",
  "sn": "SN123456",
  "result": true,
  "msg": "Report generation started."
}

Response (busy):

JSON{
  "ret": "generatereport",
  "sn": "SN123456",
  "result": false,
  "reason": 3,
  "msg": "A report is already being generated. Please wait."
}

After generation completes, files can be downloaded via /download/report and /download/rawrecord.

7.8.3 `checkreportprogress` — Check Report Generation Progress

Request:

JSON{ "cmd": "checkreportprogress", "password": "xxx" }

Response (in progress):

JSON{
  "ret": "checkreportprogress",
  "sn": "SN123456",
  "result": true,
  "progress": 75,
  "status": "generating",
  "finished": false
}

Response (completed):

JSON{
  "ret": "checkreportprogress",
  "sn": "SN123456",
  "result": true,
  "progress": 100,
  "status": "completed",
  "finished": true,
  "file_exists": true
}

7.9 Questionnaire & Notices

7.9.1 `setquestionnaire` — Configure Questionnaire

Request:

JSON{
  "cmd": "setquestionnaire",
  "password": "xxx",
  "title": "Health Declaration",
  "voice": "Please complete health declaration",
  "errmsg": "Declaration failed",
  "radio": true,
  "optionflag": 3,
  "items": ["Question 1", "Question 2"],
  "schedules": ["08: 00-09: 00", "12: 00-13: 00"],
  "usequestion": true,
  "useschedule": false,
  "card": 0,
  "switch_card": 0,
  "enrollid": "1001",
  "open": true
}

Response:

JSON{
  "ret": "setquestionnaire",
  "sn": "SN123456",
  "result": true
}

7.9.2 `getquestionnaire` — Get Questionnaire Configuration

Request:

JSON{ "cmd": "getquestionnaire", "password": "xxx" }

Response (configured):

JSON{
  "ret": "getquestionnaire",
  "sn": "SN123456",
  "result": true,
  "title": "Health Declaration",
  "voice": "Please complete health declaration",
  "errmsg": "Declaration failed",
  "radio": true,
  "optionflag": 3,
  "usequestion": true,
  "useschedule": false,
  "card": 0,
  "switch_card": 0,
  "items": ["Question 1", "Question 2"],
  "schedules": ["08: 00-09: 00", "12: 00-13: 00"]
}

Response (not configured):

JSON{
  "ret": "getquestionnaire",
  "sn": "SN123456",
  "result": false
}

7.9.3 `cleanquestionnaire` — Clear Questionnaire Settings

Request:

JSON{ "cmd": "cleanquestionnaire", "password": "xxx" }

Response:

JSON{
  "ret": "cleanquestionnaire",
  "sn": "SN123456",
  "result": true
}

7.9.4 `setcompanyname` — Set Company Name

Request:

JSON{
  "cmd": "setcompanyname",
  "password": "xxx",
  "name": "ACME Corporation"
}

Response:

JSON{
  "ret": "setcompanyname",
  "sn": "SN123456",
  "result": true
}

7.9.5 `getcompanyname` — Get Company Name

Request:

JSON{ "cmd": "getcompanyname", "password": "xxx" }

Response:

JSON{
  "ret": "getcompanyname",
  "sn": "SN123456",
  "result": true,
  "name": "ACME Corporation"
}

7.10 Video Intercom (WebRTC)

7.10.1 `enablewebrtc` — Initiate Video Call

Request:

JSON{
  "cmd": "enablewebrtc",
  "password": "xxx",
  "intercom": true,
  "monitor": true,
  "inputmode": 0,
  "waitseconds": 30,
  "stunserver": "stun:stun.l.google.com: 19302",
  "turnserver": "",
  "turnusername": "",
  "turnpassword": ""
}

Response (success):

JSON{
  "ret": "enablewebrtc",
  "sn": "SN123456",
  "result": true,
  "lanscape": 0
}

Response (hardware not supported):

JSON{
  "ret": "enablewebrtc",
  "sn": "SN123456",
  "result": false,
  "reason": 1,
  "msg": "this device have not this function"
}

7.10.2 `getwebrtc` — Get WebRTC Signaling Status

Request:

JSON{ "cmd": "getwebrtc", "password": "xxx" }

Response (success):

JSON{
  "ret": "getwebrtc",
  "sn": "SN123456",
  "result": true,
  "intercom": true,
  "monitor": false,
  "inputmode": 0,
  "waitseconds": 30,
  "stunserver": "stun:stun.l.google.com: 19302",
  "turnserver": "",
  "turnusername": "",
  "turnpassword": ""
}

Response (hardware not supported):

JSON{
  "ret": "getwebrtc",
  "sn": "SN123456",
  "result": false,
  "reason": 1,
  "msg": "this device have not this function"
}

7.10.3 `checklive` — Check Live Stream Status

Request:

JSON{ "cmd": "checklive", "password": "xxx" }

Response (ICE candidate available):

JSON{
  "sn": "SN123456",
  "cmd": "icecandidate",
  "candidate": "<ICE candidate string>"
}

Response (call cancelled on device):

JSON{
  "sn": "SN123456",
  "cmd": "talkcancel"
}

Response (no activity):

(null — no response)

This command has non-standard response format. Returns ICE candidate data when available, cancellation notice if call was ended on the device side, or no response at all when idle.

7.10.4 `answer` — SDP Answer

Request:

JSON{
  "cmd": "answer",
  "password": "xxx",
  "sdp": "<SDP string>"
}

Response (success):

JSON{
  "ret": "answer",
  "sn": "SN123456",
  "result": true
}

Response (failure):

JSON{
  "ret": "answer",
  "sn": "SN123456",
  "result": false,
  "reason": 1,
  "msg": "device error"
}

Failure reason codes:

7.10.5 `icecandidate` — ICE Candidate Exchange

Request:

JSON{
  "cmd": "icecandidate",
  "password": "xxx",
  "candidate": "<ICE candidate string>"
}

Response:

JSON{
  "ret": "icecandidate",
  "sn": "SN123456",
  "result": true
}

7.10.6 `callcancel` — Cancel Call

Request:

JSON{ "cmd": "callcancel", "password": "xxx" }

Response:

JSON{
  "ret": "callcancel",
  "sn": "SN123456",
  "result": true
}

7.10.7 `monitorcall` — Monitor Mode Call

Request:

JSON{ "cmd": "monitorcall", "password": "xxx" }

Response (offer SDP):

JSON{
  "cmd": "offer",
  "sn": "SN123456",
  "type": "offer",
  "sdp": "<SDP offer string>"
}

Response (failure):

JSON{
  "ret": "monitorcall",
  "sn": "SN123456",
  "result": false,
  "reason": 1,
  "msg": "device busy"
}

Failure reason codes:

7.11 Biometric Verification

7.11.1 `verify` — Remote Biometric Verification

Performs remote biometric verification on the device using provided biometric data.

Request:

JSON{
  "cmd": "verify",
  "password": "xxx",
  "enrollid": "1001",
  "card": "12345678",
  "pwd": 123456,
  "name": "John Doe",
  "face": "<Base64-encoded face JPEG>",
  "finger": "<Hex fingerprint template>",
  "finger2": "<Hex second fingerprint template>",
  "profile": "default"
}

Response (success):

JSON{
  "ret": "verify",
  "sn": "SN123456",
  "result": true,
  "enrollid": "1001"
}

Response (failure):

JSON{
  "ret": "verify",
  "sn": "SN123456",
  "result": false,
  "reason": 1,
  "msg": "verification failed",
  "enrollid": "1001"
}

Failure reason codes:

7.11.2 `biomatch` — Biometric Matching (OSDP Test)

Request:

JSON{ "cmd": "biomatch", "password": "xxx" }

Requires config_OSDP_TEST configuration.

Response:

JSON{
  "ret": "biomatch",
  "sn": "SN123456",
  "result": true
}

7.11.3 `bioread` — Read Raw Biometric Data (OSDP Test)

Request:

JSON{ "cmd": "bioread", "password": "xxx" }

Requires config_OSDP_TEST configuration.

Response:

JSON{
  "ret": "bioread",
  "sn": "SN123456",
  "result": true
}

7.12 File Operations

7.12.1 `getdir` — List Directory Contents

Request:

JSON{
  "cmd": "getdir",
  "password": "xxx",
  "path": "/data"
}

Response (success):

JSON{
  "ret": "getdir",
  "sn": "SN123456",
  "result": true,
  "files": ["config.txt", "photo.jpg", "logs/"]
}

Response (failure):

JSON{
  "ret": "getdir",
  "sn": "SN123456",
  "result": false
}

7.12.2 `getfile` — Get File Content (Base64 encoded)

Request:

JSON{
  "cmd": "getfile",
  "password": "xxx",
  "path": "/data/config.txt"
}

Response (success):

JSON{
  "ret": "getfile",
  "sn": "SN123456",
  "result": true,
  "base64": "<Base64-encoded file content>"
}

Response (failure):

JSON{
  "ret": "getfile",
  "sn": "SN123456",
  "result": false
}

7.12.3 `writefile` — Write File

Request:

JSON{
  "cmd": "writefile",
  "password": "xxx",
  "path": "/data/notice.txt",
  "base64": "<Base64-encoded content>"
}

Response (success):

JSON{
  "ret": "writefile",
  "sn": "SN123456",
  "result": true
}

Response (failure):

JSON{
  "ret": "writefile",
  "sn": "SN123456",
  "result": false
}

7.13 Firmware Upgrade

Firmware upgrades use a dedicated HTTP endpoint (not JSON API).

Endpoint: POST /api/firmware/upload

Query Parameters:

Chunked Transfer Logic:

1. Each POST carries a file chunk as the request body
2. offset=0 marks the first chunk — device clears /data/ota directory
3. When data.len == 0 and offset >= total, MD5 is verified and processing completes
4. Supported formats: .zip (system update) and .pkg (firmware package)

Success Response: "true" (text/plain)

Error Response (HTTP 500):

8. Static Resources & File Downloads

Static files are served from /data/res/webserver first; if not found, fallback to /usr/webserver.

9. Appendix: backupnum Reference

The backupnum field is used in getuserinfo, setuserinfo, deleteuser, adduser, deleteuserfp, deleteuserpalm and related commands to identify which biometric slot to operate on. Push commands (setuserinfo) additionally carry the template payload in record.

record quick reference:

• Fingerprint (0-9): each byte as 2 lowercase hex digits, with runs of N 0x00 bytes compressed to (N); e.g. 0a1f(2)2b decodes to 0a 1f 00 00 2b. The decoded result must be exactly 810 bytes. Minimal testable payload: (810).
• Palm vein (40/41): standard Base64 that must decode to exactly 1548 bytes (2064 Base64 characters); minimal testable payload is the Base64 of 1548 0x00 bytes (2064 A characters).
• Face feature (51): standard Base64 that must decode to exactly 1074 bytes; the first 2 bytes are the template header (08 06 on regular platforms, 08 10 on BOARD_CORE_810). Minimal testable payload is 08 06 + 1072 0x00 bytes (Base64 starting with CAYA, 1432 characters).
• Face photo (50): export/read only; push photos with the face field of setuserinfo (Base64 JPEG).

Generating minimal testable payloads:

BASH# Fingerprint (810 zero bytes) -> use the literal string (810)
# Palm vein (1548 zero bytes) -> Base64 string of 2064 characters
python3 -c "import base64;print(base64.b64encode(bytes(1548)).decode())"
# Face feature (08 06 + 1072 zero bytes) -> Base64 starting with CAYA
python3 -c "import base64;print(base64.b64encode(b'\x08\x06'+bytes(1072)).decode())"

Fingerprint and palm vein templates are only available on models with the matching hardware (fingerprint module, or palm vein module); on unsupported models the corresponding backupnum is ignored.

10. Appendix: verifymode Reference

verifymode selects the verification method(s) a user may use (the device default uses the same values). Every method — including combinations such as "face + card" — has a fixed value; use one of the values below.

Notes:

• A value of 0 means no restriction and is the factory default; a user without its own setting follows the device default.
• Only use methods the device supports. A method the device does not support has no effect: the user keeps the previous setting and no error is returned.
• Use one of the values listed above (values are independent and cannot be added together); do not use values that are not listed.
• The mode field of log and attendance records uses the same values.