Skip to content
AR ADMS Cloud
API v1.0.0
// AR TECHNOLOGIES LTD.

AR ADMS Cloud API

REST API for ERP, HRM, payroll, school management and other software.

  • Organization clients belong to one organization and use the client_credentials grant.
  • Developer apps are registered in the developer portal; each organization connects them with the authorization_code grant (PKCE S256) and can disconnect them at any time.

Every response from /api/v1 uses the same envelope: success, optional message, data and optional meta. Errors carry error.code (stable, machine-readable), error.message and sometimes error.details. Times are ISO 8601 in the organization's time zone; dates are YYYY-MM-DD in that zone. IDs are lowercase ULIDs.

Base URL
https://www.adms.arcloud.bd/api/v1
Token URL
https://www.adms.arcloud.bd/api/oauth/token
Authorize URL
https://www.adms.arcloud.bd/oauth/authorize

Getting started

Software for one organization

  1. An owner or admin of the organization opens Settings → API access and creates a client with the scopes it needs.
  2. They copy the client ID and secret (the secret is shown once) into your software's server-side settings.
  3. Your software gets a token with client_credentials and calls the API. How →

A product many organizations connect

  1. Register your company in the developer portal and create an app with your redirect URIs and scopes.
  2. Each customer's admin presses Connect in your product, signs in here, chooses their organization and allows access.
  3. You exchange the code for tokens, one pair per organization. How →

Organization clients

Exchange the client ID and secret for an access token. The token works for 1 hour; get a new one the same way when it expires (token_expired). Send the secret only from your server, never from a browser or mobile app. Leave out scope to get every scope the client has.

curl -X POST "https://www.adms.arcloud.bd/api/oauth/token" \
  -d grant_type=client_credentials \
  -d client_id=arc_… \
  -d client_secret=arcs_… \
  -d "scope=employees.read attendance.read"
{
  "access_token": "arat_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "employees.read attendance.read"
}

Then send it on every call:

curl "https://www.adms.arcloud.bd/api/v1/employees" -H "Authorization: Bearer arat_…"

Developer apps (OAuth2 authorization code + PKCE)

1. Create a PKCE pair for each connection attempt and keep the verifier on your server (for example in the user's session) together with a random state.

# Python
import base64, hashlib, secrets
verifier = secrets.token_urlsafe(64)[:96]
challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()

// PHP
$verifier = rtrim(strtr(base64_encode(random_bytes(64)), '+/', '-_'), '=');
$challenge = rtrim(strtr(base64_encode(hash('sha256', $verifier, true)), '+/', '-_'), '=');

2. Send the customer's admin to the consent page. They sign in, choose the organization and press Allow. Only owners and admins with the Manage API access permission can allow.

https://www.adms.arcloud.bd/oauth/authorize?response_type=code
  &client_id=arc_…
  &redirect_uri=https%3A%2F%2Fyour-app.example%2Foauth%2Fcallback
  &scope=employees.read%20attendance.read
  &state=RANDOM_STATE
  &code_challenge=CHALLENGE
  &code_challenge_method=S256

3. Handle the redirect. We send the browser to your redirect_uri with code and state, or with error (access_denied when the admin declines). Check that state matches. Redirect URIs must be registered exactly and use https (http only for localhost).

4. Exchange the code within 10 minutes. A code works once.

curl -X POST "https://www.adms.arcloud.bd/api/oauth/token" \
  -u "arc_…:arcs_…" \
  -d grant_type=authorization_code \
  -d code=arac_… \
  -d redirect_uri=https://your-app.example/oauth/callback \
  -d code_verifier=VERIFIER
{
  "access_token": "arat_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "arrt_…",
  "scope": "employees.read attendance.read",
  "organization": { "id": "01jcz5k2n4p6r8t0v2x4z6b8d0", "name": "Acme Garments Ltd." }
}

5. Refresh before or after the hour is up. Store the new refresh token every time: each one works once and lives 30 days. Using an old refresh token again revokes every token of that connection, so the customer would have to connect again.

curl -X POST "https://www.adms.arcloud.bd/api/oauth/token" -u "arc_…:arcs_…" \
  -d grant_type=refresh_token -d refresh_token=arrt_…

An organization can disconnect your app at any time under Settings → API access. Its tokens stop working at once (app_disconnected), and refreshing fails with invalid_grant.

Scopes

Ask only for what you need; the organization sees the list before allowing access.

ScopeAllows
organization.readRead the organization profile
branches.readRead branches
employees.readRead employees and their device user IDs
employees.writeCreate and update employees
devices.readRead devices and their status
devices.commandAsk devices to sync punches
attendance.readRead daily attendance results
attendance.raw.readRead raw punches from devices
leave.readRead leave applications
reports.readRead attendance reports
webhooks.manageCreate webhooks that send the events allowed by the read permissions

Responses and errors

{
  "success": true,
  "message": "Employee created.",
  "data": { … },
  "meta": { "pagination": { … } }
}
{
  "success": false,
  "error": {
    "code": "insufficient_scope",
    "message": "This token lacks the \"attendance.read\" scope.",
    "details": { "required_scope": "attendance.read" }
  }
}

Program against error.code; messages may change. Every response carries an X-Request-Id header: quote it when you contact support.

CodeHTTPMeaning
invalid_token401No token, an unknown token or a revoked one.
token_expired401The access token is older than 1 hour. Get a new one.
client_revoked401The organization deleted this API client.
app_disconnected401The organization disconnected your app. Ask them to connect it again.
insufficient_scope403The token lacks the scope this endpoint needs (see error.details.required_scope).
ip_not_allowed403The client has an IP allowlist and this request came from another address.
organization_unavailable403The organization is suspended or closed.
api_not_in_plan403The organization's plan does not include API access.
developer_suspended403Your developer account is suspended.
organization_read_only403The subscription expired: reading works, changes are refused.
plan_limit_reached403For example the employee limit of the organization's plan.
not_found404The resource does not exist or belongs to another organization.
employee_code_taken409Another employee already has this code.
device_user_id_taken409The device user ID belongs to another employee.
device_disabled409The device is disabled.
validation_failed422Field errors are in error.details (field → messages).
range_too_large422The date range is longer than this endpoint allows.
invalid_cursor422The cursor was changed or comes from another query. Start again without it.
invalid_idempotency_key422Idempotency-Key has characters that are not allowed or is too long.
idempotency_key_reused422The key was already used with a different request body.
webhooks_not_in_plan403The organization's plan does not include webhooks.
event_not_allowed403The token's scopes do not cover an event you asked for (see error.details).
endpoint_disabled409The webhook endpoint is switched off. PATCH it with status active first.
invalid_webhook_url422The URL is not https or does not resolve to a public address.
endpoint_limit_reached422At most 5 webhook endpoints per client and organization.
rate_limited429More than 120 requests in a minute from this client. Wait Retry-After seconds.
daily_quota_exceeded429The daily quota is used up. It resets at 00:00 UTC.

Pagination

Lists use page and per_page (at most 200) and return meta.pagination with page, per_page, total and last_page.

Raw punches can be many, so /punches uses a cursor instead: repeat the same request with cursor set to meta.next_cursor until it is null. Punches that arrive later (a device that was offline) have older times, so to collect everything re-read recent days now and then; the punch time plus device_user_id identifies a punch.

Rate limits and quotas

  • 120 requests per minute per client. Headers: X-RateLimit-Limit, X-RateLimit-Remaining.
  • Daily quota, reset at 00:00 UTC. Organization clients share the quota of the organization's plan; developer apps share their developer account's quota across every connected organization. Headers: X-Quota-Limit, X-Quota-Remaining.
  • Over a limit you get 429 with Retry-After (seconds). Wait that long; do not retry in a loop.

Idempotency

Send an Idempotency-Key header with POST requests. If the network fails and you retry with the same key within 24 hours, you get the first response again (header Idempotent-Replayed: true) and nothing is created twice. Use a new key for each new action.

Times, IDs and changes

  • Times are ISO 8601 with the organization's UTC offset, for example 2026-11-16T09:07:12+06:00. Dates (from, to, date) are days in the organization's time zone.
  • IDs are lowercase ULIDs. Employee code and device_user_ids are the organization's own values.
  • Attendance is recalculated when late punches arrive or HR corrects a day. Sync with updated_since instead of assuming a day never changes.
  • Version 1 only grows: new fields and new enum values may appear, so ignore what you do not know. Breaking changes would come as /api/v2, announced in advance.

Webhooks

Instead of asking the API every few minutes, let us call you. An organization adds your URL under Webhooks in the panel, chooses events and gets a signing secret (whsec_…, shown once). From then on every event is sent as an HTTPS POST with a JSON body. Answer with any 2xx status within 10 seconds; do the real work afterwards (for example in a queue).

POST /your/webhook/url
Content-Type: application/json
User-Agent: AR-Attendance-Webhooks/1.0
X-AR-Event-Id: 01jd2k5q8w3e7r9t1y4u6i8o0p
X-AR-Event-Type: attendance.processed
X-AR-Timestamp: 1795237200
X-AR-Signature: v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

{
  "id": "01jd2k5q8w3e7r9t1y4u6i8o0p",
  "type": "attendance.processed",
  "created_at": "2026-11-16T12:05:02Z",
  "organization": { "id": "01jcz5k2n4p6r8t0v2x4z6b8d0" },
  "data": {
    "attendance": { "employee": { … }, "date": "2026-11-16", "status": "present", … },
    "previous_status": "in_progress"
  }
}

Check every request before trusting it: compute HMAC-SHA256 of timestamp + "." + raw body with the secret, compare it with the v1= value in constant time, and reject timestamps more than 5 minutes old. Use the raw body exactly as received, before any JSON parsing.

// PHP
$body = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_AR_TIMESTAMP'] ?? '';
$expected = 'v1=' . hash_hmac('sha256', $ts . '.' . $body, getenv('AR_WEBHOOK_SECRET'));
$valid = ctype_digit($ts) && abs(time() - (int) $ts) <= 300
    && hash_equals($expected, $_SERVER['HTTP_X_AR_SIGNATURE'] ?? '');

// Node.js (Express: app.post(path, express.raw({ type: 'application/json' }), handler))
const crypto = require('crypto');
const ts = req.get('X-AR-Timestamp');
const expected = 'v1=' + crypto.createHmac('sha256', process.env.AR_WEBHOOK_SECRET).update(ts + '.' + req.body).digest('hex');
const given = req.get('X-AR-Signature') || '';
const valid = Math.abs(Date.now() / 1000 - Number(ts)) <= 300 && given.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));

