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

action

string

required

Either clock_in or clock_out.

notes

string

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

jobCode

string

Optional job code (recorded on clock in).

taskCode

string

Optional task code (recorded on clock in).

breakMinutes

integer

default:"0"

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

clockInIp

string

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

clockInDevice

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"
  }'

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.

​Request body

​Behavior

​Response

​Examples

​Errors

Request body

Behavior

Response

Examples

Errors