---
updatedAt: 2026-01-28T14:51:25.000Z
---

Fetch the complete documentation index at: https://developer.connecteam.com/llms.txt. Use this file to discover all available pages before exploring further.

# 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.

## 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

```bash
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

```json
{
  "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

```javascript
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

```bash
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

```bash
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

```bash
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](time-clock-time-activities) endpoint
> * Pay rates only appear if configured in account settings
> * Overnight shifts are included based on time clock settings

***

[API Reference](https://developer.connecteam.com/reference/)