# Python
import hmac, hashlib, time
expected = "v1=" + hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()
valid = abs(time.time() - int(ts)) <= 300 and hmac.compare_digest(expected, signature)
  • Duplicates: a retry can deliver an event you already processed. Store id and ignore events you have seen.
  • Order: events can arrive out of order. For attendance, the newest attendance.calculated_at of a day wins.
  • Retries: if we get no 2xx, we try again after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h, then give up. Redirects are not followed. The organization can resend any event from its delivery log.
  • Switched off: after 30 failed attempts in a row the endpoint is switched off until the organization switches it on again.
  • Payloads use the same shapes as the API: employee as in Get an employee, attendance as in Daily attendance, device as in Get a device, punches as in Raw punches.
EventWhendata contains
attendance.raw_receivedNew punches arrived from a device (up to 100 per event)device, punches[] (up to 100)
attendance.processedA day of attendance was calculated or changedattendance, previous_status
attendance.correctedHR corrected a day (missing punch, status change)correction, employee
employee.createdAn employee was addedemployee
employee.updatedAn employee was changed, deactivated or got new device IDsemployee
device.onlineA device came onlinedevice, reason
device.offlineA device stopped respondingdevice, reason
collector.onlineA Windows Collector came onlinecollector
collector.offlineA Windows Collector stopped sending heartbeatscollector
sync.completedA requested device sync finishedcommand, device
sync.failedA requested device sync failedcommand, device
webhook.testThe “Send test event” buttonmessage

Apps can manage their own endpoints with the Webhooks API (scope webhooks.manage). Such an endpoint receives only events the app's read scopes cover, and is deleted when the organization disconnects the app. The organization sees it on its Webhooks page and can switch it off.

Event bodies

attendance.raw_received New punches

Punches that were just stored, up to 100 per event, oldest first. The same punch is never sent twice.

FieldTypeDescription
id * string

Event ID; the same as X-AR-Event-Id. Use it to ignore duplicates.

type * string
created_at * date-time

When it happened (UTC).

organization * object
id * string

The organization's ID (GET /api/v1/organization).

data * object
device * object
id * string
name * string
serial_number * string | null
punches * object[]
punched_at * date-time
device_local_time * string | null

The time exactly as the device's clock reported it.

device_user_id * string
employee * object | null

null while the device user ID is not linked to an employee.

id * string
code * string
device_id * string | null
state * integer | null

Punch state key pressed on the device (0 check-in, 1 check-out, 2 break-out, 3 break-in, 4 OT-in, 5 OT-out).

verify_mode * integer | null

How the person was verified (device code: 1 fingerprint, 15 face, 4 card, 0 password…).

source * string
admscollectorapiimport
{
    "id": "01jd3m2a9b8c7d6e5f4g3h2j1k",
    "type": "attendance.raw_received",
    "created_at": "2026-11-18T03:12:40Z",
    "organization": {
        "id": "01jcz5k2n4p6r8t0v2x4z6b8d0"
    },
    "data": {
        "device": {
            "id": "01jcz7r5t1a2b3c4d5e6f7g8h9",
            "name": "Main gate",
            "serial_number": "CQUJ214560123"
        },
        "punches": [
            {
                "punched_at": "2026-11-16T09:07:12+06:00",
                "device_local_time": "2026-11-16 09:07:12",
                "device_user_id": "1001",
                "employee": {
                    "id": "01jcz8x4m2q7v9t3k5h6n8p0rs",
                    "code": "E1001"
                },
                "device_id": "01jcz7r5t1a2b3c4d5e6f7g8h9",
                "state": 0,
                "verify_mode": 1,
                "source": "adms"
            }
        ]
    }
}
attendance.processed A day was calculated or changed

Sent when something visible in the day changed. Days can be recalculated later (late punches, corrections); keep the newest calculated_at per employee and date.

FieldTypeDescription
id * string

Event ID; the same as X-AR-Event-Id. Use it to ignore duplicates.

type * string
created_at * date-time

When it happened (UTC).

organization * object
id * string

The organization's ID (GET /api/v1/organization).

data * object
attendance * object
employee * object
id * string | null
code * string | null
name * string | null
date * date
status * string

in_progress: checked in and the shift is still running. incomplete: only one punch and the day is over. half_day / absent: worked less than the shift's thresholds.

presenthalf_dayabsentincompletein_progressweekendholidayleave
day_type * string
workingweekendholiday
shift * object | null

The shift as it was when the day was calculated.

name string
type string
fixedflexible
start string
end string
check_in * date-time | null
check_out * date-time | null
worked_minutes * integer
break_minutes * integer
late_minutes * integer
early_out_minutes * integer
overtime_minutes * integer
is_late * boolean
flags * string[]

Notes from the engine, for example late, early_out, missing_in, missing_out, odd_punches, clock_drift, insufficient_hours, worked_on_off_day.

needs_review * boolean
corrected * boolean

HR changed this day by hand.

calculated_at * date-time | null
previous_status * string | null

Status before this change; null for a new day.

{
    "id": "01jd3m2a9b8c7d6e5f4g3h2j1k",
    "type": "attendance.processed",
    "created_at": "2026-11-18T03:12:40Z",
    "organization": {
        "id": "01jcz5k2n4p6r8t0v2x4z6b8d0"
    },
    "data": {
        "attendance": {
            "employee": {
                "id": "01jcz8x4m2q7v9t3k5h6n8p0rs",
                "code": "E1001",
                "name": "Rahim Uddin"
            },
            "date": "2026-11-16",
            "status": "present",
            "day_type": "working",
            "shift": {
                "name": "General",
                "type": "fixed",
                "start": "09:00",
                "end": "18:00"
            },
            "check_in": "2026-11-16T09:07:12+06:00",
            "check_out": "2026-11-16T18:04:40+06:00",
            "worked_minutes": 477,
            "break_minutes": 60,
            "late_minutes": 0,
            "early_out_minutes": 0,
            "overtime_minutes": 0,
            "is_late": false,
            "flags": [],
            "needs_review": false,
            "corrected": false,
            "calculated_at": "2026-11-16T18:05:02+06:00"
        },
        "previous_status": "in_progress"
    }
}
attendance.corrected HR corrected a day

A correction was approved. The recalculated day follows as attendance.processed.

