Attendance API — Sessions, Breaks, and Corrections - Workforce Intelligence & Execution OS

The Attendance API tracks the complete lifecycle of an employee’s working day — from the initial check-in that starts a session, through any breaks taken during the day, to the final check-out. It also provides a structured correction workflow so that late entries or forgotten check-outs can be reviewed and approved by a manager.

All endpoints in this section are prefixed with /api/v1/attendance and require an Authorization: Bearer <token> header. Every timestamp in responses is UTC with a Z suffix.

Enum Reference

Work Mode

The work_mode field is required when checking in and controls how the session is classified.

Value	Description
`office`	Employee is working from the office premises.
`wfh`	Employee is working from home.

Attendance Session Status

Value	Description
`active`	Session is open; employee has checked in but not yet checked out.
`completed`	Session ended normally via check-out.
`incomplete`	Session ended without a check-out (e.g. system auto-close).
`corrected`	Session times were amended by a manager-approved correction.

Attendance Classification

Value	Description
`active`	Session is still open.
`full_day`	Employee worked the full required shift hours.
`half_day`	Employee worked approximately half a shift.
`short_leave`	Employee was present for a short period only.
`insufficient`	Below the minimum threshold for any classification.
`full_leave`	No attendance recorded for the day.
`leave`	Day covered by an approved leave request.

Break Type

Value	Description
`dinner`	Meal break.
`prayer`	Prayer break.
`other`	Any other break type.

POST /attendance/check-in

Start a new work session for the current day. Only one active session is allowed per user at a time; attempting a second check-in before checking out returns 409 Conflict. Auth: Any authenticated user.

Request Body

work_mode

string

required

How the employee is working today. Must be office or wfh.

Response Fields

Returns an AttendanceSessionRead object.

uuid

required

Unique session identifier.

user_id

uuid

required

UUID of the employee who owns this session.

user_full_name

string

Resolved display name of the employee.

check_in_at

datetime

required

UTC timestamp of check-in (ISO-8601 with Z).

check_out_at

datetime

null while session is active; populated on check-out.

work_mode

string

required

office or wfh.

session_status

string

required

Current session state: active, completed, incomplete, or corrected.

correction_requested

boolean

required

true if a correction request has been submitted for this session.

correction_reason

string

Reason text submitted with the correction request.

true if check-in occurred after the shift start grace period.

is_early_logout

boolean

required

true if the employee checked out before the expected shift end.

is_overtime

boolean

Flagged true when the session extends past the shift end.

is_corrected

boolean

required

true if a manager has applied a correction to this session.

attendance_classification

string

required

System-computed classification: active, full_day, half_day, short_leave, insufficient, full_leave, or leave.

worked_minutes

integer

Total net worked minutes (excluding break time).

late_minutes

integer

Minutes late relative to shift start.

early_checkout_minutes

integer

Minutes short of full shift.

checkout_after_shift_reason

string

Reason provided when checking out after the shift ends.

checkout_after_shift_note

string

Free-text note accompanying an after-shift checkout.

expected_shift_start_at

datetime

Scheduled shift start time for today.

expected_shift_end_at

datetime

Scheduled shift end time for today.

duration_minutes

integer

Computed wall-clock session length once checked out.

total_hours

float

Shorthand hours value for UI display.

total_break_minutes

integer

Sum of all break durations in this session.

dinner_break_minutes

integer

Minutes spent on dinner breaks.

prayer_break_minutes

integer

Minutes spent on prayer breaks.

other_break_minutes

integer

Minutes spent on miscellaneous breaks.

breaks

array

List of AttendanceBreakRead objects for this session.

active_break

object

The currently open break record, or null if no break is active.

created_at

datetime

required

Record creation timestamp.

updated_at

datetime

required

Last update timestamp.

Example

curl -X POST "https://api.example.com/api/v1/attendance/check-in" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "work_mode": "office"
  }'

POST /attendance/check-out

End the currently active session for the authenticated user. The request body is optional; supply it only when you need to provide a reason for overtime or an early departure. Auth: Any authenticated user.

Request Body (optional)

checkout_after_shift_reason

string

Reason for checking out after shift end. Common values: overtime, forgot_checkout.

checkout_after_shift_note

string

Free-text note accompanying an after-shift checkout reason.

early_checkout_reason

string

Reason for leaving before the expected shift end.

Response Fields

Returns the completed AttendanceSessionRead object with check_out_at populated and session_status set to completed.

Example

