## A person's calendar – attendance, work, absences, calls (tenant:access)

`GET /api/hr/v1/calendar`

Module: HR · operationId: `getCalendar` · Tag: Work entries · Auth: access token (`Authorization: Bearer <accessToken>`)

Everything the person did in a range of at most 42 days (inclusive, tenant time zone): closed attendance
segments, finished work entries with start and end (a running stopwatch is not a block), absences as all-day
items and the calls, remote sessions and meetings of comms. An interaction a work entry was booked from
(`source` interaction) appears once, as the work entry. comms failing never fails the calendar: `unavailable`
names it and the other items stay; `truncated` when comms listed only part of the range. Microsoft 365
appointments are not included. Without an employee record `403 no_employee`; a bad range is `400` (field
`range`).

`employeeId` is `me` (default), the own id or another employee's id. Another person's calendar is served only
to who is above them in the chain of command (line managers and deputies, the whole subtree) and to the
colleagues they share it with (`PUT /calendar/shares/{employeeId}`, checked on every request: a revoked share
closes it at once); everyone else – also with `hr:work:manage`, `hr:time:manage` or admin rights – gets `404`,
as for an unknown id. The viewer sees each item only as far as they may see it themselves: attendance only
under the attendance rules (`hr:time:manage` or the chain of command), labelled `anwesend`; absences as
`abwesend`, never their type; work entries, calls, remote sessions and meetings by their `subject`, which HR
asks the owning module about for the viewer (once per module): visible items carry the module's label and
customer for the viewer, everything else – not visible, no subject, a module that cannot answer (it is named
in `unavailable`) – is a block with `hidden` true and the neutral kind `busy`, its times only (no label,
customer, subject; a generated `id` `hidden-<n>`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `employeeId` | query | string |  | `me` (default), the own id or the id of a person whose calendar the caller may see |
| `from` | query | string (date) | yes | First day |
| `to` | query | string (date) | yes | Last day, at most 41 days after from |

### Responses

- **200** The calendar (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `employeeId` (string, required): Id of the employee whose calendar it is
- `from` (string (date), required): First day of the range (YYYY-MM-DD)
- `items` (array of CalendarItem, required): Ordered by start
  - `allDay` (boolean, required): Whole days (absences, all-day appointments); start and end are the day boundaries in the tenant's time zone
  - `end` (string (date-time), required): End of the item
  - `hidden` (boolean, required): Another person's item the caller may not see (or that could not be checked): kind `busy`, time only, empty label, no customer or subject
  - `id` (string, required): The item's id (time entry, work entry, absence, interaction); in another person's calendar only for visible work, calls and meetings, else generated
  - `kind` (string, required): `appointment` is a Microsoft 365 appointment of the owner (own calendar only; another person sees it as `busy`). `busy` is a hidden item of another person (work, call, remote session or meeting the caller may not see) – not even its kind is told (one of `attendance`, `work`, `call`, `remote_session`, `meeting`, `absence`, `appointment`, `busy`)
  - `label` (string, required): Title of the item (subject label, note); empty when hidden or private
  - `start` (string (date-time), required): Start of the item
  - `booked` (boolean): An appointment (kind `appointment`, own calendar) already booked as a work entry, which is its own item; omitted otherwise
  - `customer` (object): Customer of the item, when the viewer may see it
    - `id` (string): Id of the customer (masterdata address)
    - `name` (string): Name of the customer
  - `private` (boolean): A private appointment (kind `appointment`, own calendar): no label, only the time; omitted otherwise
  - `subject` (string): Reference of what it is about, e.g. comms:interaction:<id> or comms:calendar:<id>
- `to` (string (date), required): Last day of the range (YYYY-MM-DD)
- `truncated` (boolean, required): comms listed only part of the range
- `unavailable` (array of string, required): Sources that failed (comms listing the interactions; for another person's calendar also the modules that could not say what the viewer may see – their items are hidden); the other items stay

Example 200 answer:

```json
{
  "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "from": "2026-11-16",
  "items": [
    {
      "allDay": false,
      "end": "2026-11-16T15:00:00Z",
      "hidden": false,
      "id": "7b9d1f3b-5d7f-4b9d-8f1b-5d7f9b1d3f58",
      "kind": "attendance",
      "label": "",
      "start": "2026-11-16T06:30:00Z"
    },
    {
      "allDay": false,
      "customer": {
        "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
        "name": "Alpenhotel Seeblick GmbH"
      },
      "end": "2026-11-16T09:20:07Z",
      "hidden": false,
      "id": "4f6a8c0e-2b4d-4f6a-8c0e-2b4d6f8a0c2e",
      "kind": "call",
      "label": "Katrin Stadler",
      "start": "2026-11-16T09:12:00Z",
      "subject": "comms:interaction:4f6a8c0e-2b4d-4f6a-8c0e-2b4d6f8a0c2e"
    },
    {
      "allDay": false,
      "customer": {
        "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
        "name": "Alpenhotel Seeblick GmbH"
      },
      "end": "2026-11-16T09:27:00Z",
      "hidden": false,
      "id": "5e7a9c1e-3a5c-4e7a-9c1e-3a5c7e9a1c51",
      "kind": "work",
      "label": "#214 WLAN im Restaurant fällt aus",
      "start": "2026-11-16T09:12:00Z",
      "subject": "desk:item:6a8c0e2a-4b6d-4f8a-9c1e-3b5d7f9a1c3e"
    },
    {
      "allDay": false,
      "booked": false,
      "end": "2026-11-16T13:30:00Z",
      "hidden": false,
      "id": "9d1f3b5d-7f9b-4d1f-9b3d-7f9b1d3f5b59",
      "kind": "appointment",
      "label": "Abstimmung Rollout Donau Maschinenbau",
      "start": "2026-11-16T13:00:00Z",
      "subject": "comms:calendar:AAMkAGEXAMPLE0001"
    }
  ],
  "to": "2026-11-16",
  "truncated": false,
  "unavailable": []
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/calendar?from=2026-03-02&to=2026-03-02' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