FieldTypeDescription
id * string

Event ID; the same as X-AR-Event-Id. Use it to ignore duplicates.

type * string
created_at * date-time

When it happened (UTC).

organization * object
id * string

The organization's ID (GET /api/v1/organization).

data * object
correction * object
type * string
punchstatus
date * date
punch_time date-time

Added punch (type punch).

punch_state integer
status string

New status (type status).

reason * string
employee * object
id * string | null
code * string | null
name * string | null
note * string
{
    "id": "01jd3m2a9b8c7d6e5f4g3h2j1k",
    "type": "attendance.corrected",
    "created_at": "2026-11-18T03:12:40Z",
    "organization": {
        "id": "01jcz5k2n4p6r8t0v2x4z6b8d0"
    },
    "data": {
        "correction": {
            "type": "punch",
            "date": "2026-11-17",
            "punch_time": "2026-11-17T18:00:00+06:00",
            "punch_state": 1,
            "status": "present",
            "reason": "Forgot to punch out"
        },
        "employee": {
            "id": "01jcz8x4m2q7v9t3k5h6n8p0rs",
            "code": "E1001",
            "name": "Rahim Uddin"
        },
        "note": "The recalculated day follows as attendance.processed."
    }
}
employee.created An employee was added

The employee as GET /api/v1/employees/{id} returns it.

FieldTypeDescription
id * string

Event ID; the same as X-AR-Event-Id. Use it to ignore duplicates.

type * string
created_at * date-time

When it happened (UTC).

organization * object
id * string

The organization's ID (GET /api/v1/organization).

data * object
employee * object
id * string
code * string

The organization's own employee code (unique

name * string
phone * string | null
email * email | null
branch * object | null
id * string
name * string
department * string | null
designation * string | null
joining_date * date | null
status * string
activeinactive
device_user_ids * string[]

User IDs (PINs) this employee has on the organization's devices.

created_at * date-time
updated_at * date-time
{
    "id": "01jd3m2a9b8c7d6e5f4g3h2j1k",
    "type": "employee.created",
    "created_at": "2026-11-18T03:12:40Z",
    "organization": {
        "id": "01jcz5k2n4p6r8t0v2x4z6b8d0"
    },
    "data": {
        "employee": {
            "id": "01jcz8x4m2q7v9t3k5h6n8p0rs",
            "code": "E1001",
            "name": "Rahim Uddin",
            "phone": "+8801711000000",
            "email": "rahim@example.com",
            "branch": {
                "id": "01jcz6f0a9b8c7d6e5f4g3h2j1",
                "name": "Head Office"
            },
            "department": "Production",
            "designation": "Operator",
            "joining_date": "2026-01-15",
            "status": "active",
            "device_user_ids": [
                "1001"
            ],
            "created_at": "2026-11-01T10:15:00+06:00",
            "updated_at": "2026-11-10T09:02:11+06:00"
        }
    }
}
employee.updated An employee changed

Details, status or device user IDs changed.

FieldTypeDescription
id * string

Event ID; the same as X-AR-Event-Id. Use it to ignore duplicates.

type * string
created_at * date-time

When it happened (UTC).

organization * object
id * string

The organization's ID (GET /api/v1/organization).

data * object
employee * object
id * string
code * string

The organization's own employee code (unique

name * string
phone * string | null
email * email | null
branch * object | null
id * string
name * string
department * string | null
designation * string | null
joining_date * date | null
status * string
activeinactive
device_user_ids * string[]

User IDs (PINs) this employee has on the organization's devices.

created_at * date-time
updated_at * date-time
{
    "id": "01jd3m2a9b8c7d6e5f4g3h2j1k",
    "type": "employee.updated",
    "created_at": "2026-11-18T03:12:40Z",
    "organization": {
        "id": "01jcz5k2n4p6r8t0v2x4z6b8d0"
    },
    "data": {
        "employee": {
            "id": "01jcz8x4m2q7v9t3k5h6n8p0rs",
            "code": "E1001",
            "name": "Rahim Uddin",
            "phone": "+8801711000000",
            "email": "rahim@example.com",
            "branch": {
                "id": "01jcz6f0a9b8c7d6e5f4g3h2j1",
                "name": "Head Office"
            },
            "department": "Production",
            "designation": "Operator",
            "joining_date": "2026-01-15",
            "status": "active",
            "device_user_ids": [
                "1001"
            ],
            "created_at": "2026-11-01T10:15:00+06:00",
            "updated_at": "2026-11-10T09:02:11+06:00"
        }
    }
}
device.online A device came online

The device made contact again.

FieldTypeDescription
id * string

Event ID; the same as X-AR-Event-Id. Use it to ignore duplicates.

type * string
created_at * date-time

When it happened (UTC).

organization * object
id * string

The organization's ID (GET /api/v1/organization).

data * object
device * object
id * string
name * string
serial_number * string | null
connection * string

adms: the device talks to the cloud directly. collector: through a Windows Collector on the LAN.

admscollector
branch * object | null
id * string
name * string
status * string
unknownonlineofflinedisabled
model * string | null
firmware * string | null
last_seen_at * date-time | null
last_punch_at * date-time | null
reason * string | null
{
    "id": "01jd3m2a9b8c7d6e5f4g3h2j1k",
    "type": "device.online",
    "created_at": "2026-11-18T03:12:40Z",
    "organization": {
        "id": "01jcz5k2n4p6r8t0v2x4z6b8d0"
    },
    "data": {
        "device": {
            "id": "01jcz7r5t1a2b3c4d5e6f7g8h9",
            "name": "Main gate",
            "serial_number": "CQUJ214560123",
            "connection": "adms",
            "branch": {
                "id": "01jcz6f0a9b8c7d6e5f4g3h2j1",
                "name": "Head Office"
            },
            "status": "online",
            "model": "K50-A",
            "firmware": "Ver 6.60 Apr 28 2017",
            "last_seen_at": "2026-11-17T08:20:05+06:00",
            "last_punch_at": "2026-11-17T08:01:44+06:00"
        },
        "reason": "collector offline"
    }
}
device.offline A device went offline

No contact for 2 minutes (ADMS) or the Collector cannot reach it.

FieldTypeDescription
id * string

Event ID; the same as X-AR-Event-Id. Use it to ignore duplicates.

type * string
created_at * date-time

When it happened (UTC).

organization * object
id * string

The organization's ID (GET /api/v1/organization).

data * object
device * object
id * string
name * string
serial_number * string | null
connection * string

adms: the device talks to the cloud directly. collector: through a Windows Collector on the LAN.

admscollector
branch * object | null
id * string
name * string
status * string
unknownonlineofflinedisabled
model * string | null
firmware * string | null
last_seen_at * date-time | null
last_punch_at * date-time | null
reason * string | null
{
    "id": "01jd3m2a9b8c7d6e5f4g3h2j1k",
    "type": "device.offline",
    "created_at": "2026-11-18T03:12:40Z",
    "organization": {
        "id": "01jcz5k2n4p6r8t0v2x4z6b8d0"
    },
    "data": {
        "device": {
            "id": "01jcz7r5t1a2b3c4d5e6f7g8h9",
            "name": "Main gate",
            "serial_number": "CQUJ214560123",
            "connection": "adms",
            "branch": {
                "id": "01jcz6f0a9b8c7d6e5f4g3h2j1",
                "name": "Head Office"
            },
            "status": "online",
            "model": "K50-A",
            "firmware": "Ver 6.60 Apr 28 2017",
            "last_seen_at": "2026-11-17T08:20:05+06:00",
            "last_punch_at": "2026-11-17T08:01:44+06:00"
        },
        "reason": "collector offline"
    }
}
collector.online A Windows Collector came online

A heartbeat arrived after the Collector was offline.

FieldTypeDescription
id * string

Event ID; the same as X-AR-Event-Id. Use it to ignore duplicates.

type * string
created_at * date-time

When it happened (UTC).

organization * object
id * string

The organization's ID (GET /api/v1/organization).

data * object
collector * object
id * string
name * string
version * string | null
hostname * string | null
last_heartbeat_at * date-time | null
{
    "id": "01jd3m2a9b8c7d6e5f4g3h2j1k",
    "type": "collector.online",
    "created_at": "2026-11-18T03:12:40Z",
    "organization": {
        "id": "01jcz5k2n4p6r8t0v2x4z6b8d0"
    },
    "data": {
        "collector": {
            "id": "01jcz9a1b2c3d4e5f6g7h8j9k0",
            "name": "Factory office PC",
            "version": "1.2.3",
            "hostname": "HR-PC-01",
            "last_heartbeat_at": "2026-11-18T09:10:00+06:00"
        }
    }
}
collector.offline A Windows Collector went offline

