--- title: "List timesheets" method: GET path: "/v1/timesheets" tags: ["Timesheets"] --- # List timesheets `GET /v1/timesheets` ## Request - Base URL: `https://gateway.remote.com` - URL: `https://gateway.remote.com/v1/timesheets` - Auth: one of: - OAuth 2 - Authorization code: `/auth/oauth2/authorize` - Token URL: `/auth/oauth2/token` scopes: `https://gateway.remote.com/company.manage` - OAuth 2 - Authorization code: `/auth/oauth2/authorize` - Token URL: `/auth/oauth2/token` scopes: `timesheet:read` - OAuth 2 - Authorization code: `/auth/oauth2/authorize` - Token URL: `/auth/oauth2/token` scopes: `all:read` - OAuth 2 - Authorization code: `/auth/oauth2/authorize` - Token URL: `/auth/oauth2/token` scopes: `all:write` - OAuth 2 - Client credentials - Token URL: `/auth/oauth2/token` scopes: `timesheet:read` - OAuth 2 - Client credentials - Token URL: `/auth/oauth2/token` scopes: `all:read` - OAuth 2 - Client credentials - Token URL: `/auth/oauth2/token` scopes: `all:write` - HTTP bearer Lists all timesheets. ## Authentication This endpoint accepts any one of the following token types: - **Company-scoped access token** (`OAuth2AuthorizationCode`) — obtained by a company manager through the Authorization Code flow or the Refresh Token flow. See [Authentication for partners](https://developer.remote.com/docs/authentication-for-partners). - **Company-scoped access token (assertion)** (`OAuth2CompanyManagerAssertion`) — obtained through the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant for a company manager. See [OAuth Assertion](https://developer.remote.com/docs/authorization-method-oauth-assertion). - **Customer API token** (`CustomerAPIToken`) — generated by the customer on their Integration Settings page, with the scopes they choose there. See [Authorization for customers](https://developer.remote.com/docs/authorization-for-customers). ## Scopes Any one of the scopes in a token type's row is enough. `all:read` and `all:write` work too. | Token type | Category | Read only Scope | Write only Scope (read access implicit) | |---|---|---|---| | Company-scoped access token | Manage timeoffs (`time_and_attendance`) | View timesheets (`timesheet:read`) | Manage timesheets (`timesheet:write`) | | Company-scoped access token (assertion) | Manage timeoffs (`time_and_attendance`) | View timesheets (`timesheet:read`) | Manage timesheets (`timesheet:write`) | | Customer API token | Manage timeoffs (`time_and_attendance`) | View timesheets (`timesheet:read`) | Manage timesheets (`timesheet:write`) | ## Query parameters - `status` 'open' | 'submitted' | 'approved' | 'in_calibration' | 'processed': The current status of a timesheet in its lifecycle. - `open`: The timesheet is a draft and only visible to the employee. It has not been submitted yet. - `submitted`: The employee has submitted the timesheet for review. It is awaiting approval. - `approved`: The timesheet has been approved and will be included in the next payroll run. - `in_calibration`: The timesheet was sent back to the employee for revision. The employee needs to correct and resubmit it. - `processed`: The timesheet has been processed as part of a payroll run. This is a terminal state. - `order` 'asc' | 'desc' - `sort_by` 'submitted_at' - `page` integer - `page_size` integer ## Response `200` Success - ListTimesheetsResponse: Response schema listing many timesheets - `data` object - `current_page` integer: The current page among all of the total_pages - `timesheets` Timesheet[] - `approval_required` boolean, required: Whether this timesheet requires explicit approval before it can be processed. When false, the timesheet may be auto-approved based on the company's configuration. - `break_hours` HoursAndMinutes, required: A duration expressed as hours and minutes. - `hours` integer: The number of whole hours. - `minutes` integer: The number of remaining minutes (0-59). - `country_code` string, required: Country code according to ISO 3166-1 3-digit alphabetic codes. - `employment_id` string, uuid, required: A unique identifier in UUID v4 format. - `end_date` string, date, required: UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format - `holiday_hours` HoursAndMinutes, required: A duration expressed as hours and minutes. - `hours` integer: The number of whole hours. - `minutes` integer: The number of remaining minutes (0-59). - `id` string, uuid, required: A unique identifier in UUID v4 format. - `night_hours` HoursAndMinutes, required: A duration expressed as hours and minutes. - `hours` integer: The number of whole hours. - `minutes` integer: The number of remaining minutes (0-59). - `notes` string, nullable, required: Optional notes added by the employee when submitting the timesheet. - `on_call_hours` HoursAndMinutes, required: A duration expressed as hours and minutes. - `hours` integer: The number of whole hours. - `minutes` integer: The number of remaining minutes (0-59). - `overtime_hours` HoursAndMinutes, required: A duration expressed as hours and minutes. - `hours` integer: The number of whole hours. - `minutes` integer: The number of remaining minutes (0-59). - `regular_hours` HoursAndMinutes, required: A duration expressed as hours and minutes. - `hours` integer: The number of whole hours. - `minutes` integer: The number of remaining minutes (0-59). - `start_date` string, date, required: UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format - `status` 'open' | 'submitted' | 'approved' | 'in_calibration' | 'processed', required: The current status of a timesheet in its lifecycle. - `open`: The timesheet is a draft and only visible to the employee. It has not been submitted yet. - `submitted`: The employee has submitted the timesheet for review. It is awaiting approval. - `approved`: The timesheet has been approved and will be included in the next payroll run. - `in_calibration`: The timesheet was sent back to the employee for revision. The employee needs to correct and resubmit it. - `processed`: The timesheet has been processed as part of a payroll run. This is a terminal state. - `submitted_at` string, datetime, nullable, required: The timestamp when the employee submitted this timesheet for approval. Null if the timesheet has not been submitted yet (status is `open`). - `time_trackings` TimeTracking[], required: The individual time tracking entries that make up this timesheet. - `clock_in` string, date-time, required: UTC date time in [ISO 8601][] format. [ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601 - `clock_out` string, date-time, required: UTC date time in [ISO 8601][] format. [ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601 - `has_holiday_hours` boolean, required: Whether this time tracking entry includes any hours worked on public holidays. - `has_night_hours` boolean, required: Whether this time tracking entry includes any hours worked during night hours. - `has_weekend_hours` boolean, required: Whether this time tracking entry includes any hours worked on weekends. - `holiday_hours` HoursAndMinutes, required: A duration expressed as hours and minutes. - `hours` integer: The number of whole hours. - `minutes` integer: The number of remaining minutes (0-59). - `night_hours` HoursAndMinutes, required: A duration expressed as hours and minutes. - `hours` integer: The number of whole hours. - `minutes` integer: The number of remaining minutes (0-59). - `notes` string, nullable, required: Optional free-text notes about this time tracking entry, such as project or task details. - `time_breakdown` TimeBreakdown, required: Detailed hours breakdown for a time tracking entry, split by time of day (day vs night) and then by type of day (regular, weekend, holiday). Useful for calculating overtime, night shift premiums, and holiday pay. - `day` TypeOfDayBreakdown, required: Hours breakdown by type of day (regular working day, weekend, or public holiday) for a specific time of day (day or night). - `holiday` HoursAndMinutes, required: A duration expressed as hours and minutes. - … - `regular` HoursAndMinutes, required: A duration expressed as hours and minutes. - … - `weekend` HoursAndMinutes, required: A duration expressed as hours and minutes. - … - `night` TypeOfDayBreakdown, required: Hours breakdown by type of day (regular working day, weekend, or public holiday) for a specific time of day (day or night). - `holiday` HoursAndMinutes, required: A duration expressed as hours and minutes. - … - `regular` HoursAndMinutes, required: A duration expressed as hours and minutes. - … - `weekend` HoursAndMinutes, required: A duration expressed as hours and minutes. - … - `timezone` string, required: [TZ identifier](https://www.iana.org/time-zones) - `total_hours` HoursAndMinutes, required: A duration expressed as hours and minutes. - `hours` integer: The number of whole hours. - `minutes` integer: The number of remaining minutes (0-59). - `type` 'regular_hours' | 'overtime' | 'on_call' | 'break' | 'unpaid_break' | 'time_off' | 'public_holiday', required: The category of time being tracked (e.g., regular hours, overtime, on-call, break time). - `weekend_hours` HoursAndMinutes, required: A duration expressed as hours and minutes. - `hours` integer: The number of whole hours. - `minutes` integer: The number of remaining minutes (0-59). - `timeoff_hours` HoursAndMinutes: A duration expressed as hours and minutes. - `hours` integer: The number of whole hours. - `minutes` integer: The number of remaining minutes (0-59). - `total_hours` HoursAndMinutes, required: A duration expressed as hours and minutes. - `hours` integer: The number of whole hours. - `minutes` integer: The number of remaining minutes (0-59). - `unpaid_break_hours` HoursAndMinutes, required: A duration expressed as hours and minutes. - `hours` integer: The number of whole hours. - `minutes` integer: The number of remaining minutes (0-59). - `weekend_hours` HoursAndMinutes, required: A duration expressed as hours and minutes. - `hours` integer: The number of whole hours. - `minutes` integer: The number of remaining minutes (0-59). - `total_count` integer: The total number of records in the result - `total_pages` integer: The total number of pages the user can go through ## Other responses - `401`: Unauthorized - `404`: Not Found - `422`: Unprocessable Entity --- [API](https://skmtc.dev/remote-com/apis/time-attendance.md) - [All operations](https://skmtc.dev/remote-com/apis/time-attendance/llms.txt) - [OpenAPI document](https://skmtc.dev/remote-com/apis/time-attendance/revisions/84de0ccef126?raw)