ConnectCloud Developers

An employee's month with target, actual, breaks, absences, ArbZG warnings and time account

GET /api/hr/v1/timesheet

Module: HR · operationId: getTimesheet · Tag: Working time · Auth: access token (Authorization: Bearer <accessToken>)

Parameters

Name In Type Required Description
employeeId query string Empty or me for the caller
month query string YYYY-MM, defaults to the current month

Responses

  • 200 Timesheet (application/json)
  • 400 Error (application/json)
  • 404 Error (application/json)

Fields of the 200 answer:

  • balance (integer): Time account in minutes at the end of the month (up to yesterday for the current month: today is not counted yet)
  • closed (boolean): The month is closed: its entries and absences cannot change
  • days (array of TimesheetDay): Every day of the month
    • absence (object): The absence on the day, if any
      • fraction (number): Share of the day the absence covers (1 or 0.5)
      • id (string): Id of the absence
      • status (string): State of the absence
      • typeId (string): Id of the absence type
    • actual (integer): Worked minutes
    • break (integer): Break minutes
    • counted (boolean): The day lies before today (tenant time zone) and counts in the totals and the time account. Today shows its live target, actual and credit but is not counted yet; later days show their target only
    • credit (integer): Minutes absences count as worked
    • date (string (date)): The day (YYYY-MM-DD)
    • delta (integer): actual + credit − target, in minutes; 0 on days not counted (today and later)
    • entries (array of TimeEntry): Time entries of the day
      • autoEnded (boolean): HR ended the segment at midnight because nobody clocked out (setting autoEndAtMidnight). It counts no working time until it is corrected; any change clears the mark.
      • breakMinutes (integer): Break inside the segment in minutes (manual entries)
      • createdAt (string (date-time)): When the time entry was created
      • createdBy (string): Who created the time entry (e-mail of the caller)
      • employeeId (string): Id of the employee
      • end (string (date-time)): Missing while running
      • endedForBreak (boolean): The segment was closed by starting a break
      • id (string): Id of the time entry
      • note (string): Note on the entry
      • source (string): clock: stamped, manual: entered by hand (one of clock, manual)
      • start (string (date-time)): Start of the segment
      • updatedAt (string (date-time)): When the time entry was last changed
      • updatedBy (string): Who last changed the time entry (e-mail of the caller)
      • version (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
    • holiday (Holiday)
      • custom (boolean): A holiday of the tenant's own (omitted when false)
      • date (string (date)): Date (YYYY-MM-DD)
      • fraction (number): 1 for a full day, 0.5 for a half day (e.g. 24.12.) (one of 0.5, 1)
      • name (string): Name of the holiday
    • running (boolean): A segment of the day is still open
    • target (integer): Scheduled minutes (minus holidays and unpaid absences)
    • violations (array of Violation): Working-time rule warnings (ArbZG); never blocking
      • breakMinutes (integer): Break that counts under §4 ArbZG: interruptions of 15 minutes or more plus booked breaks (break_6h, break_9h)
      • code (string): auto_ended is no ArbZG rule: a segment HR ended at midnight whose times need checking (one of break_6h, break_9h, max_10h, rest_11h, sunday_holiday, open_entry, auto_ended)
      • entryId (string): The open or auto-ended entry (open_entry, auto_ended)
      • excessMinutes (integer): Worked time above the maximum (max_10h)
      • message (string): Human-readable text of the warning (German)
      • requiredMinutes (integer): Limit of the rule: required break (30/45), maximum worked time (600) or minimum rest (660)
      • restMinutes (integer): Rest since the previous work (rest_11h)
      • since (string (date-time)): End of the previous work (rest_11h) or start of the open or auto-ended entry (open_entry, auto_ended)
      • workedMinutes (integer): Worked time of the day (break_6h, break_9h, max_10h, sunday_holiday)
  • editableFrom (string (date)): First day the caller changes without a reason
  • employeeId (string): Id of the employee
  • employeeName (string): Display name of the employee
  • month (string): The month (YYYY-MM)
  • openingBalance (integer): Time account in minutes before the month
  • totals (TimeTotals): Minutes. target, actual, break, credit and delta sum the counted days only (counted: before today in the tenant's time zone – a past month counts every day, a future month none); today and later days count once they are over
    • actual (integer): Worked minutes of the counted days
    • break (integer): Break minutes of the counted days
    • credit (integer): Minutes absences count as worked, on the counted days
    • delta (integer): actual + credit − target of the counted days, in minutes
    • monthTarget (integer): Target minutes of every day of the month (counted or not)
    • target (integer): Target minutes of the counted days (up to yesterday)
    • violations (integer): Number of working-time rule warnings (every day, today included)

Example 200 answer:

{
  "balance": 157,
  "closed": false,
  "days": [
    {
      "actual": 482,
      "break": 30,
      "counted": true,
      "credit": 0,
      "date": "2026-11-18",
      "delta": 2,
      "entries": [
        {
          "autoEnded": false,
          "breakMinutes": 30,
          "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
          "end": "2026-11-18T15:00:00Z",
          "endedForBreak": false,
          "id": "3a5c7e9a-1c3e-4a5c-9e7a-1c3e5a7c9e36",
          "source": "clock",
          "start": "2026-11-18T06:28:00Z",
          "version": 3
        }
      ],
      "running": false,
      "target": 480,
      "violations": []
    },
    {
      "actual": 145,
      "break": 0,
      "counted": false,
      "credit": 0,
      "date": "2026-11-19",
      "delta": 0,
      "entries": [
        {
          "autoEnded": false,
          "breakMinutes": 0,
          "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
          "endedForBreak": false,
          "id": "5c7e9a1c-3e5a-4c7e-8a9c-3e5a7c9e1a37",
          "source": "clock",
          "start": "2026-11-19T06:31:00Z",
          "version": 1
        }
      ],
      "running": true,
      "target": 480,
      "violations": []
    }
  ],
  "editableFrom": "2026-11-05",
  "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "employeeName": "Sophie Huber",
  "month": "2026-11",
  "openingBalance": 135,
  "totals": {
    "actual": 6262,
    "break": 390,
    "credit": 0,
    "delta": 22,
    "monthTarget": 10080,
    "target": 6240,
    "violations": 0
  }
}

Example request

curl -X GET 'https://api.mbcom.cloud/api/hr/v1/timesheet' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

View as Markdown · Interactive reference · OpenAPI