> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paypunch.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Timesheet

> GET /api/v1/employee/timesheet — retrieve the authenticated employee's time entries, totals, and clock status for a date range.

Retrieve the authenticated employee's timesheet — their time entries for a date
range, plus computed totals, current pay period, and clock status.

```http theme={null}
GET /api/v1/employee/timesheet
```

**Authentication:** requires an **employee** JWT (`Authorization: Bearer <token>`).
The employee is identified from the token's `userId` — there is no employee-id
path/query parameter.

## Query parameters

<ParamField query="startDate" type="string">
  ISO date string. Defaults to the **start of the current week** (Sunday,
  00:00:00) if omitted.
</ParamField>

<ParamField query="endDate" type="string">
  ISO date string. Defaults to the **end of the current week** (Saturday,
  23:59:59) if omitted.
</ParamField>

<ParamField query="payPeriodId" type="string">
  Optional. Filter entries to a single pay period.
</ParamField>

Returns `400` `Invalid date format` for unparseable dates, or `400` `Invalid
date range` if `startDate` is after `endDate`. Time entries are matched on
`clockIn` falling within the range.

## Response

<ResponseField name="data.employee" type="object">
  `id`, `firstName`, `lastName`, `employeeNumber`, `jobTitle`, `payRate`,
  `payType`.
</ResponseField>

<ResponseField name="data.company" type="object">
  The employee's company, including `payPeriodType` and the bookkeeper org's
  `overtimeThreshold`, `overtimeMultiplier`, and `timezone`.
</ResponseField>

<ResponseField name="data.timeEntries" type="array">
  Time entries within the range (newest first). Each entry includes its
  `payPeriod` summary (`id`, `startDate`, `endDate`, `status`, `locked`).
</ResponseField>

<ResponseField name="data.currentPayPeriod" type="object | null">
  The pay period covering "now" for this company, or `null` if none.
</ResponseField>

<ResponseField name="data.totals" type="object">
  `totalHours`, `regularHours`, `overtimeHours`, `pendingEntries` (count with
  status `PENDING`), `approvedEntries` (count where `approved` is true).
</ResponseField>

<ResponseField name="data.clockStatus" type="object">
  `isClockedIn` (boolean) and `openTimeEntry` (`{ id, clockIn }` or `null`).
</ResponseField>

<ResponseField name="data.dateRange" type="object">
  The resolved `startDate` and `endDate` used for the query.
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://app.paypunch.io/api/v1/employee/timesheet?startDate=2026-06-15&endDate=2026-06-21" \
    -H "Authorization: Bearer <employee-token>"
  ```

  ```json Response (200) theme={null}
  {
    "success": true,
    "data": {
      "employee": {
        "id": "e1f2...",
        "firstName": "John",
        "lastName": "Smith",
        "employeeNumber": "EMP-001",
        "jobTitle": "Carpenter",
        "payRate": 28.5,
        "payType": "HOURLY"
      },
      "company": {
        "id": "c9d8...",
        "name": "Builders R Us",
        "payPeriodType": "BI_WEEKLY",
        "bookkeeperOrg": { "overtimeThreshold": 40, "overtimeMultiplier": 1.5, "timezone": "America/New_York" }
      },
      "timeEntries": [
        {
          "id": "t1...",
          "clockIn": "2026-06-16T13:00:00.000Z",
          "clockOut": "2026-06-16T21:30:00.000Z",
          "totalHours": 8,
          "regularHours": 8,
          "overtimeHours": 0,
          "status": "APPROVED",
          "approved": true,
          "payPeriod": { "id": "pp_01...", "startDate": "2026-06-15T00:00:00.000Z", "endDate": "2026-06-28T00:00:00.000Z", "status": "OPEN", "locked": false }
        }
      ],
      "currentPayPeriod": { "id": "pp_01...", "startDate": "2026-06-15T00:00:00.000Z", "endDate": "2026-06-28T00:00:00.000Z", "status": "OPEN", "locked": false, "periodType": "BI_WEEKLY" },
      "totals": { "totalHours": 8, "regularHours": 8, "overtimeHours": 0, "pendingEntries": 0, "approvedEntries": 1 },
      "clockStatus": { "isClockedIn": false, "openTimeEntry": null },
      "dateRange": { "startDate": "2026-06-15T00:00:00.000Z", "endDate": "2026-06-21T23:59:59.999Z" }
    }
  }
  ```
</CodeGroup>

Returns `401` if the token is missing/invalid, `404` `Employee not found` if the
token's user no longer exists.