Examples
Common integration flows with curl and C# HttpClient. Replace the key with your application's key
(issued by CS4 ADM support) that has the scopes named in each step.
1. Add a device devices:write
Register the serial number first — the server refuses devices it does not know. Then set the server address on the device.
Its status changes from waiting to online on the first connection.
export ADM_KEY="adm_k3y9pr3f_XXXXXXXXXXXXXXXXXXXXXXXXXXXX"
# 0. Check the key and where its devices report
curl https://apiservice.adm.robeeta.com/api/v1/me -H "X-Api-Key: $ADM_KEY"
# → { "application": { "id": 7, "name": "Acme HRMS", ... },
# "key": { "connection": "adm", ... },
# "deviceServer": { "connection": "adm", "host": "adm.robeeta.com", "ports": [8081], "instructions": "..." } }
# 1. Register the device serial number (devices:write); "group" = your own customer / company id (optional)
curl -X POST https://apiservice.adm.robeeta.com/api/v1/devices \
-H "X-Api-Key: $ADM_KEY" -H "Content-Type: application/json" \
-d '{ "serialNumber": "CQZ7231260012", "name": "Main gate", "location": "Chennai HQ", "timeZone": "Asia/Kolkata", "group": "CUST-001" }'
# → 201 Created { "id": 12, "status": "waiting", "source": "adm", "group": "CUST-001", ... }
# 2. On the device: Comm. → Cloud Server Setting → deviceServer.host + one of deviceServer.ports (from /me).
# When it connects, the status becomes "online":
curl https://apiservice.adm.robeeta.com/api/v1/devices/12/status -H "X-Api-Key: $ADM_KEY"
# 3. Sync the clock (queued; executed on the next poll)
curl -X POST https://apiservice.adm.robeeta.com/api/v1/devices/12/commands \
-H "X-Api-Key: $ADM_KEY" -H "Content-Type: application/json" -d '{ "type": "settime" }'
2. Create an employee, push to all devices, enroll a fingerprint users:write
Creating an employee only stores it. /push queues the user record (and stored templates) for every device;
/enroll queues the user record plus an enroll command on one device, after which the employee scans the finger on that device.
Once enrolled, the template is uploaded and can be pushed to the other devices with /push again.
# 1. Create the employee (users:write)
curl -X POST https://apiservice.adm.robeeta.com/api/v1/employees \
-H "X-Api-Key: $ADM_KEY" -H "Content-Type: application/json" \
-d '{ "pin": "1001", "name": "Asha Raman", "cardNumber": "0012345678", "externalRef": "HR-000731" }'
# → 201 { "id": 501, "pin": "1001", ... }
# 2. Push to ALL devices (omit deviceIds) — returns a batchId
curl -X POST https://apiservice.adm.robeeta.com/api/v1/employees/501/push \
-H "X-Api-Key: $ADM_KEY" -H "Content-Type: application/json" -d '{ "includeBiometrics": true }'
# 3. Enroll the right index finger on device 12 (employee scans on the device)
curl -X POST https://apiservice.adm.robeeta.com/api/v1/employees/501/enroll \
-H "X-Api-Key: $ADM_KEY" -H "Content-Type: application/json" \
-d '{ "deviceId": 12, "kind": "fp", "fingerIndex": 6 }'
# → 202 { "batchId": "b_…", "commands": [ { "id": 88123, "type": "user.add" }, { "id": 88124, "type": "enroll.fp" } ] }
3. Poll command status devices:read
Commands are queued (pending) and run when the device polls. Final statuses: success, fw_success (treat as success),
failed, timeout, cancelled. Poll every few seconds — or subscribe to the command.completed webhook.
# Poll one command until the status is final
curl https://apiservice.adm.robeeta.com/api/v1/commands/88124 -H "X-Api-Key: $ADM_KEY"
# → { "id": 88124, "status": "success", "returnCode": 0, "executedAt": "2026-11-15T07:41:12Z", ... }
# All commands of a batch
curl "https://apiservice.adm.robeeta.com/api/v1/commands?batchId=b_5f1c2a9e0d4b" -H "X-Api-Key: $ADM_KEY"
4. Read attendance since a cursor attendance:read
Store nextId after processing each page and pass it as id next time. punchTime is the device's local wall-clock time (no offset);
receivedAt is UTC.
# Cursor feed: start with id=0, then always pass the returned nextId
curl "https://apiservice.adm.robeeta.com/api/v1/attendance/since?id=0&limit=1000" -H "X-Api-Key: $ADM_KEY"
# → { "items": [ { "id": 90001, "pin": "1001", "punchTime": "2026-11-15T09:02:41", "receivedAt": "2026-11-15T03:32:44Z", ... } ],
# "nextId": 90999, "hasMore": false }
# Date range query (device-local wall clock; "to" is exclusive)
curl "https://apiservice.adm.robeeta.com/api/v1/attendance?from=2026-11-01&to=2026-11-02&pageSize=500" -H "X-Api-Key: $ADM_KEY"
C# HttpClient
Setup and a small helper that turns problem responses into exceptions with the detail message:
using System.Net.Http.Json;
using System.Text.Json;
var http = new HttpClient { BaseAddress = new Uri("https://apiservice.adm.robeeta.com/api/v1/") };
http.DefaultRequestHeaders.Add("X-Api-Key", Environment.GetEnvironmentVariable("ADM_KEY"));
var json = new JsonSerializerOptions(JsonSerializerDefaults.Web); // camelCase
// Throws with the problem "detail" on 4xx/5xx
static async Task<T> Read<T>(HttpResponseMessage r, JsonSerializerOptions o)
{
if (!r.IsSuccessStatusCode)
{
var p = await r.Content.ReadFromJsonAsync<JsonElement>(o);
var detail = p.TryGetProperty("detail", out var d) ? d.GetString() : r.ReasonPhrase;
throw new HttpRequestException($"{(int)r.StatusCode}: {detail}");
}
return (await r.Content.ReadFromJsonAsync<T>(o))!;
}
Models (only the fields you need)
public sealed record Device(long Id, string SerialNumber, string Name, string Status);
public sealed record Employee(long Id, string Pin, string Name, string? ExternalRef);
public sealed record Command(long Id, string Type, string Status, long DeviceId, int? ReturnCode, string? Error);
public sealed record Queued(string? BatchId, int Count, List<Command> Commands, string Message);
public sealed record Punch(long Id, long DeviceId, string Pin, string? EmployeeName, DateTime PunchTime, DateTime ReceivedAt);
public sealed record Feed(List<Punch> Items, long NextId, bool HasMore);
Add a device
var device = await Read<Device>(await http.PostAsJsonAsync("devices",
new { serialNumber = "CQZ7231260012", name = "Main gate", location = "Chennai HQ", timeZone = "Asia/Kolkata" }, json), json);
Console.WriteLine($"Device {device.Id} registered, status {device.Status}");
Create employee, push to all devices, enroll fingerprint
// 1. Create (or find by your own reference)
var emp = await Read<Employee>(await http.PostAsJsonAsync("employees",
new { pin = "1001", name = "Asha Raman", externalRef = "HR-000731" }, json), json);
// 2. Push to every device (omit deviceIds)
var push = await Read<Queued>(await http.PostAsJsonAsync($"employees/{emp.Id}/push", new { includeBiometrics = true }, json), json);
Console.WriteLine($"{push.Count} commands queued, batch {push.BatchId}");
// 3. Remote fingerprint enrollment on one device
var enroll = await Read<Queued>(await http.PostAsJsonAsync($"employees/{emp.Id}/enroll",
new { deviceId = device.Id, kind = "fp", fingerIndex = 6 }, json), json);
var enrollCmd = enroll.Commands.Last(); // user.add first, then enroll.fp
Wait for the enrollment result
// Commands are only queued: the device runs them on its next poll. Poll (or use the command.completed webhook).
string[] final = ["success", "failed", "fw_success", "timeout", "cancelled"];
Command cmd;
var deadline = DateTime.UtcNow.AddMinutes(3);
do
{
await Task.Delay(TimeSpan.FromSeconds(5));
cmd = await Read<Command>(await http.GetAsync($"commands/{enrollCmd.Id}"), json);
} while (!final.Contains(cmd.Status) && DateTime.UtcNow < deadline);
Console.WriteLine(cmd.Status is "success" or "fw_success" ? "Enrolled" : $"Not enrolled: {cmd.Status} {cmd.Error}");
Import punches with the cursor feed
// Import every punch exactly once: persist nextId after each page.
long cursor = LoadCursor(); // 0 the first time
while (true)
{
var feed = await Read<Feed>(await http.GetAsync($"attendance/since?id={cursor}&limit=1000"), json);
foreach (var p in feed.Items)
SavePunch(p.Pin, p.PunchTime /* device-local wall clock, Kind=Unspecified */, p.DeviceId);
cursor = feed.NextId;
SaveCursor(cursor);
if (!feed.HasMore) break; // caught up — run again in a minute
}