Untether LabsDevelopers

Get Timesheets

gethttps://app.untetherlabs.com/api/v1/timekeeping/timesheet

Allows reading computed timesheet data for one or more providers.

Timesheets are returned for any matching provider who was active during the specified date range even if they worked zero hours. These values are impacted by historical corrections, you are advised to review the Historical Corrections documentation.

Available Expansions
expand options
  • provider: Includes the entire provider object for each timesheet.
  • paySegments: Pay segments describe each individually worked span during the timesheet. They are the primitive unit of timekeeping data.
  • scheduledPaySegments: Scheduled pay segments represent the expected set of worked segments based on the schedule only, not punch data.
  • problems: Includes any warnings and errors for the timesheet.
  • approval: Includes whether the entire range is approved, and the exact sub ranges that have been approved.
  • signOff: Includes whether the entire range is signed off, and the exact sub ranges that have been signed off.
  • historicalCorrections: Includes any historical corrections which are applied to the time range of the timesheet. These are historical corrections which were made to this time range as opposed to applied to/paid out in this range.
  • totals: The computed totals broken down by pay code and role for the requested range.
  • historicalCorrectionTotals: The totals from any historical corrections which are applied to this timesheet (as opposed to corrections made to this timesheet). Historical correction totals are only available when requesting a particular pay period (by offset or exact reference).

This endpoint may have to do significant computation to generate timesheet data on-the-fly, you are advised to set appropriate timeout and consider caching the results if applicable.

This endpoint is paginated. See Pagination for how to page through the results.

Query parameters#

teamIduuid
providerIduuid
payPeriodIduuid
payPeriodOffsetinteger

Optional offset from current pay period. 0 = current, 1 = next, -1 = previous.

startDatestring
endDatestring
expandstring

Available expansions: provider, paySegments, scheduledPaySegments, problems, approval, signOff, historicalCorrections, totals, historicalCorrectionTotals

See Query Parameters for more information on expansions.

pageSizenumber· default 20 · min 1 · max 200
cursorstring

Response 200#

itemsTimesheet[]
Required
Show Timesheet properties
providerIduuid
Required
providerProvider
Show Provider properties
namestring | null
Required
emailstring
Required
hireDatestring | null
Required
statusenum
Required
onboarding
active
dismissed
unmanaged
teamIduuid | null
Required
licensedRegionsstring[]
Required
employmentTypeuuid | null
Required
startDatestring
Required
endDatestring
Required
payPeriodIduuid | null
Required

The matching pay period, or null if the range does not align to a single pay period.

scheduledShiftsShift[]
Required
Show Shift properties
createdAtstring
Required
versionnumber

Version number for optimistic locking. Include this when updating to detect conflicts.

provideruuid | null
Required

The provider of the shift. If null, the shift is an open shift.

providerNamestring | null

The display name of the provider. Only populated when the request opts in via includeDisplayNames.

startDatestring
Required
endDatestring
Required
segmentsShiftSegment[]
Required

The segments that make up a shift, ordered by startDate.

Show ShiftSegment properties
importedIdstring | null
Required

If a segment was created in an external system, this is the ID of the segment in that system.

createdAtstring
Required
roleuuid | null
Required

The role of the shift. Can be null if the shift is pulled from an external system.

roleNamestring | null

The display name of the segment's role. Only populated when the request opts in via includeDisplayNames.

roleColorstring | null

The hex color of the segment's role. Only populated when the request opts in via includeDisplayNames.

roleImportedIdstring

DEPRECATED The ID of the role in the external system. Once all roles are migrated to the system, this field will be removed.

additionalInfoany

DEPRECATED Additional information about the segment.

isBreakboolean
Required

Used to denote whether or not the provider will be on break during this segment.

isOnCallboolean
Required
typeenum
Required

The type of the segment.

working
Regular working segment
paid_break
Paid break segment
unpaid_break
Unpaid break segment
on_call
On-call segment
startDatestring
Required

The timestamp of when the shift starts.

endDatestring
Required

The timestamp of when the shift ends.

skillRequirementNullableSkillRequirement
Option 1 — SkillRequirementCondition
typeenum
Required
skillstring· min length 1
Required
valuestring
Required
Option 2 — SkillRequirementGroup
typeenum
Required
entriesone of[]· min items 1
Required
labelsstring[]
Required

