Timesheet Totals

Retrieve detailed work records for payroll processing. This endpoint provides total hours, pay rules, and daily breakdowns for integration with external payroll systems.

📘
Related
When a timesheet is submitted, unsubmitted, approved, reopened, or a day is locked, the Time activity webhook fires user_timesheet_* and admin_day_locked / admin_day_unlocked if those event types are subscribed. Use this GET to pull the hour totals after those events.

Endpoint

Method	Endpoint	Description
GET	/time-clock/v1/time-clocks/{timeClockId}/timesheet	Get timesheet totals

Overview

The timesheet endpoint is designed for payroll integration:

Returns total worked hours per user, per day
Breaks down hours by pay rules (regular, overtime, etc.)
Includes pay rates if configured
Accounts for automated unpaid breaks
Supports filtering by approval/submission/lock status

⚠️
Date Range Limit
The date range is limited to 45 days maximum.

Query Parameters

Parameter	Type	Required	Description
startDate	string	Yes	Start date (YYYY-MM-DD)
endDate	string	Yes	End date (YYYY-MM-DD, max 45 days from start)
userIds	array	No	Filter by specific user IDs
groupIds	array	No	Filter by cohort/group IDs
jobIds	array	No	Filter by job IDs
isApproved	boolean	No	Filter by approval status
isSubmitted	boolean	No	Filter by submission status
isLocked	boolean	No	Filter by lock status

Example Request

curl --request GET \
  --url 'https://api.connecteam.com/time-clock/v1/time-clocks/12345/timesheet?startDate=2024-01-01&endDate=2024-01-15&isApproved=true' \
  --header 'X-API-KEY: YOUR_API_KEY'

Response Structure

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "startDate": "2024-01-01",
    "endDate": "2024-01-15",
    "users": [
      {
        "userId": 9170357,
        "dailyRecords": [
          {
            "date": "2024-01-02",
            "dailyTotalHours": 8.5,
            "dailyTotalWorkHours": 8.0,
            "dailyTotalPaidBreakHours": 0.5,
            "dailyTotalUnpaidBreakHours": 0.5,
            "isApproved": true,
            "isSubmitted": true,
            "isLocked": false,
            "payItems": [
              {
                "hours": 8.0,
                "payRule": {
                  "id": "pay-rule-001",
                  "code": "REG",
                  "type": "regular"
                },
                "actualPayRate": 25.00,
                "totalPay": 200.00
              }
            ],
            "records": [
              {
                "timeActivityId": "shift-abc123",
                "start": {
                  "timestamp": 1704196800,
                  "timezone": "America/New_York",
                  "source": {
                    "type": "mobile"
                  }
                },
                "end": {
                  "timestamp": 1704229200,
                  "timezone": "America/New_York",
                  "source": {
                    "type": "mobile"
                  }
                },
                "basePayRate": 25.00,
                "resources": [
                  {
                    "resourceId": "job-123",
                    "subResourceId": null
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

Response Fields

User Summary

Field	Type	Description
userId	integer	User's unique identifier
dailyRecords	array	Array of daily breakdowns

Daily Record

Field	Type	Description
date	string	Date (YYYY-MM-DD)
dailyTotalHours	number	Total hours (decimal)
dailyTotalWorkHours	number	Work hours excluding breaks
dailyTotalPaidBreakHours	number	Paid break hours
dailyTotalUnpaidBreakHours	number	Unpaid break hours
isApproved	boolean	Timesheet approved status
isSubmitted	boolean	Timesheet submitted status
isLocked	boolean	Timesheet locked status
payItems	array	Aggregated pay by rule
records	array	Individual shift entries

Pay Item

Field	Type	Description
hours	number	Hours in this pay category
payRule	object	Pay rule details
actualPayRate	number	Applied pay rate
totalPay	number	Total pay for this item

Pay Rule

Field	Type	Description
id	string	Pay rule identifier
code	string	Pay rule code (e.g., "REG", "OT")
type	string	Pay rule type

Payroll Integration Example

async function exportPayrollData(timeClockId, startDate, endDate) {
  const response = await fetch(
    `https://api.connecteam.com/time-clock/v1/time-clocks/${timeClockId}/timesheet?` +
    `startDate=${startDate}&endDate=${endDate}&isApproved=true`,
    { headers: { 'X-API-KEY': 'YOUR_API_KEY' } }
  );

  const data = await response.json();
  
  // Transform for payroll system
  const payrollEntries = [];
  
  for (const user of data.data.users) {
    for (const day of user.dailyRecords) {
      for (const payItem of day.payItems) {
        payrollEntries.push({
          employeeId: user.userId,
          date: day.date,
          hoursWorked: payItem.hours,
          payRuleCode: payItem.payRule.code,
          hourlyRate: payItem.actualPayRate,
          grossPay: payItem.totalPay
        });
      }
    }
  }
  
  return payrollEntries;
}

// Export approved hours for pay period
const payrollData = await exportPayrollData(12345, '2024-01-01', '2024-01-15');
console.log(payrollData);

Filtering Examples

Get Only Approved Timesheets

curl --request GET \
  --url 'https://api.connecteam.com/time-clock/v1/time-clocks/12345/timesheet?startDate=2024-01-01&endDate=2024-01-15&isApproved=true' \
  --header 'X-API-KEY: YOUR_API_KEY'

Get Specific Users

curl --request GET \
  --url 'https://api.connecteam.com/time-clock/v1/time-clocks/12345/timesheet?startDate=2024-01-01&endDate=2024-01-15&userIds=9170357&userIds=9170358' \
  --header 'X-API-KEY: YOUR_API_KEY'

Get Specific Jobs

curl --request GET \
  --url 'https://api.connecteam.com/time-clock/v1/time-clocks/12345/timesheet?startDate=2024-01-01&endDate=2024-01-15&jobIds=job-123&jobIds=job-456' \
  --header 'X-API-KEY: YOUR_API_KEY'

Notes

📝
Important Considerations

Hours are in decimal format (8.5 = 8 hours 30 minutes)

Automated unpaid breaks are already deducted from total hours

For PTO and manual break details, use the Time Activities endpoint

Pay rates only appear if configured in account settings

Overnight shifts are included based on time clock settings

API Reference