## 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:

```json
{
  "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

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