No heartbeat for 3 minutes.

FieldTypeDescription
id * string

Event ID; the same as X-AR-Event-Id. Use it to ignore duplicates.

type * string
created_at * date-time

When it happened (UTC).

organization * object
id * string

The organization's ID (GET /api/v1/organization).

data * object
collector * object
id * string
name * string
version * string | null
hostname * string | null
last_heartbeat_at * date-time | null
{
    "id": "01jd3m2a9b8c7d6e5f4g3h2j1k",
    "type": "collector.offline",
    "created_at": "2026-11-18T03:12:40Z",
    "organization": {
        "id": "01jcz5k2n4p6r8t0v2x4z6b8d0"
    },
    "data": {
        "collector": {
            "id": "01jcz9a1b2c3d4e5f6g7h8j9k0",
            "name": "Factory office PC",
            "version": "1.2.3",
            "hostname": "HR-PC-01",
            "last_heartbeat_at": "2026-11-18T09:10:00+06:00"
        }
    }
}
sync.completed A device sync finished

A sync requested in the panel or with POST /api/v1/devices/{id}/sync finished.

FieldTypeDescription
id * string

Event ID; the same as X-AR-Event-Id. Use it to ignore duplicates.

type * string
created_at * date-time

When it happened (UTC).

organization * object
id * string

The organization's ID (GET /api/v1/organization).

data * object
command * object
id * string
status * string
succeededfailed
requested_at * date-time | null
completed_at * date-time | null
message * string | null
device * object | null
id * string
name * string
serial_number * string | null
connection * string

adms: the device talks to the cloud directly. collector: through a Windows Collector on the LAN.

admscollector
branch * object | null
id * string
name * string
status * string
unknownonlineofflinedisabled
model * string | null
firmware * string | null
last_seen_at * date-time | null
last_punch_at * date-time | null
{
    "id": "01jd3m2a9b8c7d6e5f4g3h2j1k",
    "type": "sync.completed",
    "created_at": "2026-11-18T03:12:40Z",
    "organization": {
        "id": "01jcz5k2n4p6r8t0v2x4z6b8d0"
    },
    "data": {
        "command": {
            "id": "01jd0a1b2c3d4e5f6g7h8j9k0m",
            "status": "succeeded",
            "requested_at": "2026-11-18T09:00:00+06:00",
            "completed_at": "2026-11-18T09:00:41+06:00",
            "message": null
        },
        "device": {
            "id": "01jcz7r5t1a2b3c4d5e6f7g8h9",
            "name": "Main gate",
            "serial_number": "CQUJ214560123",
            "connection": "adms",
            "branch": {
                "id": "01jcz6f0a9b8c7d6e5f4g3h2j1",
                "name": "Head Office"
            },
            "status": "online",
            "model": "K50-A",
            "firmware": "Ver 6.60 Apr 28 2017",
            "last_seen_at": "2026-11-17T08:20:05+06:00",
            "last_punch_at": "2026-11-17T08:01:44+06:00"
        }
    }
}
sync.failed A device sync failed

The device or Collector reported a failure.

FieldTypeDescription
id * string

Event ID; the same as X-AR-Event-Id. Use it to ignore duplicates.

type * string
created_at * date-time

When it happened (UTC).

organization * object
id * string

The organization's ID (GET /api/v1/organization).

data * object
command * object
id * string
status * string
succeededfailed
requested_at * date-time | null
completed_at * date-time | null
message * string | null
device * object | null
id * string
name * string
serial_number * string | null
connection * string

adms: the device talks to the cloud directly. collector: through a Windows Collector on the LAN.

admscollector
branch * object | null
id * string
name * string
status * string
unknownonlineofflinedisabled
model * string | null
firmware * string | null
last_seen_at * date-time | null
last_punch_at * date-time | null
{
    "id": "01jd3m2a9b8c7d6e5f4g3h2j1k",
    "type": "sync.failed",
    "created_at": "2026-11-18T03:12:40Z",
    "organization": {
        "id": "01jcz5k2n4p6r8t0v2x4z6b8d0"
    },
    "data": {
        "command": {
            "id": "01jd0a1b2c3d4e5f6g7h8j9k0m",
            "status": "succeeded",
            "requested_at": "2026-11-18T09:00:00+06:00",
            "completed_at": "2026-11-18T09:00:41+06:00",
            "message": null
        },
        "device": {
            "id": "01jcz7r5t1a2b3c4d5e6f7g8h9",
            "name": "Main gate",
            "serial_number": "CQUJ214560123",
            "connection": "adms",
            "branch": {
                "id": "01jcz6f0a9b8c7d6e5f4g3h2j1",
                "name": "Head Office"
            },
            "status": "online",
            "model": "K50-A",
            "firmware": "Ver 6.60 Apr 28 2017",
            "last_seen_at": "2026-11-17T08:20:05+06:00",
            "last_punch_at": "2026-11-17T08:01:44+06:00"
        }
    }
}
webhook.test Test event

Sent by the Send test event button or POST /api/v1/webhooks/{id}/test.

FieldTypeDescription
id * string

Event ID; the same as X-AR-Event-Id. Use it to ignore duplicates.

type * string
created_at * date-time

When it happened (UTC).

organization * object
id * string

The organization's ID (GET /api/v1/organization).

data * object
message * string
endpoint * object
id * string
{
    "id": "01jd3m2a9b8c7d6e5f4g3h2j1k",
    "type": "webhook.test",
    "created_at": "2026-11-18T03:12:40Z",
    "organization": {
        "id": "01jcz5k2n4p6r8t0v2x4z6b8d0"
    },
    "data": {
        "message": "Test event from AR ADMS Cloud. If you can read this",
        "endpoint": {
            "id": "01jd3k4m6p8r0t2v4x6z8b0d2f"
        }
    }
}

Authentication

POST /api/oauth/token

Get an access token

Send client credentials in the form body (client_id, client_secret) or as HTTP Basic authentication. Access tokens last 1 hour. Developer apps also get a refresh token that lasts 30 days and works once: every refresh returns a new pair, and reusing an old refresh token revokes the whole chain. Errors here use the OAuth 2.0 format (error, error_description), not the API envelope.

Request body

FieldTypeDescription
grant_type * string
client_credentialsauthorization_coderefresh_token
client_id string

Unless sent as HTTP Basic.

client_secret string

Unless sent as HTTP Basic.

scope string

Space-separated. Optional: defaults to every scope the client has (client_credentials) or that was granted (refresh_token).

code string

authorization_code only.

redirect_uri string

authorization_code only; the same value as in the authorization request.

code_verifier string

authorization_code only; the PKCE verifier (43–128 characters).

refresh_token string

refresh_token only.

Response 200

FieldTypeDescription
access_token * string
token_type * string
expires_in * integer
scope * string
refresh_token string

Developer apps only. Works once.

organization object

Developer apps only. The organization that granted access.

id string
name string

Organization

GET /api/v1/organization organization.read

The organization

Response 200

FieldTypeDescription
success * boolean
data * object
id * string

The same ID as organization.id in developer-app token responses.

name * string
timezone * string
country * string
currency * string
status * string
trialactivesuspendedcancelled

Example request

curl "https://www.adms.arcloud.bd/api/v1/organization" \
  -H "Authorization: Bearer $TOKEN"

Example response

{
    "success": true,
    "data": {
        "id": "01jcz5k2n4p6r8t0v2x4z6b8d0",
        "name": "Acme Garments Ltd.",
        "timezone": "Asia/Dhaka",
        "country": "BD",
        "currency": "BDT",
        "status": "active"
    }
}
GET /api/v1/branches branches.read

Branches

Response 200

FieldTypeDescription
success * boolean
data * object[]
id * string
code * string
name * string
timezone * string
weekend_days * integer[]

ISO weekday numbers, 1 = Monday … 7 = Sunday.

status * string
activeinactive

Example request

curl "https://www.adms.arcloud.bd/api/v1/branches" \
  -H "Authorization: Bearer $TOKEN"

Example response

