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 isfrom(string (date), required): First day of the range (YYYY-MM-DD)items(array of CalendarItem, required): Ordered by startallDay(boolean, required): Whole days (absences, all-day appointments); start and end are the day boundaries in the tenant's time zoneend(string (date-time), required): End of the itemhidden(boolean, required): Another person's item the caller may not see (or that could not be checked): kindbusy, time only, empty label, no customer or subjectid(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 generatedkind(string, required):appointmentis a Microsoft 365 appointment of the owner (own calendar only; another person sees it asbusy).busyis a hidden item of another person (work, call, remote session or meeting the caller may not see) – not even its kind is told (one ofattendance,work,call,remote_session,meeting,absence,appointment,busy)label(string, required): Title of the item (subject label, note); empty when hidden or privatestart(string (date-time), required): Start of the itembooked(boolean): An appointment (kindappointment, own calendar) already booked as a work entry, which is its own item; omitted otherwisecustomer(object): Customer of the item, when the viewer may see itid(string): Id of the customer (masterdata address)name(string): Name of the customer
private(boolean): A private appointment (kindappointment, own calendar): no label, only the time; omitted otherwisesubject(string): Reference of what it is about, e.g. comms:interaction: or comms:calendar:
to(string (date), required): Last day of the range (YYYY-MM-DD)truncated(boolean, required): comms listed only part of the rangeunavailable(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:
{
"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
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/calendar?from=2026-03-02&to=2026-03-02' \
-H "Authorization: Bearer $ACCESS_TOKEN"