> ## Documentation Index > Fetch the complete documentation index at: https://docs.guardhousehq.com/llms.txt > Use this file to discover all available pages before exploring further. # List timesheet entries > Returns a paginated list of timesheet entries within the given date range, scoped to your API key's customers and sites. Requires an API key with `KeyType=timesheet`. ## OpenAPI ````yaml /api-reference/openapi.json get /api/external/timesheets openapi: 3.1.0 info: title: Guardhouse API version: 1.0.0 description: >- The Guardhouse API gives external systems programmatic access to incident reports, timesheets, staff, customers, sites, and webhook event subscriptions. All endpoints return a consistent envelope (`ApiResponse`, `ApiPagedResponse`, or `ApiPostPagedResponse`). Authentication is a two-step flow: exchange a long-lived **API key** for a short-lived **JWT bearer token**, then send the bearer on every subsequent request. contact: name: Guardhouse Support license: name: Proprietary servers: - url: https://gateway-api.guardhousehq.com description: AU production - url: https://gateway-api.guardhousehq.co.uk description: UK production security: - bearerAuth: [] subscriptionKey: [] tags: - name: Authentication description: >- Exchange a long-lived API key for a short-lived JWT bearer token. The token must be sent as `Authorization: Bearer ` on every subsequent request. - name: Incident Reports description: >- List, fetch, and export incident reports submitted against your customers and sites. Requires an API key with `KeyType=incidentreport`. - name: Timesheets description: List timesheet entries and fetch per-entry rate breakdowns. - name: Live Operations description: >- Retrieve live shift and employee operational data, including clock-in status, location, welfare checks, and license details. - name: Staff description: >- List, create, and update employees and their security licenses. Read endpoints (`GET /api/external/staffs`, `GET /api/external/staffs/{id}/licenses`) are accessible with any valid Public API key. Write endpoints (`POST`, `PATCH`, `GET /staffs/search`) require `KeyType=developer`. - name: Customers description: List customer records visible to your API key. - name: Sites description: List sites visible to your API key. - name: Webhooks description: >- Manage webhook subscribers and event subscriptions so Guardhouse can notify your systems when incident reports or timesheets change. Requires an API key with `KeyType=developer`. - name: Login Audit description: >- Read-only access to login activity (successful logins, failed logins, and reserved logout events) for your company. **Requires an API key issued with the `login-audits.read` entitlement scope** — keys without this special scope are rejected at the auth layer with `403 Forbidden`. Tokens minted from such a key carry `login-audits.read` in their `Scope` claim, which is what the endpoint checks. paths: /api/external/timesheets: get: tags: - Timesheets summary: List timesheet entries description: >- Returns a paginated list of timesheet entries within the given date range, scoped to your API key's customers and sites. Requires an API key with `KeyType=timesheet`. parameters: - name: startDate in: query required: true description: Inclusive start of the date filter (UTC). schema: type: string format: date-time - name: endDate in: query required: true description: Inclusive end of the date filter (UTC). schema: type: string format: date-time - name: customerId in: query description: >- Filter to a single customer. Omit to fall back to the customers your API key is scoped to. schema: type: integer format: int32 - name: siteIds in: query description: >- Comma-separated list of site IDs. Omit to fall back to the sites your API key is scoped to. schema: type: string - name: employeeId in: query description: Filter to a single employee. schema: type: integer format: int32 - name: searchText in: query description: >- Free-text filter across timesheet ID, subcontractor name, and abbreviation. schema: type: string - name: status in: query description: Filter by approval state. schema: type: string enum: - Approved - Rejected - Pending - name: referenceSiteName in: query description: Cursor anchor when paginating across results sorted by site name. schema: type: string - name: referenceStaffName in: query description: Cursor anchor when paginating across results sorted by staff name. schema: type: string - name: referenceStartDate in: query description: Cursor anchor when paginating across time-sorted results. schema: type: string format: date-time - $ref: '#/components/parameters/ReferenceIdParam' - $ref: '#/components/parameters/ReferenceNameParam' - name: limit in: query description: Maximum number of records to return. schema: type: integer format: int32 default: 20 - $ref: '#/components/parameters/DirectionParam' - name: filter in: query description: Optional filter expression. schema: type: string responses: '200': description: Paginated list of timesheet entries content: application/json: schema: $ref: '#/components/schemas/TimesheetEntryListEnvelope' '403': $ref: '#/components/responses/Forbidden' components: parameters: ReferenceIdParam: name: referenceId in: query description: >- Cursor anchor ID. Pass the last `incidentReportId` (or equivalent) you saw to fetch the next page. schema: type: integer format: int32 ReferenceNameParam: name: referenceName in: query description: Cursor anchor name when paginating across results sorted by name. schema: type: string DirectionParam: name: direction in: query description: >- Cursor pagination direction. Use `next` to page forward and `prev` to page back. schema: type: string enum: - next - prev default: next schemas: TimesheetEntryListEnvelope: allOf: - $ref: '#/components/schemas/ApiPostPagedResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/TimesheetEntry' ApiPostPagedResponse: allOf: - $ref: '#/components/schemas/ApiResponse' - type: object description: >- Envelope for the newer cursor-paginated endpoints (timesheets, staff, customers, sites). The cursor is encoded as a string in `nextPageParameter` / `prevPageParameter` and is intended to be POSTed back as the next request body — or appended to the query string verbatim. properties: nextPageParameter: type: string nullable: true prevPageParameter: type: string nullable: true TimesheetEntry: type: object description: >- Public-facing view of a timesheet entry. Nested arrays (`allowances`, `notes`, `staffSubmittedTimesheetTimes`, `scheduleNotes`) carry detail objects whose schema is best inspected from a sample response — they're typed as generic objects here. properties: timesheetId: type: integer format: int32 customerName: type: string customerApiId: type: integer format: int32 nullable: true siteName: type: string siteApiId: type: integer format: int32 nullable: true staffId: type: string description: Employee.Id as a string. staffName: type: string employeeId: type: string description: Employee.ExternalReferenceNumber. employeeReferenceNumber: type: string email: type: string format: email mobile: type: string subcontractorCompany: type: string entryType: type: string position: type: string service: type: string paygroup: type: string scheduledStartTime: type: string format: date-time nullable: true scheduledEndTime: type: string format: date-time nullable: true timeclockStartTime: type: string format: date-time nullable: true clockInCoordinates: type: object additionalProperties: true nullable: true timeclockBreakStartTime: type: string format: date-time nullable: true timeclockBreakEndTime: type: string format: date-time nullable: true timeclockEndTime: type: string format: date-time nullable: true clockOutCoordinates: type: object additionalProperties: true nullable: true staffSubmittedTimesheetTimes: type: array items: type: object additionalProperties: true payStartTime: type: string format: date-time payEndTime: type: string format: date-time payBreakTime: type: integer format: int32 nullable: true invoiceStartTime: type: string format: date-time invoiceEndTime: type: string format: date-time invoiceBreakTime: type: integer format: int32 nullable: true notes: type: array items: type: object additionalProperties: true allowances: type: array items: type: object additionalProperties: true status: type: string enum: - Approved - Rejected - Unapproved approvedBy: type: string approvedDateTime: type: string format: date-time nullable: true customerApprovalStatus: type: string customerApprover: type: string customerApprovedDateTime: type: string format: date-time nullable: true lock: type: boolean scheduleNotes: type: object additionalProperties: true nullable: true ApiResponse: type: object description: The standard envelope for every JSON endpoint. properties: status: $ref: '#/components/schemas/Status' data: description: Endpoint-specific payload. `null` when an error occurred. nullable: true count: type: integer format: int32 nullable: true message: type: string errors: type: array items: $ref: '#/components/schemas/Error' Status: type: object properties: code: type: integer format: int32 description: Numeric service result code. `0` indicates success. errorMessage: type: string description: Human-readable error message; empty on success. Error: type: object properties: code: type: integer format: int32 default: 100 message: type: string responses: Forbidden: description: >- The bearer token is missing the required policy or `KeyType` claim, or the resource is outside your API key's scope. content: application/json: schema: $ref: '#/components/schemas/ApiResponse' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT issued by `POST /api/external/token/request`. Send as `Authorization: Bearer `. subscriptionKey: type: apiKey in: header name: external-gh-apim-sub-key description: >- Guardhouse API Management subscription key. Required on every request. The same value is used by all API consumers within a region — contact Guardhouse Support for the subscription key. ````