Clock In / Clock Out

A single endpoint that both clocks in (creates a new open time entry) and clocks out (completes the open entry and computes hours), selected by the action field.

POST /api/v1/employee/timesheet/entry

Authentication: requires an employee JWT. The employee is taken from the token’s userId.

Request body

string

required

Either clock_in or clock_out.

string

Free-text note. On clock out, if omitted the existing entry’s notes are kept.

string

Optional job code (recorded on clock in).

string

Optional task code (recorded on clock in).

integer

default:"0"

Unpaid break minutes deducted from total hours on clock out. Minimum 0.

string

Optional client IP to record. Used for both the clock-in and clock-out IP fields.

string

Optional device identifier to record.

Behavior

clock_in
clock_out

Creates a new time entry with status: "PENDING" and clockIn set to now. It is associated with the company’s current unlocked pay period (if one exists). If the employee already has an open entry, returns 400 Already clocked in (with the existing entry’s id and clockIn).

Finds the open entry (no clockOut) and completes it: sets clockOut to now, applies breakMinutes, and computes totalHours, regularHours, and overtimeHours using the org’s overtimeThreshold against the employee’s weekly hours. If there is no open entry, returns 400 No open time entry.

Response

Both actions return 200 with data.timeEntry (including its payPeriod summary) and a data.message. Clock out additionally returns data.summary with totalHours, regularHours, overtimeHours, and breakMinutes.

Examples

curl -X POST https://app.paypunch.io/api/v1/employee/timesheet/entry \
  -H "Authorization: Bearer <employee-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "clock_in",
    "jobCode": "JOB-204",
    "notes": "Site A framing"
  }'

curl -X POST https://app.paypunch.io/api/v1/employee/timesheet/entry \
  -H "Authorization: Bearer <employee-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "clock_out",
    "breakMinutes": 30
  }'

{
  "success": true,
  "data": {
    "timeEntry": {
      "id": "t9...",
      "employeeId": "e1f2...",
      "companyId": "c9d8...",
      "payPeriodId": "pp_01...",
      "clockIn": "2026-06-17T13:00:00.000Z",
      "clockOut": null,
      "jobCode": "JOB-204",
      "status": "PENDING",
      "payPeriod": { "id": "pp_01...", "startDate": "2026-06-15T00:00:00.000Z", "endDate": "2026-06-28T00:00:00.000Z", "status": "OPEN" }
    },
    "message": "Clocked in successfully"
  }
}

{
  "success": true,
  "data": {
    "timeEntry": {
      "id": "t9...",
      "clockIn": "2026-06-17T13:00:00.000Z",
      "clockOut": "2026-06-17T21:30:00.000Z",
      "breakMinutes": 30,
      "totalHours": 8,
      "regularHours": 8,
      "overtimeHours": 0,
      "payPeriod": { "id": "pp_01...", "status": "OPEN" }
    },
    "message": "Clocked out successfully",
    "summary": { "totalHours": 8, "regularHours": 8, "overtimeHours": 0, "breakMinutes": 30 }
  }
}

Errors

Status	`error`	Cause
`400`	`Already clocked in`	`clock_in` while an open entry exists.
`400`	`No open time entry`	`clock_out` with nothing to close.
`400`	`Invalid action` / `Invalid time entry data`	`action` not `clock_in`/`clock_out`, or body validation failed.
`401`	`Authentication required`	Missing/invalid employee token.
`404`	`Employee not found or inactive`	Token user missing or deactivated.
`500`	`Failed to create time entry`	Unexpected server error.

Overview

Admin API

Employee API

Clock In / Clock Out

Request body

Behavior

Response

Examples

Errors

​Request body

​Behavior

​Response

​Examples

​Errors

Request body

Behavior

Response

Examples

Errors