Time Clock: Manual Break Clock In/Out API

You can now start and end live manual breaks for employees over the API, mirroring the Connecteam mobile app's one-tap "take a break" and "return to job" experience. Physical clock devices and self-service kiosks can finally record breaks in the live punch lifecycle instead of writing completed historical records.

New Endpoints

• POST /time-clock/v1/time-clocks/{timeClockId}/manual-breaks/{manualBreakId}/clock-in — Start a manual break
• POST /time-clock/v1/time-clocks/{timeClockId}/manual-breaks/clock-out — End the open manual break

Key Features

• Automatic shift → break transition: if the employee is on a shift, starting a break closes the shift and opens the break in a single call (attributed to the shift's job). The response returns isSwitchFromShift and the closedShift.
• Return to job on end: by default, ending a break that came from a shift re-opens that shift on the same job. Opt out with isResumeShift: false to leave the employee idle. The response returns the actual isResumeShift outcome and the resumedShift.
• Mandatory breaks honored: breaks configured as mandatory cannot be ended before their minimum duration elapses (with a 45-second grace window).
• Offline sync: both endpoints accept an optional retroactive timestamp (Unix seconds, up to 12 hours in the past), matching the shift clock-in/out behavior.

Authentication

• API Key (X-API-KEY header), or
• OAuth 2.0 with scope time_clock.write

Use Cases

• Integrated kiosks: one tap to take a break while on shift, one tap to return — no error-prone two-step clock-out + break-start orchestration.
• Physical clock devices: record breaks that keep the device's state machine in sync with the employee's real status.
• Offline-capable terminals: flush queued break punches with their original timestamps on reconnect.

For full details and examples, see the Manual Break Clocking guide and the Clock In / Clock Out API references.