{
    "success": true,
    "data": [
        {
            "id": "01jcz6f0a9b8c7d6e5f4g3h2j1",
            "code": "HO",
            "name": "Head Office",
            "timezone": "Asia/Dhaka",
            "weekend_days": [
                5
            ],
            "status": "active"
        }
    ]
}

Employees

GET /api/v1/employees employees.read

List employees

Parameters

NameInTypeDescription
branch_id query string

Only this branch.

status query string
default active

Which employees to return.

activeinactiveall
updated_since query date-time

Only employees changed at or after this time (ISO 8601). Use it to sync changes.

device_user_id query string

Only the employee who has this user ID on devices.

page query integer
default 1
per_page query integer
default 50

Items per page, 1–200.

Response 200

FieldTypeDescription
success * boolean
data * object[]
id * string
code * string

The organization's own employee code (unique

name * string
phone * string | null
email * email | null
branch * object | null
id * string
name * string
department * string | null
designation * string | null
joining_date * date | null
status * string
activeinactive
device_user_ids * string[]

User IDs (PINs) this employee has on the organization's devices.

created_at * date-time
updated_at * date-time
meta * object
pagination * object
page * integer
per_page * integer
total * integer
last_page * integer

Example request

curl "https://www.adms.arcloud.bd/api/v1/employees" \
  -H "Authorization: Bearer $TOKEN"

Example response

{
    "success": true,
    "data": [
        {
            "id": "01jcz8x4m2q7v9t3k5h6n8p0rs",
            "code": "E1001",
            "name": "Rahim Uddin",
            "phone": "+8801711000000",
            "email": "rahim@example.com",
            "branch": {
                "id": "01jcz6f0a9b8c7d6e5f4g3h2j1",
                "name": "Head Office"
            },
            "department": "Production",
            "designation": "Operator",
            "joining_date": "2026-01-15",
            "status": "active",
            "device_user_ids": [
                "1001"
            ],
            "created_at": "2026-11-01T10:15:00+06:00",
            "updated_at": "2026-11-10T09:02:11+06:00"
        }
    ],
    "meta": {
        "pagination": {
            "page": 1,
            "per_page": 50,
            "total": 128,
            "last_page": 3
        }
    }
}
POST /api/v1/employees employees.write

Create an employee

Counts against the organization's employee limit. device_user_ids links the IDs the employee uses on every device of the organization; punches already received with those IDs are attached and attendance is recalculated.

Parameters

NameInTypeDescription
Idempotency-Key header string

Any unique string (1–100 of A-Z a-z 0-9 _ . : -). Retrying with the same key within 24 hours returns the first response (header Idempotent-Replayed: true) instead of doing the work twice. Reusing a key for a different body is an error.

Request body

FieldTypeDescription
name * string
code * string
branch_id * string
department string | null

Created if it does not exist.

designation string | null

Created if it does not exist.

phone string | null
email email | null
joining_date date | null

Attendance is tracked from this day.

status string
activeinactive
device_user_ids string[]

Response 201

FieldTypeDescription
success * boolean
message string
data * object
id * string
code * string

The organization's own employee code (unique

name * string
phone * string | null
email * email | null
branch * object | null
id * string
name * string
department * string | null
designation * string | null
joining_date * date | null
status * string
activeinactive
device_user_ids * string[]

User IDs (PINs) this employee has on the organization's devices.

created_at * date-time
updated_at * date-time

Example request

curl -X POST "https://www.adms.arcloud.bd/api/v1/employees" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: payroll-sync-2026-11-17-E1" \
  -H "Content-Type: application/json" \
  -d '{"name":"Rahim Uddin","code":"E1001","branch_id":"01jcz6f0a9b8c7d6e5f4g3h2j1","department":"Production","designation":"Operator","phone":"+8801711000000","email":"rahim@example.com","joining_date":"2026-01-15","status":"active","device_user_ids":["1001"]}'

Example response

{
    "success": true,
    "message": "Employee created.",
    "data": {
        "id": "01jcz8x4m2q7v9t3k5h6n8p0rs",
        "code": "E1001",
        "name": "Rahim Uddin",
        "phone": "+8801711000000",
        "email": "rahim@example.com",
        "branch": {
            "id": "01jcz6f0a9b8c7d6e5f4g3h2j1",
            "name": "Head Office"
        },
        "department": "Production",
        "designation": "Operator",
        "joining_date": "2026-01-15",
        "status": "active",
        "device_user_ids": [
            "1001"
        ],
        "created_at": "2026-11-01T10:15:00+06:00",
        "updated_at": "2026-11-10T09:02:11+06:00"
    }
}
GET /api/v1/employees/{employee} employees.read

Get an employee

Parameters

NameInTypeDescription
employee * path string

Employee ID.

Response 200

FieldTypeDescription
success * boolean
message string
data * object
id * string
code * string

The organization's own employee code (unique

name * string
phone * string | null
email * email | null
branch * object | null
id * string
name * string
department * string | null
designation * string | null
joining_date * date | null
status * string
activeinactive
device_user_ids * string[]

User IDs (PINs) this employee has on the organization's devices.

created_at * date-time
updated_at * date-time

Example request

curl "https://www.adms.arcloud.bd/api/v1/employees/01jcz8x4m2q7v9t3k5h6n8p0rs" \
  -H "Authorization: Bearer $TOKEN"

Example response

{
    "success": true,
    "message": "Employee created.",
    "data": {
        "id": "01jcz8x4m2q7v9t3k5h6n8p0rs",
        "code": "E1001",
        "name": "Rahim Uddin",
        "phone": "+8801711000000",
        "email": "rahim@example.com",
        "branch": {
            "id": "01jcz6f0a9b8c7d6e5f4g3h2j1",
            "name": "Head Office"
        },
        "department": "Production",
        "designation": "Operator",
        "joining_date": "2026-01-15",
        "status": "active",
        "device_user_ids": [
            "1001"
        ],
        "created_at": "2026-11-01T10:15:00+06:00",
        "updated_at": "2026-11-10T09:02:11+06:00"
    }
}
PATCH /api/v1/employees/{employee} employees.write

Update an employee

Send only the fields to change. device_user_ids, when sent, replaces the full list. Setting status to inactive stops attendance tracking; reactivating counts against the employee limit again.

Parameters

NameInTypeDescription
employee * path string

Employee ID.

Request body

FieldTypeDescription
name string
code string
branch_id string
department string | null
designation string | null
phone string | null
email email | null
joining_date date | null
status string
activeinactive
device_user_ids string[]

Replaces the whole list. Send [] to unlink every ID.

Response 200

FieldTypeDescription
success * boolean
message string
data * object
id * string
code * string

The organization's own employee code (unique

name * string
phone * string | null
email * email | null
branch * object | null
id * string
name * string
department * string | null
designation * string | null
joining_date * date | null
status * string
activeinactive
device_user_ids * string[]

User IDs (PINs) this employee has on the organization's devices.

created_at * date-time
updated_at * date-time

Example request

curl -X PATCH "https://www.adms.arcloud.bd/api/v1/employees/01jcz8x4m2q7v9t3k5h6n8p0rs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"inactive"}'

Example response

{
    "success": true,
    "message": "Employee created.",
    "data": {
        "id": "01jcz8x4m2q7v9t3k5h6n8p0rs",
        "code": "E1001",
        "name": "Rahim Uddin",
        "phone": "+8801711000000",
        "email": "rahim@example.com",
        "branch": {
            "id": "01jcz6f0a9b8c7d6e5f4g3h2j1",
            "name": "Head Office"
        },
        "department": "Production",
        "designation": "Operator",
        "joining_date": "2026-01-15",
        "status": "active",
        "device_user_ids": [
            "1001"
        ],
        "created_at": "2026-11-01T10:15:00+06:00",
        "updated_at": "2026-11-10T09:02:11+06:00"
    }
}

Devices

GET /api/v1/devices devices.read

List devices

Response 200

FieldTypeDescription
success * boolean
data * object[]
id * string
name * string
serial_number * string | null
connection * string

adms: the device talks to the cloud directly. collector: through a Windows Collector on the LAN.

admscollector
branch * object | null
id * string
name * string
status * string
unknownonlineofflinedisabled
model * string | null
firmware * string | null
last_seen_at * date-time | null
last_punch_at * date-time | null

Example request

curl "https://www.adms.arcloud.bd/api/v1/devices" \
  -H "Authorization: Bearer $TOKEN"

Example response

