Skip to content

API — Attendance

Purpose

Attendance records and viewing, the admin edit/import/review surfaces, and reconciliation (variance between planned and actual).

Auth & roles

Area Base Gate
Attendance (view) /api/attendance, /api/me/attendance attendance.view.all / .scoped / .own
Edit /api/admin/attendance/{id} attendance.edit
Import /api/admin/attendance/import attendance.import
Review /api/admin/attendance/pending-reviews attendance.review
Reconciliation /api/admin/reconciliation reconciliation.view / reconciliation.validate

See the RBAC matrix — note HR_DIRECTOR/COO hold the attendance import/edit/review scope.

Endpoints

View — /api/attendance (+ /api/me/attendance)

Method Path Purpose Gate
GET /api/attendance/all All records attendance.view.all
GET /api/attendance/scoped Scoped records attendance.view.scoped
GET /api/attendance/{id} · /{id}/audit Record + its audit trail attendance.view.all
GET /api/me/attendance Own attendance attendance.view.own

Edit / import / review — /api/admin/attendance

Method Path Purpose Gate
PUT /api/admin/attendance/{id} Admin-edit a record attendance.edit
POST /api/admin/attendance/import/preview · /commit Excel import (preview → commit) attendance.import
GET /api/admin/attendance/template Import template attendance.import
GET /api/admin/attendance/pending-reviews (+ /count) Review queue attendance.review
POST /api/admin/attendance/pending-reviews/{id}/acknowledge · /revert Acknowledge / revert an edit attendance.review

Reconciliation — /api/admin/reconciliation

Method Path Purpose Gate
GET /api/admin/reconciliation/exceptions (+ /pending-count) Exception queue reconciliation.view
POST /api/admin/reconciliation/exceptions/validate Validate an exception reconciliation.validate
GET /api/admin/reconciliation/variance Variance report data reconciliation.view

Shapes & errors

Attendance is Excel-sourced — preview/commit import, admin-edit with manager-revert, and reconciliation tables (sheet 13). Standard ProblemDetails.

Gotchas

  • No device/punch feed. Times come from Excel import, not turnstiles or biometric devices (sheet 13). Don't document a real-time punch integration.
  • Cross-midnight Time_Out is rejected (Phase-3 finding C2) — a shift ending after midnight needs handling outside the simple import path.
  • Edits are reviewable — an admin edit creates a pending review a manager can revert; the …/{id}/audit trail records the change.