ConnectCloud Developers

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: or comms:calendar:
  • 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:

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

View as Markdown · Interactive reference · OpenAPI