Shifts

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 Shifts by Location

Retrieve shifts for a specific location within a date range.

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 shifts for
published Boolean No Filter by published status (true/false/null for all)

Response Fields:

Field Description
id Unique identifier for the shift
startTime Start date/time of the shift
endTime End date/time of the shift
breaks Array of break periods for the shift
breaks[].startTime Start time of the break
breaks[].endTime End time of the break
breaks[].subtracts Whether the break is subtracted from paid hours
published Whether the shift has been published to employees
hours Total hours for the shift (including breaks)
employee.id ID of the employee assigned to the shift
employee.fullName Full name of the employee
position.id ID of the position for this shift
position.text Name/description of the position
location.id ID of the location
location.name Name of the location

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

Implementation Notes:

  • Times are in ISO 8601 format with timezone information
  • When published is null or omitted, both published and unpublished shifts are returned
  • When published is true, only shifts visible to employees are returned
  • When published is false, only draft/unpublished shifts are returned
  • The hours field includes both paid and unpaid time
  • Breaks with subtracts: true are unpaid breaks that reduce the paid hours
  • Shifts can span multiple days (e.g., overnight shifts)
  • The date range is inclusive of both start and end times

GraphQL Query

query Roster($startTime: DateTime!, $endTime: DateTime!, $locationId: ID!, $published: Boolean) {
  shifts(startTime: $startTime, endTime: $endTime, locationId: $locationId, published: $published) {
    id
    startTime
    endTime
    breaks {
      startTime
      endTime
      subtracts
    }
    published
    hours
    employee {
      id
      fullName
    }
    position {
      id
      text
    }
    location {
      id
      name
    }
  }
}

Example Variables

{
  "startTime": "2024-05-01T16:00:00.000Z",
  "endTime": "2024-05-30T17:59:59.999Z",
  "locationId": "12325",
  "published": null
}

Example Response

{
  "data": {
    "shifts": [
      {
        "id": "5652527",
        "startTime": "2024-05-22T00:00:00.000Z",
        "endTime": "2024-05-22T04:00:00.000Z",
        "breaks": [],
        "published": true,
        "hours": 4,
        "employee": {
          "id": "72908",
          "fullName": "Craig Bussell"
        },
        "position": {
          "id": "18215",
          "text": "Product Manager"
        },
        "location": {
          "id": "12325",
          "name": "Integration Sandbox"
        }
      },
      {
        "id": "5652528",
        "startTime": "2024-05-20T22:00:00.000Z",
        "endTime": "2024-05-21T05:00:00.000Z",
        "breaks": [],
        "published": true,
        "hours": 7,
        "employee": {
          "id": "72908",
          "fullName": "Craig Bussell"
        },
        "position": {
          "id": "18215",
          "text": "Product Manager"
        },
        "location": {
          "id": "12325",
          "name": "Integration Sandbox"
        }
      }
    ]
  }
}

Query Shifts by Employee

Retrieve shifts for a specific employee within a date range.

Query Parameters:

Parameter Type Required Description
startTime DateTime! Yes Start of the date range (inclusive)
endTime DateTime! Yes End of the date range (inclusive)
employeeId ID No ID of the employee to query shifts for
published Boolean No Filter by published status (true/false/null for all)

Response Fields:

Field Description
id Unique identifier for the shift
startTime Start date/time of the shift
endTime End date/time of the shift
breaks Array of break periods for the shift
breaks[].startTime Start time of the break
breaks[].endTime End time of the break
breaks[].subtracts Whether the break is subtracted from paid hours
published Whether the shift has been published to employees
hours Total hours for the shift (including breaks)
cost Cost of the shift (based on employee's pay rate)
employee.id ID of the employee assigned to the shift
employee.fullName Full name of the employee
position.id ID of the position for this shift
position.text Name/description of the position
location.id ID of the location
location.name Name of the location

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

Implementation Notes:

  • Times are in ISO 8601 format with timezone information
  • When employeeId is omitted, shifts for all employees are returned
  • When published is null or omitted, both published and unpublished shifts are returned
  • The cost field is calculated based on the employee's pay rate and shift duration
  • Cost calculations take into account pay rules, pay levels, and any applicable penalty rates
  • This endpoint can be used to calculate total hours worked for payroll purposes
  • The date range is inclusive of both start and end times
  • Shifts can span multiple days (e.g., overnight shifts)

GraphQL Query

query Roster($startTime: DateTime!, $endTime: DateTime!, $published: Boolean, $employeeId: ID) {
  shifts(startTime: $startTime, endTime: $endTime, published: $published, employeeId: $employeeId) {
    id
    startTime
    endTime
    breaks {
      startTime
      endTime
      subtracts
    }
    published
    hours
    cost
    employee {
      id
      fullName
    }
    position {
      id
      text
    }
    location {
      id
      name
    }
  }
}

Example Variables

{
  "startTime": "2023-09-30T16:00:00.000Z",
  "endTime": "2023-11-31T17:59:59.999Z",
  "published": null,
  "employeeId": "73544"
}

Example Response

{
  "data": {
    "shifts": [
      {
        "id": "5633782",
        "startTime": "2023-11-12T23:00:00.000Z",
        "endTime": "2023-11-13T07:00:00.000Z",
        "breaks": [],
        "published": true,
        "hours": 8,
        "employee": {
          "id": "73544",
          "fullName": "Alana Robertson"
        },
        "position": {
          "id": "18101",
          "text": "General Manager"
        },
        "location": {
          "id": "12326",
          "name": "Brisbane Office"
        }
      },
      {
        "id": "5633783",
        "startTime": "2023-11-13T23:00:00.000Z",
        "endTime": "2023-11-14T07:00:00.000Z",
        "breaks": [],
        "published": true,
        "hours": 8,
        "employee": {
          "id": "73544",
          "fullName": "Alana Robertson"
        },
        "position": {
          "id": "18101",
          "text": "General Manager"
        },
        "location": {
          "id": "12326",
          "name": "Brisbane Office"
        }
      }
    ]
  }
}