Timesheets

Authentication: All endpoints require an Authorization: Bearer <access token> header.

Most endpoints require an X-Company-ID: <company_id> header to scope requests to a specific company. This is the recommended header for most API operations.

Some endpoints require an X-Location-ID: <location_id> header when the query doesn't accept a locationId parameter.

See Authentication for details on how to obtain and use these headers.

Query Timesheets

Retrieve timesheets for a specific location within a date range. Timesheets represent actual time worked by employees, including clock-in/out times, breaks, and approval status.

Query Parameters:

Parameter	Type	Required	Description
`startTime`	`DateTime!`	Yes	Start of the date range (inclusive)
`endTime`	`DateTime!`	Yes	End of the date range (inclusive)
`locationId`	`ID!`	Yes	ID of the location to query

Response Fields:

Field	Description
`id`	Unique identifier for the timesheet
`startTime`	Start date/time of the timesheet
`endTime`	End date/time of the timesheet
`status`	Timesheet status (e.g., "approved", "completed", "payrolled", "committed")
`hours`	Total hours worked (excluding unpaid breaks)
`cost`	Cost of the timesheet based on employee's pay rate (optional)
`variance`	Variance between scheduled and actual hours (optional)
`workType`	Work type applied to this timesheet (if applicable)
`workType.id`	Unique identifier for the work type
`workType.name`	Name of the work type (e.g., "Min Break", "Overtime")
`workType.appliedFromId`	ID of the rule or template applied from
`breaks`	Array of break periods
`breaks[].id`	Unique identifier for the break
`breaks[].startTime`	Start time of the break
`breaks[].endTime`	End time of the break
`breaks[].subtracts`	Whether the break is subtracted from paid hours
`employee.id`	ID of the employee
`employee.fullName`	Full name of the employee
`position.id`	ID of the position worked
`position.text`	Name/description of the position
`location.id`	ID of the location
`location.name`	Name of the location
`location.timezone`	IANA timezone identifier for the location

For the complete Timesheet type reference and all available fields, see the GraphQL Schema Reference.

Implementation Notes:

The locationId parameter is required to specify which location's timesheets to query
Times are in ISO 8601 format with timezone information
Timesheet status progression: committed → completed → approved → payrolled
The hours field automatically excludes unpaid breaks (where subtracts: true)
The cost field is optional and calculated based on the employee's pay rate and applicable pay rules
The variance field is optional and shows the difference between scheduled (roster) hours and actual timesheet hours
The workType field indicates special pay conditions or rules applied to the timesheet
Breaks with subtracts: true are unpaid breaks that reduce the total paid hours
Timesheets can span multiple days (e.g., overnight shifts)
Only timesheets within the specified date range will be returned

GraphQL Query

query Timesheets($startTime: DateTime!, $endTime: DateTime!, $locationId: ID!) {
  timesheets(startTime: $startTime, endTime: $endTime, locationId: $locationId) {
    id
    startTime
    endTime
    status
    hours
    cost
    variance
    workType {
      id
      name
      appliedFromId
    }
    breaks {
      id
      startTime
      endTime
      subtracts
    }
    employee {
      id
      fullName
    }
    position {
      id
      text
    }
    location {
      id
      name
      timezone
    }
  }
}

Example Variables

{
  "startTime": "2024-04-01T16:00:00.000Z",
  "endTime": "2024-06-14T17:59:59.999Z",
  "locationId": "12325"
}

Example Response

{
  "data": {
    "timesheets": [
      {
        "id": "4518810",
        "startTime": "2024-04-04T23:00:00.000Z",
        "endTime": "2024-04-05T07:00:00.000Z",
        "status": "approved",
        "hours": 7.6,
        "cost": 0,
        "variance": 0,
        "workType": null,
        "breaks": [
          {
            "id": "330409",
            "startTime": "2024-04-05T02:00:00.000Z",
            "endTime": "2024-04-05T02:24:00.000Z",
            "subtracts": true
          }
        ],
        "employee": {
          "id": "73542",
          "fullName": "Kate Mallone"
        },
        "position": null,
        "location": {
          "id": "12326",
          "name": "Brisbane Office",
          "timezone": "Australia/Brisbane"
        }
      },
      {
        "id": "4518993",
        "startTime": "2024-06-09T23:00:00.000Z",
        "endTime": "2024-06-10T07:00:00.000Z",
        "status": "approved",
        "hours": 7.5,
        "cost": 0,
        "variance": 0,
        "workType": {
          "id": "114",
          "name": "Min Break",
          "appliedFromId": null
        },
        "breaks": [
          {
            "id": "330656",
            "startTime": "2024-06-10T03:00:00.000Z",
            "endTime": "2024-06-10T03:30:00.000Z",
            "subtracts": true
          }
        ],
        "employee": {
          "id": "72909",
          "fullName": "Nicolas Chan"
        },
        "position": {
          "id": "18100",
          "text": "Full Stack Developer"
        },
        "location": {
          "id": "12326",
          "name": "Brisbane Office",
          "timezone": "Australia/Brisbane"
        }
      }
    ]
  }
}