The label IDs associated with this shift segment.

payCodesShiftPayCode[]· max items 1
payCodeIduuid
Required

The pay code ID associated with this shift.

valuenumber

Only present for variable pay codes. The value of the pay code for this shift.

teamuuid | null
Required

The team that the shift is associated with.

notestring | null
Required

A note about the shift. Visible to providers.

isCalloutboolean
Required

Whether the shift is marked as a callout. Callout shifts are hidden from reads unless an endpoint explicitly includes them.

workRuleOverrideuuid | null
Required
punchesTimecardPunch[]
Required
Show TimecardPunch properties
timecardIduuid
Required
providerIduuid
Required
generatedboolean· default false
createdAtstring
Required
updatedAtstring
Required
actionstring
Required
stateTimecardPunchState
Required
pending
approved
rejected
timestring
Required
providerNotestring | null
Required
adminNotestring | null
Required
paySegmentsPaySegment[]
Show PaySegment properties
typePaySegmentType
Required
paid
unpaid
on_call
itemIdstring | null
shiftIdstring | null
timecardIdstring | null
startDatestring
Required

The start date of the pay segment.

endDatestring
Required

The end date of the pay segment.

payCodesstring[]
Required
overtimestring[]
Required
timeRangesstring[]
Required
workRuleOverridestring | null
rolestring | null
scheduledPaySegmentsPaySegment[]
Show PaySegment properties
typePaySegmentType
Required
paid
unpaid
on_call
itemIdstring | null
shiftIdstring | null
timecardIdstring | null
startDatestring
Required

The start date of the pay segment.

endDatestring
Required

The end date of the pay segment.

payCodesstring[]
Required
overtimestring[]
Required
timeRangesstring[]
Required
workRuleOverridestring | null
rolestring | null
warningsTimesheetWarning[]
typeTimesheetWarningType
Required
clock_in_early
clock_out_early
clock_in_late
clock_out_late
missing_shift
punchIduuid
Required
errorsTimesheetError[]
typeTimesheetErrorType
Required
no_clock_out
invalid_shift
missing_timecard
missing_pay_period_template
shiftIduuid
timecardIduuid
approvalTimesheetApproval
Show TimesheetApproval properties
approvedboolean
Required
rangesTimeRange[]
Required
startDatestring
Required
endDatestring
Required
signOffTimesheetSignOff
Show TimesheetSignOff properties
signedOffboolean
Required
rangesTimeRange[]
Required
startDatestring
Required
endDatestring
Required
historicalCorrectionsHistoricalCorrection[]
Show HistoricalCorrection properties
statusHistoricalCorrectionStatus
Required
pending
The historical correction is still being processed. `payCodeDifference` will always be empty.
completed
changesHistoricalCorrectionChange[]
Required
Show HistoricalCorrectionChange properties
createdAtstring
Required
actorobject | null
Required

A null actor indicates a system-generated change

namestring
Required
notestring
auditLogReferenceuuid | null
Required

A null audit log reference indicates a manually triggered historical correction

auditLogActionstring | null
Required

The action associated with the audit log reference. Will be null if there is no audit log reference.

payCodeDifferenceHistoricalCorrectionPayCodeDifference[]
Required
datestring
Required

Always represents the start of the day.

payCodeuuid
Required
rolestring | null
Required
valuenumber
Required

The difference in minutes (may be negative)

totalsPayCodeTotal[]
payCodeIduuid
Required
roleIduuid | null
Required

The role worked during this time, or null for non-working time.

schedulednumber
Required

The number of minutes scheduled for this pay code and role.

actualnumber
Required

The number of minutes actually worked for this pay code and role.

historicalCorrectionTotalsPayCodeTotal[]
payCodeIduuid
Required
roleIduuid | null
Required

The role worked during this time, or null for non-working time.

schedulednumber
Required

The number of minutes scheduled for this pay code and role.

actualnumber
Required

The number of minutes actually worked for this pay code and role.

cursorstring

Errors#

negative-range400

Time range end date must come after start date.

Show extension members
pathstring
validation400

Input validation failed.

Show extension members
pathstring
messagestring
Required