curl -X POST "https://api.example.com/api/v1/attendance/check-out" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "early_checkout_reason": "Medical appointment"
  }'

GET /attendance/active

Return the authenticated user’s currently active (open) attendance session, or null if no session is open. Auth: Any authenticated user.

Response Fields

Returns a single AttendanceSessionRead object, or null. See POST /attendance/check-in for the full field list.

Example

curl -X GET "https://api.example.com/api/v1/attendance/active" \
  -H "Authorization: Bearer <token>"

GET /attendance/me

Retrieve the authenticated employee’s personal attendance history, optionally filtered to a date range. Auth: Any authenticated user.

Query Parameters

date_from

date

Inclusive start date in YYYY-MM-DD format.

date_to

date

Inclusive end date in YYYY-MM-DD format.

Response Fields

Returns an array of AttendanceSessionRead objects. See POST /attendance/check-in for the full field list.

Example

curl -X GET "https://api.example.com/api/v1/attendance/me?date_from=2024-06-01&date_to=2024-06-30" \
  -H "Authorization: Bearer <token>"

GET /attendance/team

Retrieve attendance sessions for the authenticated user’s team. Managers see their direct reports; Admins and HR see the entire organisation. Auth: Any authenticated user. Results are RBAC-scoped.

Query Parameters

date_from

date

Inclusive start date in YYYY-MM-DD format.

date_to

date

Inclusive end date in YYYY-MM-DD format.

Response Fields

Returns an array of AttendanceSessionRead objects.

Example

curl -X GET "https://api.example.com/api/v1/attendance/team?date_from=2024-06-01&date_to=2024-06-30" \
  -H "Authorization: Bearer <token>"

POST /attendance/breaks/start

Begin a timed break within the current active session. Only one break may be active at a time; the session must not already have an open break. Auth: Any authenticated user with an active session.

Request Body

break_type

string

required

Category of break. One of: dinner, prayer, other.

note

string

Optional free-text note describing the break.

Response Fields

Returns an AttendanceBreakRead object.

uuid

required

Unique break identifier.

attendance_session_id

uuid

required

Parent session UUID.

break_type

string

required

dinner, prayer, or other.

started_at

datetime

required

UTC start timestamp.

ended_at

datetime

null while break is active; populated on end.

duration_minutes

integer

Computed duration once ended; null while active.

note

string

Free-text note supplied at start.

is_paid

boolean

required

Whether this break type is a paid break per company policy.

Example

curl -X POST "https://api.example.com/api/v1/attendance/breaks/start" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "break_type": "prayer",
    "note": "Dhuhr prayer"
  }'

POST /attendance/breaks/end

End the currently active break, computing and persisting the duration_minutes. Auth: Any authenticated user with an active break.

Request Body

No request body is required.

Response Fields

Returns the completed AttendanceBreakRead object with ended_at and duration_minutes populated.

Example

curl -X POST "https://api.example.com/api/v1/attendance/breaks/end" \
  -H "Authorization: Bearer <token>"

GET /attendance/breaks/current

Return the authenticated user’s currently active (open) break, or null if no break is in progress. Auth: Any authenticated user.

Response Fields

Returns a single AttendanceBreakRead object, or null. See POST /attendance/breaks/start for the full field list.

Example

curl -X GET "https://api.example.com/api/v1/attendance/breaks/current" \
  -H "Authorization: Bearer <token>"

GET /attendance/sessions//breaks

List all breaks recorded within a specific attendance session. Auth: Any authenticated user.

Path Parameters

session_id

uuid

required

UUID of the attendance session.

Response Fields

Returns an array of AttendanceBreakRead objects. See POST /attendance/breaks/start for the full field list.

Example

curl -X GET "https://api.example.com/api/v1/attendance/sessions/3fa85f64-5717-4562-b3fc-2c963f66afa6/breaks" \
  -H "Authorization: Bearer <token>"

PATCH /attendance//correction-request

Submit a correction request for a past session where check-in or check-out times need to be amended. The request enters a pending queue for manager review. Auth: Any authenticated user (own sessions). Managers and admins can initiate corrections for team sessions.

Path Parameters

session_id

uuid

required

UUID of the attendance session to correct.

Request Body

reason

string

required

Explanation of why the correction is needed.

requested_check_in_at

datetime

The desired corrected check-in time (ISO-8601 UTC).

requested_check_out_at

datetime

The desired corrected check-out time (ISO-8601 UTC).

