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://mail.artoolshub.com/api/v1
Token URL
https://mail.artoolshub.com/api/oauth/token
Authorize URL
https://mail.artoolshub.com/oauth/authorize
Getting started
Software for one organization
An owner or admin of the organization opens Settings → API access and creates a client with the scopes it needs.
They copy the client ID and secret (the secret is shown once) into your software's server-side settings.
Your software gets a token with client_credentials and calls the API. How →
A product many organizations connect
Register your company in the developer portal and create an app with your redirect URIs and scopes.
Each customer's admin presses Connect in your product, signs in here, chooses their organization and allows access.
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.
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.
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.
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.
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.
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.
Scope
Allows
organization.read
Read the organization profile
branches.read
Read branches
employees.read
Read employees and their device user IDs
employees.write
Create and update employees
devices.read
Read devices and their status
devices.command
Ask devices to sync punches
attendance.read
Read daily attendance results
attendance.raw.read
Read raw punches from devices
leave.read
Read leave applications
reports.read
Read attendance reports
webhooks.manage
Create webhooks that send the events allowed by the read permissions
Program against error.code; messages may change. Every response carries an X-Request-Id header: quote it when you contact support.
Code
HTTP
Meaning
invalid_token
401
No token, an unknown token or a revoked one.
token_expired
401
The access token is older than 1 hour. Get a new one.
client_revoked
401
The organization deleted this API client.
app_disconnected
401
The organization disconnected your app. Ask them to connect it again.
insufficient_scope
403
The token lacks the scope this endpoint needs (see error.details.required_scope).
ip_not_allowed
403
The client has an IP allowlist and this request came from another address.
organization_unavailable
403
The organization is suspended or closed.
api_not_in_plan
403
The organization's plan does not include API access.
developer_suspended
403
Your developer account is suspended.
organization_read_only
403
The subscription expired: reading works, changes are refused.
plan_limit_reached
403
For example the employee limit of the organization's plan.
not_found
404
The resource does not exist or belongs to another organization.
employee_code_taken
409
Another employee already has this code.
device_user_id_taken
409
The device user ID belongs to another employee.
device_disabled
409
The device is disabled.
validation_failed
422
Field errors are in error.details (field → messages).
range_too_large
422
The date range is longer than this endpoint allows.
invalid_cursor
422
The cursor was changed or comes from another query. Start again without it.
invalid_idempotency_key
422
Idempotency-Key has characters that are not allowed or is too long.
idempotency_key_reused
422
The key was already used with a different request body.
webhooks_not_in_plan
403
The organization's plan does not include webhooks.
event_not_allowed
403
The token's scopes do not cover an event you asked for (see error.details).
endpoint_disabled
409
The webhook endpoint is switched off. PATCH it with status active first.
invalid_webhook_url
422
The URL is not https or does not resolve to a public address.
endpoint_limit_reached
422
At most 5 webhook endpoints per client and organization.
rate_limited
429
More than 120 requests in a minute from this client. Wait Retry-After seconds.
daily_quota_exceeded
429
The 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).
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.
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.
New punches arrived from a device (up to 100 per event)
device, punches[] (up to 100)
attendance.processed
A day of attendance was calculated or changed
attendance, previous_status
attendance.corrected
HR corrected a day (missing punch, status change)
correction, employee
employee.created
An employee was added
employee
employee.updated
An employee was changed, deactivated or got new device IDs
employee
device.online
A device came online
device, reason
device.offline
A device stopped responding
device, reason
collector.online
A Windows Collector came online
collector
collector.offline
A Windows Collector stopped sending heartbeats
collector
sync.completed
A requested device sync finished
command, device
sync.failed
A requested device sync failed
command, device
webhook.test
The “Send test event” button
message
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_receivedNew punches
Punches that were just stored, up to 100 per event, oldest first. The same punch is never sent twice.
Field
Type
Description
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…).
attendance.processedA 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.
Field
Type
Description
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.
Sent by the Send test event button or POST /api/v1/webhooks/{id}/test.
Field
Type
Description
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
Field
Type
Description
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
Field
Type
Description
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/organizationorganization.read
The organization
Response 200
Field
Type
Description
success*
boolean
data*
object
id*
string
The same ID as organization.id in developer-app token responses.
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
Name
In
Type
Description
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
Field
Type
Description
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
Field
Type
Description
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.
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
Name
In
Type
Description
employee*
path
string
Employee ID.
Request body
Field
Type
Description
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
Field
Type
Description
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.
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
Name
In
Type
Description
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
Field
Type
Description
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.
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
Name
In
Type
Description
from
query
date
First day (organization time zone). Default today.
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
Field
Type
Description
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.
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
Name
In
Type
Description
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
Field
Type
Description
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.
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
Name
In
Type
Description
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.
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).