CS4 ADM integration API
Manage ESSL / ZKTeco biometric devices from your own application: register devices, manage employees, push them to devices, start fingerprint / face enrollment, send device commands, read attendance and access events, run reports and receive webhooks. There is no customer console — this API is the interface.
https://apiservice.adm.robeeta.com/api/v1Getting started
- CS4 ADM support creates your application and issues its API key(s). Each key has a connection:
adm(devices push to the CS4 ADM device server) oressl(devices stay on a given eSSL eTimeTrackLite server). - Call
GET /me: it shows your application, the key anddeviceServer— the address to configure on devices added with this key. - Register each device with
POST /devices(serial number, name, optionalgroup). It reports where the key's connection points; unknown serial numbers are always refused. - For
admdevices set the device's cloud server (ADMS) todeviceServer.hostand one ofdeviceServer.ports; the device becomesonlineon its first request.essldevices are read from the eSSL server every minute. - Create employees, push them to devices, enroll fingerprints / faces, and read punches with the cursor feed
GET /attendance/sinceor theattendance.punchwebhook.
One application, one data set: every key of the application sees all its devices, employees, punches, commands and webhooks —
devices on the CS4 ADM server and on eSSL servers alike, in the same JSON shape (source tells them apart).
Groups: if your application serves several customers, put your customer / company id in the optional group of devices
and employees and filter with ?group= (devices, employees, attendance, attendance/since).
Authentication
API keys are issued by CS4 ADM support for your application. The key is shown once; only its SHA-256 hash is stored.
Keys look like adm_k3y9pr3f_… — the 8 characters after adm_ are the key prefix shown in lists and audit logs.
Send the key with every request in the X-Api-Key header (or Authorization: ApiKey <key>):
curl https://apiservice.adm.robeeta.com/api/v1/me \
-H "X-Api-Key: adm_k3y9pr3f_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
# equivalent
curl https://apiservice.adm.robeeta.com/api/v1/me -H "Authorization: ApiKey adm_k3y9pr3f_XXXX..."
Your application is determined by the key — there is no application id in URLs or bodies. Requests with an unknown, revoked or expired key,
or whose application is suspended / has API access disabled, get 401 with the reason in detail.
Repeated requests with invalid keys block the caller's IP address for a while (403).
The API sets no cookies and needs no session; keep keys on your server (never in a browser or mobile app).
Call GET /api/v1/me to check a key: it returns the application, key name, scopes, rate limit, IP allowlist, connection and device server.
Scopes
Each key has a set of scopes. A request outside the key's scopes gets 403 with missingScopes listed.
| Scope | Grants |
|---|---|
devices:read | Read devices and command status |
devices:write | Add/remove devices, send commands |
devices:admin | Dangerous commands (clear data, custom) |
users:read | Read employees and departments |
users:write | Manage employees, push to devices, enroll |
attendance:read | Read attendance / access logs |
reports:read | Run reports |
webhooks:manage | Manage webhooks |
devices:admin is needed in addition to devices:write for the destructive command types
clearattlog, cleardata and custom.
Rate limits & IP allowlist
- Each key has its own limit in requests per minute (set by CS4 ADM support, shown by
/me), enforced as a sliding one-minute window. Every authenticated response carriesX-RateLimit-Limit. - Over the limit you get
429 Too Many Requestswith aRetry-Afterheader (seconds). Back off and retry after that time. - If the key has an IP allowlist (exact IPv4 addresses or CIDR ranges such as
203.0.113.0/24), requests from other addresses get403. - Request bodies are limited to 5 MB. Lists are paged (see below) — do not try to download everything in one call.
Requests & JSON
- Send
Content-Type: application/jsonon POST / PUT. Property names are camelCase (serialNumber,pageSize); matching is case-insensitive on input. - PUT updates are partial: an omitted or
nullproperty keeps its current value; an empty string""clears an optional text field;0clears an optional reference (departmentId,parentId). - Creating returns
201 Createdwith aLocationheader and the created object; deleting returns200with{"deleted": true}. - Actions that send something to devices return
202 Acceptedwith the queued commands (see command lifecycle). - Every change is written to the application's audit log as actor
api:<key prefix>; every request is logged per key.
Errors
Errors are RFC 9457 / 7807 problem details (application/problem+json). Show or log detail — it is written for humans.
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.4",
"title": "Forbidden",
"status": 403,
"detail": "This API key lacks the required scope: devices:write. Ask CS4 ADM support to grant it.",
"missingScopes": [ "devices:write" ],
"traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}
| Status | Meaning |
|---|---|
400 | Invalid input (validation message in detail; model errors also in errors). |
401 | Missing, unknown, revoked or expired key; application suspended or API access disabled. |
403 | Missing scope (missingScopes), caller IP not in the key's allowlist, or IP blocked after repeated invalid keys. |
404 | The object does not exist in your application. |
409 | Conflict: duplicate serial / PIN / external reference, device limit reached, device blocked, command no longer pending … |
422 | The command type is not available for a device on an eSSL server (see Devices on eSSL servers). |
429 | Rate limit exceeded — wait Retry-After seconds. |
5xx | Server problem — retry with backoff; include traceId when contacting support. |
Pagination
List endpoints return { items, total, page, pageSize }. Use ?page= (1-based) and ?pageSize=
(maximum 1000 for employees / attendance / access events, 500 for commands, 200 for webhook deliveries). Short lists such as
devices, departments and webhooks are returned completely in one page.
{
"items": [ { "id": 1201, "pin": "1001", "name": "Asha Raman", ... } ],
"total": 245,
"page": 1,
"pageSize": 100
}
To import punches continuously, use the cursor feed GET /attendance/since?id=<lastId>&limit=1000:
it returns punches in arrival order with nextId and hasMore. It never skips or repeats rows, even when devices upload old punches late.
Date & time formats
| Kind | Format | Fields |
|---|---|---|
| Device wall-clock | 2026-11-15T09:02:41 — no offset |
punchTime, eventTime, attendance filters from/to, fetch-attendance range |
| Instant (UTC) | 2026-11-15T03:32:44Z |
createdAt, receivedAt, lastSeenAt, sentAt, executedAt, expiresAt … |
| Calendar date | 2026-11-15 |
report from/to, report rows |
Punch times are exactly what the device clock showed — the device's local time, without a zone. Do not convert them;
each device's zone is its effectiveTimeZone. On input, wall-clock values may be yyyy-MM-dd or
yyyy-MM-ddTHH:mm:ss; an offset or Z, if sent, is ignored. Range filters include from and exclude to.
Command lifecycle
Devices are never contacted directly: the API only queues commands. Each device polls the server every few seconds while
online and takes its pending commands; the result arrives with its next request. Pushing an employee, enrolling, syncing,
rebooting etc. therefore return 202 Accepted with the queued commands and a batchId.
pending | Queued; the device has not polled yet (an offline device keeps its commands until it reconnects). Can be cancelled. |
sent | Handed to the device; waiting for its reply. |
success | The device executed it (returnCode ≥ 0). |
failed | The device returned an error (returnCode < 0, explained in error). |
fw_success | The device reported failure for an enrollment, but a punch of that employee arrived afterwards — the enrollment worked (known firmware quirk). Treat as success. |
timeout | Sent but no reply within the timeout. Retry with POST /commands/{id}/retry. |
cancelled | Cancelled while pending (POST /commands/{id}/cancel). |
Read the outcome with GET /commands/{id} (or GET /commands?batchId=…), or subscribe to the command.completed webhook instead of polling.
HTTP/1.1 202 Accepted
{
"batchId": "b_5f1c2a9e0d4b",
"count": 2,
"commands": [
{ "id": 88123, "type": "user.add", "status": "pending", "deviceId": 12, ... },
{ "id": 88124, "type": "enroll.fp", "status": "pending", "deviceId": 12, ... }
],
"message": "2 command(s) queued (pending). Devices fetch them on their next poll; ..."
}
Devices on eSSL servers
A device either pushes to CS4 ADM ("source": "adm") or stays connected to an eSSL eTimeTrackLite server
("source": "essl") — decided by the connection of the key that registers it (or by CS4 ADM support).
Both kinds are in one combined list: GET /devices returns every device with
source, esslServer (server name, null for ADM devices), esslLinked
(the serial was found on that eSSL server) and esslLastPing (the eSSL server's wall clock).
- CS4 ADM reads the status and punches of eSSL devices every minute. Their punches arrive within about a minute through the
same cursor feed
GET /attendance/since?id=<lastId>as all other punches ("source": "essl"on each punch). Adding an eSSL device imports its last 3 months of punches. - To add one, call
POST /deviceswith a key whose connection isessl(GET /meshows the key's connection and eSSL server). Ask CS4 ADM support for such a key. - Commands are relayed through the eSSL server. Supported:
reboot,settime,check,POST /devices/{id}/fetch-attendance,POST /devices/{id}/sync-employees, and the employeepush/remove-from-devices/enroll(fingerprint and face) endpoints. Not available (answered with422):info,userquery,biodataquery,clearattlog,cleardata,custom— the eSSL server keeps those replies and owns the device's data.
# With a key whose connection is "essl" (GET /me → key.connection = "essl", key.esslServer = "Chennai eTimeTrackLite")
# the same POST registers a device that stays on that eSSL server (devices:write):
curl -X POST https://apiservice.adm.robeeta.com/api/v1/devices \
-H "X-Api-Key: $ADM_ESSL_KEY" -H "Content-Type: application/json" \
-d '{ "serialNumber": "CQZ7231260077", "name": "Plant 2 gate", "group": "CUST-001" }'
# → 201 { "id": 13, "source": "essl", "esslServer": "Chennai eTimeTrackLite", "esslLinked": false, ... }
# esslLinked becomes true once the serial is found on the eSSL server (within a minute).
# Any key of the application lists both devices (12 and 13) and all their punches.
CS4.Identity WebQuery → /api/v1
Calls of the old CS4.Identity WebQuery service and their replacement. Paths are relative to https://apiservice.adm.robeeta.com/api/v1.
| WebQuery | /api/v1 | Notes |
|---|---|---|
ReadDevices | GET /devices | ADM and eSSL devices in one list (source). |
SyncDevices | GET /devices | Status and counts are kept current by the server; just read the list. |
ReadDeviceLogs (TableName + LastSyncId) | GET /attendance/since?id={lastId} | No table names: one cursor for all months and all devices. Store nextId. |
CreateIdentity | POST /employees | Then POST /employees/{id}/push to send it to devices. |
CreateDeviceCommand AddUser | POST /employees/{id}/push | {deviceIds?, includeBiometrics} |
CreateDeviceCommand DeleteUser | POST /employees/{id}/remove-from-devices | {deviceIds?} |
CreateDeviceCommand EnrollUser | POST /employees/{id}/enroll | {deviceId, kind: "fp", fingerIndex} |
CreateDeviceCommand EnrollUserFace | POST /employees/{id}/enroll | {deviceId, kind: "face"} |
ReadCommandStatus | GET /commands/{id} | Or GET /commands?batchId=… / the command.completed webhook. |
ClearEsslLog | — | Not offered. |
Webhooks
Register an HTTPS endpoint (POST /webhooks, scope webhooks:manage) and choose events. The response contains the
signing secret once (whsec_…); rotate it with POST /webhooks/{id}/rotate-secret.
| Event | When |
|---|---|
attendance.punch | A new punch was received. |
command.completed | A command reached success / failed / fw_success / timeout. |
device.online / device.offline | A device connected again / stopped polling. |
user.enrolled | A fingerprint / face enrollment completed. |
Deliveries are POST requests with a JSON body (webhook bodies use snake_case envelope fields). Answer quickly with any 2xx (do slow work after responding);
otherwise the delivery is retried with exponential backoff (1, 2, 4 … 128 minutes, 8 attempts). After 50 consecutive failures the webhook is disabled
(re-enable with PUT {"isActive": true}). Deliveries can arrive more than once or out of order — de-duplicate by the delivery id.
Inspect attempts with GET /webhooks/{id}/deliveries and send one again with
POST /webhooks/{id}/deliveries/{deliveryId}/redeliver. The envelope's application_id is your application id.
POST https://your-app.example.com/hooks/adm
Content-Type: application/json
X-ADM-Event: command.completed
X-ADM-Delivery: dlv_Qm2VxR9cL4pT
X-ADM-Signature: t=1763190000,v1=5d2a...e91f
{
"id": "dlv_Qm2VxR9cL4pT",
"event": "command.completed",
"created_at": "2026-11-15T07:40:00Z",
"application_id": 42,
"data": { ... }
}
Signature verification
Every delivery carries X-ADM-Signature: t=<unix seconds>,v1=<hex> where
v1 = HEX(HMAC-SHA256(secret, "<t>.<raw body>")). Verify it over the raw body bytes before parsing,
compare in constant time and reject timestamps older than 5 minutes (replay protection).
C#
using System.Security.Cryptography;
using System.Text;
// ASP.NET Core minimal example: read the RAW body (verify before parsing JSON).
app.MapPost("/hooks/adm", async (HttpRequest req) =>
{
using var reader = new StreamReader(req.Body, Encoding.UTF8);
var body = await reader.ReadToEndAsync();
var header = req.Headers["X-ADM-Signature"].ToString();
if (!AdmWebhook.Verify(secret: "whsec_...", header, body)) return Results.Unauthorized();
// ... process; use X-ADM-Delivery to ignore duplicates
return Results.Ok();
});
public static class AdmWebhook
{
public static bool Verify(string secret, string header, string body, int toleranceSeconds = 300)
{
long t = 0; string? v1 = null;
foreach (var part in header.Split(','))
{
var kv = part.Split('=', 2);
if (kv.Length != 2) continue;
if (kv[0] == "t") long.TryParse(kv[1], out t);
else if (kv[0] == "v1") v1 = kv[1];
}
if (t == 0 || v1 is null) return false;
if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - t) > toleranceSeconds) return false; // replay protection
var mac = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), Encoding.UTF8.GetBytes($"{t}.{body}"));
var expected = Convert.ToHexStringLower(mac);
return CryptographicOperations.FixedTimeEquals(Encoding.ASCII.GetBytes(expected), Encoding.ASCII.GetBytes(v1));
}
}
Node.js
// Node.js (Express): keep the raw body for the signature check
const crypto = require('crypto');
const express = require('express');
const app = express();
function verifyAdmSignature(secret, header, rawBody, toleranceSec = 300) {
const parts = Object.fromEntries((header || '').split(',').map(p => p.split('=', 2)));
const t = Number(parts.t);
if (!t || !parts.v1) return false;
if (Math.abs(Date.now() / 1000 - t) > toleranceSec) return false; // replay protection
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`, 'utf8').digest('hex');
const a = Buffer.from(expected), b = Buffer.from(parts.v1);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
app.post('/hooks/adm', express.raw({ type: 'application/json' }), (req, res) => {
const raw = req.body.toString('utf8');
if (!verifyAdmSignature(process.env.ADM_WEBHOOK_SECRET, req.get('X-ADM-Signature'), raw)) return res.sendStatus(401);
const evt = JSON.parse(raw);
// ... process evt.event / evt.data; use evt.id (X-ADM-Delivery) to ignore duplicates
res.sendStatus(200);
});
Endpoints
All paths are relative to https://apiservice.adm.robeeta.com/api/v1. Full schemas and a "try it out" console are in Swagger.
| Method & path | Scope | Description |
|---|---|---|
| Application | ||
| GET /me | — | Application, key (scopes, rate limit, connection), device server to configure |
| Devices | ||
| GET /devices | devices:read | List (?search=&status=&group=) |
| GET /devices/stats | devices:read | Counts by status |
| GET /devices/{id} | devices:read | One device |
| GET /devices/{id}/status | devices:read | Live state: online, last seen, counts |
| POST /devices | devices:write | Register a serial number (serialNumber, name, group?) — reports to the key's connection |
| PUT /devices/{id} | devices:write | Name, location, time zone, FaceEx, group |
| DELETE /devices/{id} | devices:write | Remove the device |
| POST /devices/{id}/commands | devices:write (+admin) | reboot · info · check · settime · userquery · biodataquery · clearattlog* · cleardata* · custom* |
| POST /devices/{id}/fetch-attendance | devices:write | Re-upload punches {from, to} |
| POST /devices/{id}/sync-employees | devices:write | Send all active employees {includeBiometrics} |
| GET /devices/{id}/commands | devices:read | Commands of the device |
| POST /devices/{id}/commands/cancel-pending | devices:write | Cancel every pending command of the device |
| Commands | ||
| GET /commands | devices:read | ?status=&deviceId=&pin=&batchId=&page= |
| GET /commands/{id} | devices:read | Status and result |
| POST /commands/{id}/cancel | devices:write | Cancel a pending command |
| POST /commands/{id}/retry | devices:write | Re-queue a failed / timed-out / cancelled command |
| Employees & departments | ||
| GET /employees | users:read | ?search=&departmentId=&active=&group=&page=&pageSize= |
| GET /employees/{id} · /by-pin/{pin} · /by-ref/{externalRef} | users:read | One employee |
| POST /employees | users:write | Create |
| PUT /employees/{id} | users:write | Update (PIN can't change) |
| DELETE /employees/{id} | users:write | ?removeFromDevices=true (default) also deletes it on devices |
| POST /employees/{id}/push | users:write | Send to devices {deviceIds?, includeBiometrics} |
| POST /employees/{id}/remove-from-devices | users:write | {deviceIds?} |
| POST /employees/{id}/enroll | users:write | Remote enrollment {deviceId, kind: fp|face, fingerIndex} |
| GET /employees/{id}/enrollments | users:read | Devices that know the employee |
| GET /employees/{id}/biometrics | users:read | Template metadata (never the template) |
| DELETE /employees/{id}/biometrics | users:write | Delete stored templates on the server (?type=) |
| GET /departments · /departments/{id} | users:read | List / one |
| POST PUT DELETE /departments | users:write | Create / update / delete |
| Attendance | ||
| GET /attendance | attendance:read | ?from=&to=&pin=&deviceId=&departmentId=&group=&page=&pageSize= (max 1000) |
| GET /attendance/since | attendance:read | Cursor feed ?id=&limit=&group= → items, nextId, hasMore |
| GET /access-events | attendance:read | Access-control events |
| Reports | ||
| GET /reports/types | reports:read | Report types |
| POST /reports/run | reports:read | {type, from, to, departmentId?, deviceId?, pin?} → {title, subtitle, columns, rows, summary} |
| GET /reports/run.xlsx · .pdf · .csv | reports:read | Same as query string, as a file |
| Webhooks | ||
| GET /webhooks/events | webhooks:manage | Event names |
| GET POST /webhooks | webhooks:manage | List / create (secret returned once) |
| GET PUT DELETE /webhooks/{id} | webhooks:manage | One / update / delete |
| POST /webhooks/{id}/rotate-secret | webhooks:manage | New secret (returned once) |
| GET /webhooks/{id}/deliveries | webhooks:manage | Delivery attempts |
| POST /webhooks/{id}/deliveries/{deliveryId}/redeliver | webhooks:manage | Send a delivery again |
* requires devices:admin as well.