Response Fields

Returns the updated AttendanceSessionRead with correction_requested set to true and correction_reason populated.

Submitting a correction request does not immediately change the session’s recorded times. Times are only updated after a manager approves the correction via PATCH /attendance/{session_id}/resolve-correction.

Example

curl -X PATCH "https://api.example.com/api/v1/attendance/3fa85f64-5717-4562-b3fc-2c963f66afa6/correction-request" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "VPN issue delayed system check-in. Arrived at 09:05.",
    "requested_check_in_at": "2024-06-15T09:05:00Z",
    "requested_check_out_at": "2024-06-15T18:00:00Z"
  }'

GET /attendance/corrections/pending

Return all attendance sessions with a pending correction request that the authenticated caller is authorised to review. Managers see their team’s pending corrections; Admins and HR see all. Auth: Any authenticated user. Results are RBAC-scoped.

Response Fields

Returns an array of AttendanceSessionRead objects where correction_requested is true and the correction has not yet been resolved.

Example

curl -X GET "https://api.example.com/api/v1/attendance/corrections/pending" \
  -H "Authorization: Bearer <token>"

PATCH /attendance//resolve-correction

Approve, reject, or request clarification on a pending attendance correction. The caller must be the session owner’s manager or an admin/HR operator. Auth: Manager (own team), Admin, or HR Operations.

Path Parameters

session_id

uuid

required

UUID of the attendance session with a pending correction.

Request Body

action

string

required

Resolution decision. One of: approve, reject, clarify.

check_in_at

datetime

Corrected check-in time to apply when action is approve.

check_out_at

datetime

Corrected check-out time to apply when action is approve.

manager_comment

string

Reviewer note. Recommended when rejecting or requesting clarification.

Response Fields

Returns the updated AttendanceSessionRead. If approved, is_corrected is true and session_status becomes corrected.

Example — Approve

curl -X PATCH "https://api.example.com/api/v1/attendance/3fa85f64-5717-4562-b3fc-2c963f66afa6/resolve-correction" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "approve",
    "check_in_at": "2024-06-15T09:05:00Z",
    "check_out_at": "2024-06-15T18:00:00Z",
    "manager_comment": "Verified via office CCTV logs."
  }'

Example — Reject

curl -X PATCH "https://api.example.com/api/v1/attendance/3fa85f64-5717-4562-b3fc-2c963f66afa6/resolve-correction" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "reject",
    "manager_comment": "Badge scan logs show original time is correct."
  }'

Standard Error Response

{
  "detail": "An active attendance session already exists for today."
}

Common HTTP status codes for this resource: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict.

Overview

Endpoints

Documentation Index

​Enum Reference

​Work Mode

​Attendance Session Status

​Attendance Classification

​Break Type

​POST /attendance/check-in

​Request Body

​Response Fields

​POST /attendance/check-out

​Request Body (optional)

​Response Fields

​GET /attendance/active

​Response Fields

​GET /attendance/me

​Query Parameters

​Response Fields

​GET /attendance/team

​Query Parameters

​Response Fields

​POST /attendance/breaks/start

​Request Body

​Response Fields

​POST /attendance/breaks/end

​Request Body

​Response Fields

​GET /attendance/breaks/current

​Response Fields

​GET /attendance/sessions//breaks

​Path Parameters

​Response Fields

​PATCH /attendance//correction-request

​Path Parameters

​Request Body

​Response Fields

​GET /attendance/corrections/pending

​Response Fields

​PATCH /attendance//resolve-correction

​Path Parameters

​Request Body

​Response Fields

​Standard Error Response

Build docs developers (and LLMs) love

Enum Reference

Work Mode

Attendance Session Status

Attendance Classification

Break Type

POST /attendance/check-in

Request Body

Response Fields

POST /attendance/check-out

Request Body (optional)

Response Fields

GET /attendance/active

Response Fields

GET /attendance/me

Query Parameters

Response Fields

GET /attendance/team

Query Parameters

Response Fields

POST /attendance/breaks/start

Request Body

Response Fields

POST /attendance/breaks/end

Request Body

Response Fields

GET /attendance/breaks/current

Response Fields

GET /attendance/sessions//breaks

Path Parameters

Response Fields

PATCH /attendance//correction-request

Path Parameters

Request Body

Response Fields

GET /attendance/corrections/pending

Response Fields

PATCH /attendance//resolve-correction

Path Parameters

Request Body

Response Fields

Standard Error Response