CS4 ADM API
v1 · build 26.11.10

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.

Base URLhttps://apiservice.adm.robeeta.com/api/v1
FormatJSON (camelCase), UTF-8, HTTPS only
ReferenceSwagger UI · OpenAPI JSON
Examplescurl and C# samples for common flows

Getting started

  1. 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) or essl (devices stay on a given eSSL eTimeTrackLite server).
  2. Call GET /me: it shows your application, the key and deviceServer — the address to configure on devices added with this key.
  3. Register each device with POST /devices (serial number, name, optional group). It reports where the key's connection points; unknown serial numbers are always refused.
  4. For adm devices set the device's cloud server (ADMS) to deviceServer.host and one of deviceServer.ports; the device becomes online on its first request. essl devices are read from the eSSL server every minute.
  5. Create employees, push them to devices, enroll fingerprints / faces, and read punches with the cursor feed GET /attendance/since or the attendance.punch webhook.

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.

ScopeGrants
devices:readRead devices and command status
devices:writeAdd/remove devices, send commands
devices:adminDangerous commands (clear data, custom)
users:readRead employees and departments
users:writeManage employees, push to devices, enroll
attendance:readRead attendance / access logs
reports:readRun reports
webhooks:manageManage 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 carries X-RateLimit-Limit.
  • Over the limit you get 429 Too Many Requests with a Retry-After header (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 get 403.
  • 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/json on POST / PUT. Property names are camelCase (serialNumber, pageSize); matching is case-insensitive on input.
  • PUT updates are partial: an omitted or null property keeps its current value; an empty string "" clears an optional text field; 0 clears an optional reference (departmentId, parentId).
  • Creating returns 201 Created with a Location header and the created object; deleting returns 200 with {"deleted": true}.
  • Actions that send something to devices return 202 Accepted with 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"
}
StatusMeaning
400Invalid input (validation message in detail; model errors also in errors).
401Missing, unknown, revoked or expired key; application suspended or API access disabled.
403Missing scope (missingScopes), caller IP not in the key's allowlist, or IP blocked after repeated invalid keys.
404The object does not exist in your application.
409Conflict: duplicate serial / PIN / external reference, device limit reached, device blocked, command no longer pending …
422The command type is not available for a device on an eSSL server (see Devices on eSSL servers).
429Rate limit exceeded — wait Retry-After seconds.
5xxServer 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

KindFormatFields
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→ sent→ success failed fw_success timeout
pendingQueued; the device has not polled yet (an offline device keeps its commands until it reconnects). Can be cancelled.
sentHanded to the device; waiting for its reply.
successThe device executed it (returnCode ≥ 0).
failedThe device returned an error (returnCode < 0, explained in error).
fw_successThe device reported failure for an enrollment, but a punch of that employee arrived afterwards — the enrollment worked (known firmware quirk). Treat as success.
timeoutSent but no reply within the timeout. Retry with POST /commands/{id}/retry.
cancelledCancelled 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 /devices with a key whose connection is essl (GET /me shows 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 employee push / remove-from-devices / enroll (fingerprint and face) endpoints. Not available (answered with 422): 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/v1Notes
ReadDevicesGET /devicesADM and eSSL devices in one list (source).
SyncDevicesGET /devicesStatus 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.
CreateIdentityPOST /employeesThen POST /employees/{id}/push to send it to devices.
CreateDeviceCommand AddUserPOST /employees/{id}/push{deviceIds?, includeBiometrics}
CreateDeviceCommand DeleteUserPOST /employees/{id}/remove-from-devices{deviceIds?}
CreateDeviceCommand EnrollUserPOST /employees/{id}/enroll{deviceId, kind: "fp", fingerIndex}
CreateDeviceCommand EnrollUserFacePOST /employees/{id}/enroll{deviceId, kind: "face"}
ReadCommandStatusGET /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.

EventWhen
attendance.punchA new punch was received.
command.completedA command reached success / failed / fw_success / timeout.
device.online / device.offlineA device connected again / stopped polling.
user.enrolledA 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 & pathScopeDescription
Application
GET /me—Application, key (scopes, rate limit, connection), device server to configure
Devices
GET /devicesdevices:readList (?search=&status=&group=)
GET /devices/statsdevices:readCounts by status
GET /devices/{id}devices:readOne device
GET /devices/{id}/statusdevices:readLive state: online, last seen, counts
POST /devicesdevices:writeRegister a serial number (serialNumber, name, group?) — reports to the key's connection
PUT /devices/{id}devices:writeName, location, time zone, FaceEx, group
DELETE /devices/{id}devices:writeRemove the device
POST /devices/{id}/commandsdevices:write (+admin)reboot · info · check · settime · userquery · biodataquery · clearattlog* · cleardata* · custom*
POST /devices/{id}/fetch-attendancedevices:writeRe-upload punches {from, to}
POST /devices/{id}/sync-employeesdevices:writeSend all active employees {includeBiometrics}
GET /devices/{id}/commandsdevices:readCommands of the device
POST /devices/{id}/commands/cancel-pendingdevices:writeCancel every pending command of the device
Commands
GET /commandsdevices:read?status=&deviceId=&pin=&batchId=&page=
GET /commands/{id}devices:readStatus and result
POST /commands/{id}/canceldevices:writeCancel a pending command
POST /commands/{id}/retrydevices:writeRe-queue a failed / timed-out / cancelled command
Employees & departments
GET /employeesusers:read?search=&departmentId=&active=&group=&page=&pageSize=
GET /employees/{id} · /by-pin/{pin} · /by-ref/{externalRef}users:readOne employee
POST /employeesusers:writeCreate
PUT /employees/{id}users:writeUpdate (PIN can't change)
DELETE /employees/{id}users:write?removeFromDevices=true (default) also deletes it on devices
POST /employees/{id}/pushusers:writeSend to devices {deviceIds?, includeBiometrics}
POST /employees/{id}/remove-from-devicesusers:write{deviceIds?}
POST /employees/{id}/enrollusers:writeRemote enrollment {deviceId, kind: fp|face, fingerIndex}
GET /employees/{id}/enrollmentsusers:readDevices that know the employee
GET /employees/{id}/biometricsusers:readTemplate metadata (never the template)
DELETE /employees/{id}/biometricsusers:writeDelete stored templates on the server (?type=)
GET /departments · /departments/{id}users:readList / one
POST PUT DELETE /departmentsusers:writeCreate / update / delete
Attendance
GET /attendanceattendance:read?from=&to=&pin=&deviceId=&departmentId=&group=&page=&pageSize= (max 1000)
GET /attendance/sinceattendance:readCursor feed ?id=&limit=&group= → items, nextId, hasMore
GET /access-eventsattendance:readAccess-control events
Reports
GET /reports/typesreports:readReport types
POST /reports/runreports:read{type, from, to, departmentId?, deviceId?, pin?} → {title, subtitle, columns, rows, summary}
GET /reports/run.xlsx · .pdf · .csvreports:readSame as query string, as a file
Webhooks
GET /webhooks/eventswebhooks:manageEvent names
GET POST /webhookswebhooks:manageList / create (secret returned once)
GET PUT DELETE /webhooks/{id}webhooks:manageOne / update / delete
POST /webhooks/{id}/rotate-secretwebhooks:manageNew secret (returned once)
GET /webhooks/{id}/deliverieswebhooks:manageDelivery attempts
POST /webhooks/{id}/deliveries/{deliveryId}/redeliverwebhooks:manageSend a delivery again

* requires devices:admin as well.