{
    "success": true,
    "data": [
        {
            "id": "01jcz7r5t1a2b3c4d5e6f7g8h9",
            "name": "Main gate",
            "serial_number": "CQUJ214560123",
            "connection": "adms",
            "branch": {
                "id": "01jcz6f0a9b8c7d6e5f4g3h2j1",
                "name": "Head Office"
            },
            "status": "online",
            "model": "K50-A",
            "firmware": "Ver 6.60 Apr 28 2017",
            "last_seen_at": "2026-11-17T08:20:05+06:00",
            "last_punch_at": "2026-11-17T08:01:44+06:00"
        }
    ]
}
GET /api/v1/devices/{device} devices.read

Get a device

Parameters

NameInTypeDescription
device * path string

Device ID.

Response 200

FieldTypeDescription
success * boolean
data * object
id * string
name * string
serial_number * string | null
connection * string

adms: the device talks to the cloud directly. collector: through a Windows Collector on the LAN.

admscollector
branch * object | null
id * string
name * string
status * string
unknownonlineofflinedisabled
model * string | null
firmware * string | null
last_seen_at * date-time | null
last_punch_at * date-time | null

Example request

curl "https://www.adms.arcloud.bd/api/v1/devices/01jcz7r5t1a2b3c4d5e6f7g8h9" \
  -H "Authorization: Bearer $TOKEN"

Example response

{
    "success": true,
    "data": {
        "id": "01jcz7r5t1a2b3c4d5e6f7g8h9",
        "name": "Main gate",
        "serial_number": "CQUJ214560123",
        "connection": "adms",
        "branch": {
            "id": "01jcz6f0a9b8c7d6e5f4g3h2j1",
            "name": "Head Office"
        },
        "status": "online",
        "model": "K50-A",
        "firmware": "Ver 6.60 Apr 28 2017",
        "last_seen_at": "2026-11-17T08:20:05+06:00",
        "last_punch_at": "2026-11-17T08:01:44+06:00"
    }
}
POST /api/v1/devices/{device}/sync devices.command

Ask a device to send its punches

Queues a command for the device (ADMS) or its Windows Collector. The device picks it up on its next contact, usually within a minute. Poll GET /api/v1/device-commands/{id} for the result. If a sync is already waiting, that command is returned instead of a new one.

Parameters

NameInTypeDescription
device * path string

Device ID.

Idempotency-Key header string

Any unique string (1–100 of A-Z a-z 0-9 _ . : -). Retrying with the same key within 24 hours returns the first response (header Idempotent-Replayed: true) instead of doing the work twice. Reusing a key for a different body is an error.

Response 202

FieldTypeDescription
success * boolean
message string
data * object
id * string
device_id * string | null
type * string
sync_attlogget_infoset_time
status * string

queued → delivered (the device fetched it) → succeeded or failed. Commands not picked up in time become expired.

queueddeliveredsucceededfailedexpiredcancelled
requested_at * date-time
completed_at * date-time | null
expires_at * date-time | null

Example request

curl -X POST "https://www.adms.arcloud.bd/api/v1/devices/01jcz7r5t1a2b3c4d5e6f7g8h9/sync" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: payroll-sync-2026-11-17-E1"

Example response

{
    "success": true,
    "message": "Sync requested.",
    "data": {
        "id": "01jd0a1b2c3d4e5f6g7h8j9k0m",
        "device_id": "01jcz7r5t1a2b3c4d5e6f7g8h9",
        "type": "sync_attlog",
        "status": "queued",
        "requested_at": "2026-11-17T08:21:00+06:00",
        "completed_at": null,
        "expires_at": "2026-11-17T09:21:00+06:00"
    }
}
GET /api/v1/device-commands/{command} devices.read

Get a command's status

Parameters

NameInTypeDescription
command * path string

Command ID returned by the sync request.

Response 200

FieldTypeDescription
success * boolean
message string
data * object
id * string
device_id * string | null
type * string
sync_attlogget_infoset_time
status * string

queued → delivered (the device fetched it) → succeeded or failed. Commands not picked up in time become expired.

queueddeliveredsucceededfailedexpiredcancelled
requested_at * date-time
completed_at * date-time | null
expires_at * date-time | null

Example request

curl "https://www.adms.arcloud.bd/api/v1/device-commands/01jd0a1b2c3d4e5f6g7h8j9k0m" \
  -H "Authorization: Bearer $TOKEN"

Example response

{
    "success": true,
    "message": "Sync requested.",
    "data": {
        "id": "01jd0a1b2c3d4e5f6g7h8j9k0m",
        "device_id": "01jcz7r5t1a2b3c4d5e6f7g8h9",
        "type": "sync_attlog",
        "status": "queued",
        "requested_at": "2026-11-17T08:21:00+06:00",
        "completed_at": null,
        "expires_at": "2026-11-17T09:21:00+06:00"
    }
}

Attendance

GET /api/v1/attendance attendance.read

Daily attendance

One row per employee per day, as calculated by the attendance engine (shifts, grace, overtime, weekends, holidays, leave and corrections applied). Days are recalculated when late punches arrive or HR corrects them; use updated_since to pick up changes. At most 62 days per request.

Parameters

NameInTypeDescription
from query date

First day (organization time zone). Default today.

to query date

Last day, inclusive. Default from.

employee_id query string

Only this employee.

branch_id query string

Only this branch.

status query string
presenthalf_dayabsentincompletein_progressweekendholidayleave
updated_since query date-time

Only rows calculated at or after this time (ISO 8601).

page query integer
default 1
per_page query integer
default 100

Rows per page, 1–200.

Response 200

FieldTypeDescription
success * boolean
data * object[]
employee * object
id * string | null
code * string | null
name * string | null
date * date
status * string

in_progress: checked in and the shift is still running. incomplete: only one punch and the day is over. half_day / absent: worked less than the shift's thresholds.

presenthalf_dayabsentincompletein_progressweekendholidayleave
day_type * string
workingweekendholiday
shift * object | null

The shift as it was when the day was calculated.

name string
type string
fixedflexible
start string
end string
check_in * date-time | null
check_out * date-time | null
worked_minutes * integer
break_minutes * integer
late_minutes * integer
early_out_minutes * integer
overtime_minutes * integer
is_late * boolean
flags * string[]

Notes from the engine, for example late, early_out, missing_in, missing_out, odd_punches, clock_drift, insufficient_hours, worked_on_off_day.

needs_review * boolean
corrected * boolean

HR changed this day by hand.

calculated_at * date-time | null
meta * object
pagination * object
page * integer
per_page * integer
total * integer
last_page * integer

Example request

curl "https://www.adms.arcloud.bd/api/v1/attendance" \
  -H "Authorization: Bearer $TOKEN"

Example response

{
    "success": true,
    "data": [
        {
            "employee": {
                "id": "01jcz8x4m2q7v9t3k5h6n8p0rs",
                "code": "E1001",
                "name": "Rahim Uddin"
            },
            "date": "2026-11-16",
            "status": "present",
            "day_type": "working",
            "shift": {
                "name": "General",
                "type": "fixed",
                "start": "09:00",
                "end": "18:00"
            },
            "check_in": "2026-11-16T09:07:12+06:00",
            "check_out": "2026-11-16T18:04:40+06:00",
            "worked_minutes": 477,
            "break_minutes": 60,
            "late_minutes": 0,
            "early_out_minutes": 0,
            "overtime_minutes": 0,
            "is_late": false,
            "flags": [],
            "needs_review": false,
            "corrected": false,
            "calculated_at": "2026-11-16T18:05:02+06:00"
        }
    ],
    "meta": {
        "pagination": {
            "page": 1,
            "per_page": 50,
            "total": 128,
            "last_page": 3
        }
    }
}
GET /api/v1/punches attendance.raw.read

Raw punches

Every punch exactly as devices sent it, oldest first, including punches from device user IDs not linked to any employee yet. At most 31 days per request. Uses cursor pagination: repeat the request with cursor set to meta.next_cursor until it is null.

Parameters

NameInTypeDescription
from query date

First day (organization time zone). Default today.

to query date

Last day, inclusive. Default from.

employee_id query string

Only this employee.

cursor query string

meta.next_cursor from the previous page.

per_page query integer
default 200

Punches per page, 1–200.

Response 200

FieldTypeDescription
success * boolean
data * object[]
punched_at * date-time
device_local_time * string | null

The time exactly as the device's clock reported it.

device_user_id * string
employee * object | null

null while the device user ID is not linked to an employee.

