Skip to main content
POST
/
devices
Create Device
curl --request POST \
  --url https://api.example.com/devices \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "<string>",
  "name": "<string>",
  "ip": "<string>",
  "port": 123,
  "password": 123,
  "timeout": 123
}
'
{
  "success": true,
  "message": "<string>",
  "data": {
    "ip": "<string>",
    "port": 123,
    "password": 123,
    "timeout": 123,
    "name": "<string>",
    "created_at": "<string>"
  }
}
Registers a new biometric device by providing its connection details. The device ID must be unique and will be normalized to lowercase with underscores replacing spaces.

​
Request Body

​
id
string
required
Unique identifier for the device. Will be converted to lowercase with spaces replaced by underscores.Example: "bodega" or "entrance_main"
​
name
string
required
Human-readable name for the deviceExample: "Bodega Principal" or "Main Entrance"
​
ip
string
required
IP address of the ZKTeco device on your networkExample: "192.168.1.207"
​
port
integer
default:"4370"
TCP port number for the device connection. Most ZKTeco devices use port 4370.
​
password
integer
default:"0"
Device communication password (usually 0 for default configuration)
​
timeout
integer
default:"5"
Connection timeout in seconds

​
Response

​
success
boolean
required
Indicates whether the device was successfully registered
​
message
string
required
Confirmation message
​
data
object
required
The complete device configuration that was saved

​
Example Request

curl -X POST https://your-server.com/devices \
  -H "Content-Type: application/json" \
  -d '{
    "id": "bodega",
    "name": "Bodega Principal",
    "ip": "192.168.1.207",
    "port": 4370,
    "password": 0,
    "timeout": 5
  }'

​
Example Response

​
Success (200)

{
  "success": true,
  "message": "Dispositivo 'bodega' registrado.",
  "data": {
    "ip": "192.168.1.207",
    "port": 4370,
    "password": 0,
    "timeout": 5,
    "name": "Bodega Principal",
    "created_at": "2026-03-06 14:20:00"
  }
}

​
Error: Missing Required Fields (400)

{
  "success": false,
  "error": "id, name e ip son requeridos."
}

​
Error: Device ID Already Exists (409)

{
  "success": false,
  "error": "El id 'bodega' ya existe."
}

​
Error: Invalid JSON Body (400)

{
  "success": false,
  "error": "Body JSON requerido."
}

​
Error Codes

Status CodeDescription
200Device successfully registered
400Missing required fields or invalid JSON
409Device ID already exists

​
Notes

  • The device ID is automatically normalized: converted to lowercase and spaces are replaced with underscores
  • The device configuration is persisted to devices.json on disk
  • A thread lock is created for the device to handle concurrent operations safely
  • Registration does not test the connection; use the /devices/{device_id}/ping endpoint to verify connectivity

Build docs developers (and LLMs) love

Get started for freeTalk to us