Time & Attendance API

Endpoints for clock in/out, breaks, time entries, and time-off requests.

Clock Status

Get the current clock status for the authenticated user.

GET/api/time-attendance/clockAuth: Session

Get current clock status.

Response (200):

json

{
  "isClockedIn": true,
  "currentEntry": {
    "id": "uuid",
    "clockIn": "2026-01-29T08:00:00Z",
    "clockOut": null
  },
  "activeBreak": null
}

Clock In/Out

Clock in or out for the authenticated user.

POST/api/time-attendance/clockAuth: Session

Clock in or out.

Request Body (Clock In):

json

{
  "action": "clock_in"
}

Request Body (Clock Out):

json

{
  "action": "clock_out"
}

Parameter	Type	Required	Description
`action`	string	Required	"clock_in" or "clock_out"

Response (200):

json

{
  "success": true,
  "entry": {
    "id": "uuid",
    "clockIn": "2026-01-29T08:00:00Z",
    "clockOut": null
  }
}

Start/End Break

Manage breaks during a shift.

POST/api/time-attendance/breakAuth: Session

Start or end a break.

Request Body (Start Break):

json

{
  "action": "start",
  "breakType": "lunch"
}

Request Body (End Break):

json

{
  "action": "end"
}

Parameter	Type	Required	Description
`action`	string	Required	"start" or "end"
`breakType`	string	Optional	Break type when starting: "break", "lunch", "meeting", "training"

Response (200):

json

{
  "success": true,
  "break": {
    "id": "uuid",
    "breakType": "lunch",
    "startTime": "2026-01-29T12:00:00Z",
    "endTime": null
  }
}

Time Entries

Get time entries for a date range.

GET/api/time-attendance/entriesAuth: Session

Get time entries (supervisors can view team).

Query Parameters:

Parameter	Type	Required	Description
`startDate`	string	Required	Start date (YYYY-MM-DD)
`endDate`	string	Required	End date (YYYY-MM-DD)
`employeeId`	string	Optional	Filter by employee (supervisors only)

Response (200):

json

{
  "entries": [
    {
      "id": "uuid",
      "employeeId": "uuid",
      "clockIn": "2026-01-29T08:00:00Z",
      "clockOut": "2026-01-29T17:00:00Z",
      "totalHours": 9,
      "breakMinutes": 60,
      "breaks": [
        {
          "id": "uuid",
          "breakType": "lunch",
          "startTime": "2026-01-29T12:00:00Z",
          "endTime": "2026-01-29T13:00:00Z",
          "durationMinutes": 60
        }
      ]
    }
  ],
  "summary": {
    "totalHours": 40,
    "totalBreakMinutes": 300
  }
}

Time-Off Requests

List Requests

GET/api/time-attendance/time-offAuth: Session

Get time-off requests.

Query Parameters:

Parameter	Type	Required	Description
`status`	string	Optional	Filter by status: "pending", "approved", "denied", "cancelled"
`employeeId`	string	Optional	Filter by employee (supervisors only)

Response (200):

json

{
  "requests": [
    {
      "id": "uuid",
      "employeeId": "uuid",
      "type": "vacation",
      "startDate": "2026-02-01",
      "endDate": "2026-02-03",
      "hours": 24,
      "status": "pending",
      "notes": "Family vacation",
      "createdAt": "2026-01-20T10:00:00Z"
    }
  ]
}

Create Request

POST/api/time-attendance/time-offAuth: Session

Submit a time-off request.

Request Body:

json

{
  "type": "vacation",
  "startDate": "2026-02-01",
  "endDate": "2026-02-03",
  "hours": 24,
  "notes": "Family vacation"
}

Parameter	Type	Required	Description
`type`	string	Required	"vacation", "sick", "personal", or "other"
`startDate`	string	Required	Start date (YYYY-MM-DD)
`endDate`	string	Required	End date (YYYY-MM-DD)
`hours`	number	Required	Total hours requested
`notes`	string	Optional	Optional notes

Response (201):

json

{
  "success": true,
  "request": {
    "id": "uuid",
    "type": "vacation",
    "startDate": "2026-02-01",
    "endDate": "2026-02-03",
    "hours": 24,
    "status": "pending"
  }
}

Approve/Deny Request

PATCH/api/time-attendance/time-off/:idAuth: Session

Approve, deny, or cancel a request.

Request Body:

json

{
  "action": "approve",
  "reviewerNotes": "Approved. Enjoy your vacation!"
}

Parameter	Type	Required	Description
`action`	string	Required	"approve", "deny", or "cancel"
`reviewerNotes`	string	Optional	Notes from reviewer

Response (200):

json

{
  "success": true,
  "request": {
    "id": "uuid",
    "status": "approved",
    "reviewerNotes": "Approved. Enjoy your vacation!",
    "reviewedAt": "2026-01-21T14:00:00Z"
  }
}