id * string
code * string
device_id * string | null
state * integer | null

Punch state key pressed on the device (0 check-in, 1 check-out, 2 break-out, 3 break-in, 4 OT-in, 5 OT-out).

verify_mode * integer | null

How the person was verified (device code: 1 fingerprint, 15 face, 4 card, 0 password…).

source * string
admscollectorapiimport
meta * object
next_cursor * string | null

Pass as cursor for the next page; null on the last page.

Example request

curl "https://www.adms.arcloud.bd/api/v1/punches" \
  -H "Authorization: Bearer $TOKEN"

Example response

{
    "success": true,
    "data": [
        {
            "punched_at": "2026-11-16T09:07:12+06:00",
            "device_local_time": "2026-11-16 09:07:12",
            "device_user_id": "1001",
            "employee": {
                "id": "01jcz8x4m2q7v9t3k5h6n8p0rs",
                "code": "E1001"
            },
            "device_id": "01jcz7r5t1a2b3c4d5e6f7g8h9",
            "state": 0,
            "verify_mode": 1,
            "source": "adms"
        }
    ],
    "meta": {
        "next_cursor": null
    }
}
GET /api/v1/leave leave.read

Leave applications

Applications that overlap the date range (at most 366 days).

Parameters

NameInTypeDescription
from query date

First day (organization time zone). Default today.

to query date

Last day, inclusive. Default from.

employee_id query string

Only this employee.

status query string
pendingapprovedrejectedcancelled
page query integer
default 1
per_page query integer
default 50

Items per page, 1–200.

Response 200

FieldTypeDescription
success * boolean
data * object[]
employee * object
id * string | null
code * string | null
name * string | null
type * object
code * string | null
name * string | null
paid * boolean | null
from * date
to * date
half_day * boolean
days * number
status * string
pendingapprovedrejectedcancelled
reason * string | null
decided_at * date-time | null
meta * object
pagination * object
page * integer
per_page * integer
total * integer
last_page * integer

Example request

curl "https://www.adms.arcloud.bd/api/v1/leave" \
  -H "Authorization: Bearer $TOKEN"

Example response

{
    "success": true,
    "data": [
        {
            "employee": {
                "id": "01jcz8x4m2q7v9t3k5h6n8p0rs",
                "code": "E1001",
                "name": "Rahim Uddin"
            },
            "type": {
                "code": "CL",
                "name": "Casual leave",
                "paid": true
            },
            "from": "2026-11-14",
            "to": "2026-11-15",
            "half_day": false,
            "days": 2,
            "status": "approved",
            "reason": "Family event",
            "decided_at": "2026-11-13T16:40:00+06:00"
        }
    ],
    "meta": {
        "pagination": {
            "page": 1,
            "per_page": 50,
            "total": 128,
            "last_page": 3
        }
    }
}

Reports

GET /api/v1/reports/monthly-summary reports.read

Monthly summary per employee

Parameters

NameInTypeDescription
month * query string
branch_id query string

Only this branch.

Response 200

FieldTypeDescription
success * boolean
data * object[]
code * string
name * string
department * string | null
present_days * number
half_days * number
absent_days * number
incomplete_days * number
leave_days * number
holidays * number
weekend_days * number
late_days * number
late_minutes * number
early_out_days * number
worked_hours * number
overtime_hours * number
meta * object
month * string

Example request

curl "https://www.adms.arcloud.bd/api/v1/reports/monthly-summary?month=2026-11" \
  -H "Authorization: Bearer $TOKEN"

Example response

{
    "success": true,
    "data": [
        {
            "code": "E1001",
            "name": "Rahim Uddin",
            "department": "Production",
            "present_days": 21,
            "half_days": 1,
            "absent_days": 0,
            "incomplete_days": 1,
            "leave_days": 2,
            "holidays": 1,
            "weekend_days": 4,
            "late_days": 3,
            "late_minutes": 41,
            "early_out_days": 0,
            "worked_hours": 182.5,
            "overtime_hours": 6
        }
    ],
    "meta": {
        "month": "2026-11"
    }
}

Webhooks

GET /api/v1/webhooks webhooks.manage

List your webhook endpoints

Endpoints this client created in this organization.

Response 200

FieldTypeDescription
success * boolean
data * object[]
id * string
url * string
description * string | null
events * string[]
status * string
activedisabled
disabled_reason * string | null
consecutive_failures * integer
last_success_at * date-time | null
last_failure_at * date-time | null
created_at * date-time

Example request

curl "https://www.adms.arcloud.bd/api/v1/webhooks" \
  -H "Authorization: Bearer $TOKEN"

Example response

{
    "success": true,
    "data": [
        {
            "id": "01jd3k4m6p8r0t2v4x6z8b0d2f",
            "url": "https://payroll.example.com/hooks/ar",
            "description": "Payroll sync",
            "events": [
                "attendance.processed",
                "employee.updated"
            ],
            "status": "active",
            "disabled_reason": null,
            "consecutive_failures": 0,
            "last_success_at": "2026-11-18T09:12:44+06:00",
            "last_failure_at": null,
            "created_at": "2026-11-18T09:00:00+06:00"
        }
    ]
}
POST /api/v1/webhooks webhooks.manage

Create a webhook endpoint

The URL must use https and resolve to a public address. Every event in events must be covered by one of the token's read scopes (attendance.raw_received needs attendance.raw.read, attendance.* needs attendance.read, employee.* needs employees.read, device.*, collector.* and sync.* need devices.read). The response contains the signing secret once. At most 5 endpoints per client and organization; the organization's plan must include webhooks.

Parameters

NameInTypeDescription
Idempotency-Key header string

Any unique string (1–100 of A-Z a-z 0-9 _ . : -). Retrying with the same key within 24 hours returns the first response (header Idempotent-Replayed: true) instead of doing the work twice. Reusing a key for a different body is an error.

Request body

FieldTypeDescription
url * string
events * string[]
description string | null

Response 201

FieldTypeDescription
success * boolean
message string
data * object
id * string
url * string
description * string | null
events * string[]
status * string
activedisabled
disabled_reason * string | null
consecutive_failures * integer
last_success_at * date-time | null
last_failure_at * date-time | null
created_at * date-time
secret * string

Signing secret. Shown only in this response.

Example request

curl -X POST "https://www.adms.arcloud.bd/api/v1/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: payroll-sync-2026-11-17-E1" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://payroll.example.com/hooks/ar","events":["attendance.processed","employee.updated"],"description":"Payroll sync"}'

Example response

{
    "success": true,
    "message": "Endpoint created. Store the secret now: it is not shown again.",
    "data": {
        "id": "01jd3k4m6p8r0t2v4x6z8b0d2f",
        "url": "https://payroll.example.com/hooks/ar",
        "description": "Payroll sync",
        "events": [
            "attendance.processed",
            "employee.updated"
        ],
        "status": "active",
        "disabled_reason": null,
        "consecutive_failures": 0,
        "last_success_at": "2026-11-18T09:12:44+06:00",
        "last_failure_at": null,
        "created_at": "2026-11-18T09:00:00+06:00",
        "secret": "whsec_3q9Lx…"
    }
}
GET /api/v1/webhooks/{webhook} webhooks.manage

Get a webhook endpoint

Parameters

NameInTypeDescription
webhook * path string

Webhook endpoint ID.

Response 200

FieldTypeDescription
success * boolean
message string
data * object
id * string
url * string
description * string | null
events * string[]
status * string
activedisabled
disabled_reason * string | null
consecutive_failures * integer
last_success_at * date-time | null
last_failure_at * date-time | null
created_at * date-time

Example request

curl "https://www.adms.arcloud.bd/api/v1/webhooks/01jd3k4m6p8r0t2v4x6z8b0d2f" \
  -H "Authorization: Bearer $TOKEN"

Example response

{
    "success": true,
    "message": "Endpoint updated.",
    "data": {
        "id": "01jd3k4m6p8r0t2v4x6z8b0d2f",
        "url": "https://payroll.example.com/hooks/ar",
        "description": "Payroll sync",
        "events": [
            "attendance.processed",
            "employee.updated"
        ],
        "status": "active",
        "disabled_reason": null,
        "consecutive_failures": 0,
        "last_success_at": "2026-11-18T09:12:44+06:00",
        "last_failure_at": null,
        "created_at": "2026-11-18T09:00:00+06:00"
    }
}
PATCH /api/v1/webhooks/{webhook} webhooks.manage

Update a webhook endpoint

