--- updatedAt: 2026-06-24T13:25:22.000Z --- Fetch the complete documentation index at: https://developer.connecteam.com/llms.txt. Use this file to discover all available pages before exploring further. # Overview The Time Clock API provides comprehensive workforce time tracking capabilities. Manage employee clock-ins, clock-outs, time activities, geofences, and retrieve timesheet data for payroll processing. ## Key Concepts ### Time Clocks Time clocks are the core organizational unit. Each time clock can have its own settings, jobs, geofences, and assigned users. An account can have multiple time clocks for different departments or locations. ### Breadcrumbs GPS location events collected while an employee is clocked into a shift. Exported via the async Breadcrumbs Report API for compliance and route auditing. ### Time Activities Time activities represent work records and include: * **Shifts**: Regular work periods tracked by clock-in/clock-out * **Manual Breaks**: Scheduled break periods (paid or unpaid) * **Time Offs**: Approved PTO that appears on timesheets ### Punch Source Types Each clock event tracks its source: | Source | Description | | :------------- | :----------------------- | | `mobile` | Clocked via mobile app | | `pc` | Clocked via desktop | | `kiosk` | Clocked via shared kiosk | | `nfc` | Clocked via NFC tag | | `api` | Clocked via API | | `admin` | Manually added by admin | | `autoClockOut` | System auto clock-out | ### Auto Clock-Out Modes When auto clock-out occurs, the reason is tracked: | Mode | Description | | :---------------------- | :------------------------- | | `dailyLimit` | Daily hour limit reached | | `hourLimit` | Shift hour limit reached | | `schedulerShiftEnded` | Scheduled shift ended | | `geofenceExit` | User exited geofenced area | | `disabledGps` | GPS was disabled | | `disabledGpsPermission` | GPS permission revoked | *** ## Available Endpoints ### Time Clocks | Method | Endpoint | Description | | :----- | :------------------------- | :------------------ | | GET | /time-clock/v1/time-clocks | Get all time clocks | ### Time Activities | Method | Endpoint | Description | | :----- | :------------------------------------------------------------------------ | :--------------------- | | GET | /time-clock/v1/time-clocks/{timeClockId}/time-activities | Get time activities | | POST | /time-clock/v1/time-clocks/{timeClockId}/time-activities | Create time activities | | PUT | /time-clock/v1/time-clocks/{timeClockId}/time-activities | Update time activities | | DELETE | /time-clock/v1/time-clocks/{timeClockId}/time-activities/{timeActivityId} | Delete a time activity | ### Real-Time Clocking | Method | Endpoint | Description | | :----- | :------------------------------------------------- | :-------------------------------------------------- | | POST | /time-clock/v1/time-clocks/{timeClockId}/clock-in | Clock in a user (optional retroactive `timestamp`) | | POST | /time-clock/v1/time-clocks/{timeClockId}/clock-out | Clock out a user (optional retroactive `timestamp`) | ### Manual Break Clocking | Method | Endpoint | Description | | :----- | :------------------------------------------------------------------------------ | :------------------------------------------------------ | | POST | /time-clock/v1/time-clocks/{timeClockId}/manual-breaks/{manualBreakId}/clock-in | Start a manual break (auto-closes an open shift) | | POST | /time-clock/v1/time-clocks/{timeClockId}/manual-breaks/clock-out | End the open manual break (optionally resume the shift) | ### Breadcrumbs | Method | Endpoint | Description | | :----- | :-------------------------------------------------- | :---------------------------------- | | POST | /time-clock/breadcrumbs/v1/report | Start breadcrumbs report for a date | | GET | /time-clock/breadcrumbs/v1/report/{fileId} | Get report task status | | GET | /time-clock/breadcrumbs/v1/report/{fileId}/download | Download completed JSON report | ### Geofences | Method | Endpoint | Description | | :----- | :----------------------------------------------------------- | :---------------- | | GET | /time-clock/v1/time-clocks/{timeClockId}/geofences | Get all geofences | | POST | /time-clock/v1/time-clocks/{timeClockId}/geofences | Create geofences | | GET | /time-clock/v1/time-clocks/{timeClockId}/geofences/{fenceId} | Get a geofence | | DELETE | /time-clock/v1/time-clocks/{timeClockId}/geofences/{fenceId} | Delete a geofence | ### Timesheet & Payroll | Method | Endpoint | Description | | :----- | :------------------------------------------------- | :------------------- | | GET | /time-clock/v1/time-clocks/{timeClockId}/timesheet | Get timesheet totals | ### Supporting Data | Method | Endpoint | Description | | :----- | :--------------------------------------------------------- | :---------------------------- | | GET | /time-clock/v1/time-clocks/{timeClockId}/shift-attachments | Get shift attachment settings | | GET | /time-clock/v1/time-clocks/{timeClockId}/manual-breaks | Get manual break settings | *** ## Constraints | Constraint | Value | | :----------------------------------------- | :------------------------------------------------ | | Max users per time activities request | 100 | | Max shifts per user (create/update) | 50 | | Max manual breaks per user (create/update) | 50 | | Max geofences per create request | 1000 | | Max jobs per geofence | 100 | | Geofence radius | 75-1524 meters | | Time activities date range | 92 days (3 months) | | Timesheet date range | 45 days | | Timestamps | Unix epoch (seconds) | | Retroactive clock-in/out | Up to 12 hours in the past (optional `timestamp`) | | Date format | YYYY-MM-DD | *** ## Authentication All endpoints require authentication via API key or OAuth 2.0. ### Required Scopes | Scope | Operations | | :----------------- | :--------------------------------------------------------------- | | time\_clock.read | GET time clocks, time activities, geofences, timesheet, settings | | time\_clock.write | POST/PUT time activities, clock-in, clock-out, create geofences | | time\_clock.delete | DELETE geofences, time activities | *** ## Validation Rules > ⚠️ Important Validations > > * Users must be **assigned to the time clock** before any operations > * Jobs must be **assigned to the time clock** if job tracking is required > * Cannot create/update time activities on **locked or approved days** > * **Start time must be before end time** for all activities > * **Retroactive punches:** optional `timestamp` on clock-in/out — max 12 hours in the past, not in the future *** ## Guide Pages | Page | Description | | :-------------------------------------------------------- | :------------------------------------------------------------------ | | [Getting Time Clocks](time-clock-getting-time-clocks) | Retrieve available time clocks | | [Time Activities](time-clock-time-activities) | Query, create, update, and delete time records | | [Real-Time Clocking](time-clock-real-time-clocking) | Clock in and clock out users, including offline retroactive punches | | [Manual Break Clocking](time-clock-manual-break-clocking) | Start and end live manual breaks, with automatic shift transitions | | [Breadcrumbs](time-clock-breadcrumbs) | Export GPS breadcrumb trails for shifts (async report) | | [Geofences](time-clock-geofences) | Manage location-based restrictions | | [Timesheet Totals](time-clock-timesheet) | Get payroll-ready hour summaries | | [Settings & Configuration](time-clock-settings) | Retrieve shift attachments and manual breaks | *** [API Reference](https://developer.connecteam.com/reference/)