Endpoints

All paths are relative to /api/v1. Every endpoint requires a Sanctum token except /auth/login, /ping, and /up.

Auth

Method	Path	Role	Notes
POST	/auth/login	—	Issue token.
POST	/auth/logout	any	Revoke current token.
POST	/auth/logout-all	any	Revoke all tokens.
GET	/me	any	Authenticated user profile, roles, scopes.

Organizations & Units

Method	Path	Role
GET	/organizations	SystemAdmin, SuperAdmin
POST	/organizations	SystemAdmin
GET	/organizations/{id}	scoped
PATCH	/organizations/{id}	SystemAdmin, OrgAdmin
DELETE	/organizations/{id}	SystemAdmin
GET	/organizations/{id}/units	scoped
POST	/organizations/{id}/units	SystemAdmin, OrgAdmin
PATCH	/units/{id}	SystemAdmin, OrgAdmin, OrgUnitAdmin
POST	/units/{id}/geo	SystemAdmin, OrgAdmin

Employees

Method	Path	Role
GET	/employees	HR, ShiftManager (scoped)
POST	/employees	HR
GET	/employees/{id}	scoped
PATCH	/employees/{id}	HR
POST	/employees/{id}/deployments	HR
POST	/employees/{id}/transfer	HR
POST	/employees/{id}/deactivate	HR

Shifts & Roster

Method	Path	Role
GET	/shifts	scoped
POST	/shifts	OrgAdmin, OrgUnitAdmin
PATCH	/shifts/{id}	OrgAdmin, OrgUnitAdmin
GET	/roster?unit_id=&month=YYYY-MM	ShiftManager
POST	/roster	ShiftManager (bulk upsert)
PATCH	/roster/{assignmentId}	ShiftManager
POST	/roster/{assignmentId}/locum	ShiftManager

Attendance

Method	Path	Role
POST	/attendance/punch	Employee (self)
GET	/attendance	scoped
GET	/attendance/{id}	scoped
PATCH	/attendance/{id}	HR (pre-lock), SuperAdmin (post-lock)
POST	/attendance/{id}/recalculate	HR, SuperAdmin
GET	/attendance/{id}/flags	scoped
POST	/attendance/lock	HR
POST	/attendance/unlock	SuperAdmin

Punch request body

{
  "direction": "in",        // "in" | "out" | "auto"
  "punched_at": "2026-04-23T09:05:12Z",
  "organization_unit_id": 12,
  "lat": 17.4375,
  "lon": 78.4483,
  "accuracy_m": 12.5,
  "device_fingerprint": "abc123",
  "channel": "mobile"
}

Response after processing

{
  "accepted": true,
  "punch_id": 998877,
  "attendance_id": 3321,
  "status": "present",
  "flags": ["LATE_CHECK_IN"]
}

Leave

Method	Path	Role
GET	/leaves	scoped
POST	/leaves	Employee
POST	/leaves/{id}/decide	ShiftManager, HR, SuperAdmin

Regularization

Method	Path	Role
GET	/regularizations	scoped
POST	/regularizations	Employee
POST	/regularizations/{id}/decide	ShiftManager, HR, SuperAdmin

Devices

Method	Path	Role
GET	/devices	HR, Employee (own)
POST	/devices/register	Employee
POST	/devices/{id}/approve	HR
POST	/devices/{id}/revoke	HR

Reports & Exports

Method	Path	Role
POST	/reports/attendance	HR, OrgAdmin
POST	/exports	HR, OrgAdmin
GET	/exports/{id}	requester
GET	/exports/{id}/download	requester

Webhooks / Integrations

Method	Path	Notes
POST	/telegram/webhook	Telegram callback.
POST	/integrations/payroll/daily	Push locked attendance to payroll partner.
GET	/integrations/payroll/pull?month=YYYY-MM&org_id=N	Pull for polling partners.