Send only what changes. status: active switches an endpoint on again after it was switched off (by you, by the organization, or automatically after 30 failed attempts in a row).

Parameters

NameInTypeDescription
webhook * path string

Webhook endpoint ID.

Request body

FieldTypeDescription
url string
events string[]
description string | null
status string
activedisabled

Response 200

FieldTypeDescription
success * boolean
message string
data * object
id * string
url * string
description * string | null
events * string[]
status * string
activedisabled
disabled_reason * string | null
consecutive_failures * integer
last_success_at * date-time | null
last_failure_at * date-time | null
created_at * date-time

Example request

curl -X PATCH "https://www.adms.arcloud.bd/api/v1/webhooks/01jd3k4m6p8r0t2v4x6z8b0d2f" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"active"}'

Example response

{
    "success": true,
    "message": "Endpoint updated.",
    "data": {
        "id": "01jd3k4m6p8r0t2v4x6z8b0d2f",
        "url": "https://payroll.example.com/hooks/ar",
        "description": "Payroll sync",
        "events": [
            "attendance.processed",
            "employee.updated"
        ],
        "status": "active",
        "disabled_reason": null,
        "consecutive_failures": 0,
        "last_success_at": "2026-11-18T09:12:44+06:00",
        "last_failure_at": null,
        "created_at": "2026-11-18T09:00:00+06:00"
    }
}
DELETE /api/v1/webhooks/{webhook} webhooks.manage

Delete a webhook endpoint

Also deletes its delivery log.

Parameters

NameInTypeDescription
webhook * path string

Webhook endpoint ID.

Response 200

FieldTypeDescription
success * boolean
message string
data * null

Example request

curl -X DELETE "https://www.adms.arcloud.bd/api/v1/webhooks/01jd3k4m6p8r0t2v4x6z8b0d2f" \
  -H "Authorization: Bearer $TOKEN"

Example response

{
    "success": true,
    "message": "Endpoint deleted.",
    "data": null
}
POST /api/v1/webhooks/{webhook}/rotate-secret webhooks.manage

Create a new signing secret

Requests are signed with the new secret immediately; the old one stops working.

Parameters

NameInTypeDescription
webhook * path string

Webhook endpoint ID.

Response 200

FieldTypeDescription
success * boolean
message string
data * object
id * string
url * string
description * string | null
events * string[]
status * string
activedisabled
disabled_reason * string | null
consecutive_failures * integer
last_success_at * date-time | null
last_failure_at * date-time | null
created_at * date-time
secret * string

Signing secret. Shown only in this response.

Example request

curl -X POST "https://www.adms.arcloud.bd/api/v1/webhooks/01jd3k4m6p8r0t2v4x6z8b0d2f/rotate-secret" \
  -H "Authorization: Bearer $TOKEN"

Example response

{
    "success": true,
    "message": "Endpoint created. Store the secret now: it is not shown again.",
    "data": {
        "id": "01jd3k4m6p8r0t2v4x6z8b0d2f",
        "url": "https://payroll.example.com/hooks/ar",
        "description": "Payroll sync",
        "events": [
            "attendance.processed",
            "employee.updated"
        ],
        "status": "active",
        "disabled_reason": null,
        "consecutive_failures": 0,
        "last_success_at": "2026-11-18T09:12:44+06:00",
        "last_failure_at": null,
        "created_at": "2026-11-18T09:00:00+06:00",
        "secret": "whsec_3q9Lx…"
    }
}
POST /api/v1/webhooks/{webhook}/test webhooks.manage

Send a test event

Sends a webhook.test event to this endpoint only.

Parameters

NameInTypeDescription
webhook * path string

Webhook endpoint ID.

Response 202

FieldTypeDescription
success * boolean
message string
data * object
id * string
event * object
id * string | null

The event ID your receiver sees in X-AR-Event-Id.

type * string | null
status * string

pending with attempts > 0 means a retry is scheduled (next_attempt_at).

pendingsucceededfailed
attempts * integer
http_status * integer | null

Status your server answered with last time.

error * string | null
duration_ms * integer | null
created_at * date-time
delivered_at * date-time | null
next_attempt_at * date-time | null

Example request

curl -X POST "https://www.adms.arcloud.bd/api/v1/webhooks/01jd3k4m6p8r0t2v4x6z8b0d2f/test" \
  -H "Authorization: Bearer $TOKEN"

Example response

{
    "success": true,
    "message": "Test event queued.",
    "data": {
        "id": "01jd3m2n4p6r8t0v2x4z6b8d0f",
        "event": {
            "id": "01jd3m2a9b8c7d6e5f4g3h2j1k",
            "type": "attendance.processed"
        },
        "status": "succeeded",
        "attempts": 1,
        "http_status": 200,
        "error": null,
        "duration_ms": 184,
        "created_at": "2026-11-18T09:12:44+06:00",
        "delivered_at": "2026-11-18T09:12:44+06:00",
        "next_attempt_at": null
    }
}
GET /api/v1/webhooks/{webhook}/deliveries webhooks.manage

Delivery log

Newest first. Kept for 30 days.

Parameters

NameInTypeDescription
webhook * path string

Webhook endpoint ID.

status query string
pendingsucceededfailed
page query integer
default 1
per_page query integer
default 50

Items per page, 1–200.

Response 200

FieldTypeDescription
success * boolean
data * object[]
id * string
event * object
id * string | null

The event ID your receiver sees in X-AR-Event-Id.

type * string | null
status * string

pending with attempts > 0 means a retry is scheduled (next_attempt_at).

pendingsucceededfailed
attempts * integer
http_status * integer | null

Status your server answered with last time.

error * string | null
duration_ms * integer | null
created_at * date-time
delivered_at * date-time | null
next_attempt_at * date-time | null
meta * object
pagination * object
page * integer
per_page * integer
total * integer
last_page * integer

Example request

curl "https://www.adms.arcloud.bd/api/v1/webhooks/01jd3k4m6p8r0t2v4x6z8b0d2f/deliveries" \
  -H "Authorization: Bearer $TOKEN"

Example response

{
    "success": true,
    "data": [
        {
            "id": "01jd3m2n4p6r8t0v2x4z6b8d0f",
            "event": {
                "id": "01jd3m2a9b8c7d6e5f4g3h2j1k",
                "type": "attendance.processed"
            },
            "status": "succeeded",
            "attempts": 1,
            "http_status": 200,
            "error": null,
            "duration_ms": 184,
            "created_at": "2026-11-18T09:12:44+06:00",
            "delivered_at": "2026-11-18T09:12:44+06:00",
            "next_attempt_at": null
        }
    ],
    "meta": {
        "pagination": {
            "page": 1,
            "per_page": 50,
            "total": 128,
            "last_page": 3
        }
    }
}
POST /api/v1/webhooks/{webhook}/deliveries/{delivery}/resend webhooks.manage

Send a delivery again

Sends the same event (same id) again now, with a fresh retry schedule.

Parameters

NameInTypeDescription
webhook * path string

Webhook endpoint ID.

delivery * path string

Delivery ID from the delivery log.

Response 202

FieldTypeDescription
success * boolean
message string
data * object
id * string
event * object
id * string | null

The event ID your receiver sees in X-AR-Event-Id.

type * string | null
status * string

pending with attempts > 0 means a retry is scheduled (next_attempt_at).

pendingsucceededfailed
attempts * integer
http_status * integer | null

Status your server answered with last time.

error * string | null
duration_ms * integer | null
created_at * date-time
delivered_at * date-time | null
next_attempt_at * date-time | null

Example request

curl -X POST "https://www.adms.arcloud.bd/api/v1/webhooks/01jd3k4m6p8r0t2v4x6z8b0d2f/deliveries/01jd3m2n4p6r8t0v2x4z6b8d0f/resend" \
  -H "Authorization: Bearer $TOKEN"

Example response

{
    "success": true,
    "message": "Test event queued.",
    "data": {
        "id": "01jd3m2n4p6r8t0v2x4z6b8d0f",
        "event": {
            "id": "01jd3m2a9b8c7d6e5f4g3h2j1k",
            "type": "attendance.processed"
        },
        "status": "succeeded",
        "attempts": 1,
        "http_status": 200,
        "error": null,
        "duration_ms": 184,
        "created_at": "2026-11-18T09:12:44+06:00",
        "delivered_at": "2026-11-18T09:12:44+06:00",
        "next_attempt_at": null
    }
}