# ConnectCloud HR API (v1.0.0)

Employees, roles and groups, absences and vacation accounts, working time, travel expenses and the organisation chart. Also issues the access tokens for every other API.

Base URLs:

- Production: `https://api.mbcom.cloud/api/hr/v1`
- Staging: `https://api.mbcom.cloud/api/hr/v1`
- Sandbox: `https://developers.mbcom.cloud/sandbox/hr`

HR manages the people of a tenant ("Mitarbeitende") and who may do what. It is the source of
truth for portal users: HR signs people in (Microsoft or passkey, for the portal's server, which keeps the
session) and mints their session tokens, based on the tenants they belong to and the
permissions they hold there.

## Model
- **Employees** have one built-in field, `email` (unique per tenant). Everything else is a
  tenant-defined **field** (`text`, `longtext`, `number`, `date`, `datetime`, `bool`,
  `select`, `multiselect`, `url`, `phone`, `email`); values live in `customFields`. Restricted fields are only
  visible to callers with `hr:write`; fields marked `visibleToColleagues` are shown to every colleague in the
  directory (`listColleagues`). Every tenant has a catalogue of **standard fields**
  (personnel number, position, department, entry date, …) that are switched on or off with
  `archived`; all fields are grouped in **sections** (person, contact, employment, working
  time, confidential, other).
- **Roles** are named sets of permissions from the grantable catalogue (`GET /bootstrap`).
  Seeded roles: Administrator (locked), Mitarbeiter, Einstellungen lesen, Datenzugriff,
  Rechnungsvergleich; the operator tenant also has the locked Portal-Administration (`portal:admin`).
- **Groups** bundle employees and give them roles. An employee's effective permissions are
  the union of the roles granted directly and through groups.
- A tenant signs in through HR as soon as it has one employee. Creating the first employee
  also creates the acting administrator as Administrator.
- **Absences** have a tenant-defined **type** (vacation, sickness, …) and a workflow
  `requested → approved | rejected`, `approved → cancellation_requested → cancelled`.
  Their working days come from the employee's **working-time model** (effective-dated
  target minutes per weekday and yearly vacation days) and the **holidays** of the
  Bundesland plus the tenant's own. The **vacation account** of a year is the prorated
  entitlement plus the carryover (until `carryoverExpiry`) plus corrections minus approved
  and requested vacation.
- The **organisation** is a tree of **org units** with a head and a deputy each; employees are
  placed in a unit and may have a manager override. The **chain of command** of a person is their
  direct manager (override, else the head of their unit or of the nearest parent unit with another
  head), then that manager's chain. Managers and the deputies of the chain's heads decide absences
  and manage the working time of the people they are responsible for.
- **Working time** is booked as **time entries** (worked segments from the stamp clock or
  entered manually; changes keep a history). The **timesheet** compares them per day with the
  target, credits absences, flags Arbeitszeitgesetz breaches (warnings) and sums up the **time
  account**. Closed months freeze their figures and lock their entries and absences.
- **Travel expense reports** cover one business trip: times, destination country, the meals provided
  per day and the expenses (mileage, transport, lodging, other) with receipt photos stored in the DMS
  (malware-scanned; AI can read them into a draft). Meal allowances, lodging lump sums and mileage
  come from the tenant's **travel rates** (per country and validity). Workflow
  `draft → submitted → approved → released → transferred` (rejected reports go back to the owner);
  the transfer creates a trade document (Einkauf, `TRAVEL_EXPENSE`) for the employee's masterdata address.
- Every **employee** has a person address in masterdata with the roles customer and supplier
  (`addressId`), created and kept up to date by HR.

## Authentication
Send an access token as `Authorization: Bearer <accessToken>`. Get it by exchanging an API key at
`POST https://api.mbcom.cloud/api/hr/v1/auth/token`; it lives 15 minutes and carries the key's permissions.
The tenant is always the one of the token. Guide: https://developers.mbcom.cloud/guides/authentication

## Permissions
| Permission | Grants |
|---|---|
| `tenant:access` | own absences, vacation account, time entries, timesheet, stamp clock; own travel expense reports; team calendar; colleagues' presence (absent until) |
| `hr:read` | read employees and their working-time models |
| `hr:write` | create and edit employees (including restricted fields) |
| `hr:admin` | employee fields and settings, absence types, holidays, working-time settings |
| `hr:absence:approve` | all absences with their type, approve/reject/cancel, vacation corrections |
| `hr:absence:request` | lets the AI assistant propose the own absence request (assistant visibility only; the route itself needs `tenant:access`) |
| `hr:time:record` | lets the AI assistant propose the own clock-in, clock-out and breaks (assistant visibility only; the route itself needs `tenant:access`) |
| `hr:time:manage` | everyone's time entries and timesheets, close/reopen months, time account corrections, export |
| `hr:travel:approve` | every travel expense report with its receipts; approve and reject submitted reports (managers decide their team's without it) |
| `hr:travel:manage` | release approved reports, transfer them to trade, reject approved ones; travel rates and settings |
| `hr:team:lead` | derived, never granted: set for everyone responsible for other people; only drives what the portal shows – HR checks the chain of command itself |
| `identity:admin` | roles, groups, role assignments, invitations, enabling/disabling employees; service accounts and their keys, revoking anyone's personal keys |
| `tenant:token:generate` | own personal API keys |

Nobody can grant or revoke permissions they do not hold themselves (`403 forbidden_grant`),
and every tenant keeps at least one active employee with `identity:admin`
(`409 last_admin`). `portal:admin` (portal administration of the platform) exists only in roles of the
operator tenant 10639/MBCOM (its locked role *Portal-Administration*); a role holding it in any other tenant
answers `403 forbidden_grant`, and API keys never carry it.

## Conventions
- Updates use optimistic locking: send the `version` you read; a stale version returns `409`.
- Errors have the shape `{error, code, field?, missingFields?}`.
- Rate limits: 20 requests per second per signed-in principal and route with bursts up to 100 (per client IP for failed authentications).

## Events
Published through the transactional outbox: `hr.employee.created|updated|active|disabled|invited`,
`hr.access.changed`, `hr.config.changed`,
`hr.absence.requested|approved|rejected|cancelled|cancellation_requested|changed`, `hr.vacation.adjusted`,
`hr.org.changed`, `hr.employee.placement_changed`,
`hr.timeentry.changed`, `hr.timeperiod.closed|reopened`, `hr.timeaccount.adjusted`, `hr.schedule.changed`,
`hr.travel.submitted|approved|rejected|released|transferred|draft` (draft: recalled by its owner),
`hr.work_entry.created|updated|deleted|approved|unapproved`, `hr.work_batch.requested|invoiced` (ids, scope and
references only), `hr.mobile_session.ended` (a phone session of the first-party mobile app ended: revoked, replayed
or idle; payload `{grantId, sid}`, not offered to flows).

Absence events carry `absenceId`, `employeeId`, `employeeName`, `employeeEmail`, `typeId`,
`typeName`, `typeSensitive`, `status`, `startDate`, `endDate` and `days` (working days);
`approved`, `rejected` and `cancelled` also carry `decidedBy` (who acted).

Travel events carry `reportId`, `employeeId`, `employeeName`, `employeeEmail`, `status`, `purpose`,
`destination`, `startDate`, `endDate` and `total` (euros); decisions carry `decidedBy`, rejections
`reason`, transfers `tradeTransactionId` and `tradeDocumentNo`.

Work entry events carry ids and references only: `id`, `employeeId`, `workDate`, `state`, `version` and, where
set, `subject`, `origin`, `projectRef` and `correctionOf` – never descriptions or labels.

# Configuration

## Fields, roles, groups, settings and the permission catalogue

`GET /api/hr/v1/bootstrap`

Module: HR · operationId: `getBootstrap` · Tag: Configuration · Auth: access token (`Authorization: Bearer <accessToken>`)

Needs `hr:read`, `hr:admin` or `identity:admin`. `grantable` lists the permissions the caller may grant. Managers and deputies in the chain of command without these permissions get the field definitions and settings without roles, groups and `employeeCount` (to show their team's records); everybody else `403`.

### Responses

- **200** Configuration (`application/json`)

Fields of the 200 answer:

- `absenceTypes` (array of AbsenceType): Absence types of the tenant
  - `key` (string, required): Stable key of the type
  - `name` (string, required): Display name
  - `allowHalfDays` (boolean): Half days may be requested
  - `archived` (boolean): Archived: no longer offered for new data, kept for existing data
  - `color` (string): Semantic colour of the type in calendars (one of `primary`, `info`, `success`, `warning`, `error`, `neutral`)
  - `countsAgainstVacation` (boolean): Days of this type are taken from the vacation account
  - `icon` (string): Lucide icon (i-lucide-…)
  - `id` (string): Id of the absence type
  - `paid` (boolean): The absence is paid time
  - `requiresApproval` (boolean): Requests start as requested and need a decision; otherwise they are approved when entered
  - `sensitive` (boolean): Colleagues see only "abwesend"
  - `sortOrder` (integer): Position in lists (ascending)
  - `timeEffect` (string): credit: counts as worked; none: the time account pays (Überstundenabbau); reduce_target: no target (unpaid) (one of `credit`, `none`, `reduce_target`)
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `customHolidays` (array of CustomHoliday): The tenant's own holidays
  - `date` (string (date), required): Date (YYYY-MM-DD)
  - `fraction` (number, required): 1 for a full day, 0.5 for a half day (one of `0.5`, `1`)
  - `name` (string, required): Name of the holiday
  - `id` (string): Id of the tenant holiday
  - `recurring` (boolean): Every year on the same day
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `employeeCount` (integer): Number of employees in the tenant
- `federalStates` (array of FederalState): German states (Bundesländer) to choose from
  - `code` (string): ISO 3166-2 suffix of the state (BW, BY, …)
  - `name` (string): Name of the state
- `fields` (array of FieldDef): Employee field definitions
  - `key` (string, required): Stable key; the key in customFields
  - `kind` (string, required): Kind of value; `phone` takes digits, spaces and `+ ( ) / . -` (at least 3 digits, `+` only first, at most 40 characters), `email` the shape `local@domain.tld` (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `url`, `phone`, `email`)
  - `label` (string, required): Display name
  - `archived` (boolean): Archived: no longer offered for new data, kept for existing data
  - `description` (string): Help text of the field
  - `id` (string): Id of the field
  - `options` (array of object): Choices of select and multiselect fields
    - `color` (string): Colour of the choice
    - `label` (string): Display text of the choice
    - `value` (string): Stored value of the choice
  - `required` (boolean): A value is required
  - `restricted` (boolean): Values are visible only to callers with hr:write
  - `section` (string): Group in forms; defaults to other (one of `person`, `contact`, `employment`, `working_time`, `confidential`, `other`)
  - `sortOrder` (integer): Position within the section
  - `standard` (boolean, read-only): From the built-in catalogue; switched on and off with archived, key and kind are fixed
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
  - `visibleToColleagues` (boolean): Values are shown to every colleague in the directory (listColleagues); not together with restricted (400)
- `grantable` (array of string): Permissions the caller may grant or revoke
- `groups` (array of Group): Groups of the tenant
  - `name` (string, required): Name of the group
  - `description` (string): Description of the group
  - `id` (string): Id of the group
  - `memberCount` (integer, read-only): Number of members
  - `roleIds` (array of string, read-only): Ids of the roles the members receive
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `permissions` (array of object): The permission catalogue
  - `area` (string): Module or area the permission belongs to
  - `customerWide` (boolean): The permission applies to every tenant of the customer
  - `description` (string): What the permission allows
  - `key` (string): Permission name, e.g. hr:read
  - `label` (string): Display name
- `roles` (array of Role): Roles of the tenant
  - `name` (string, required): Name of the role
  - `description` (string): Description of the role
  - `id` (string): Id of the role
  - `key` (string, read-only): Stable key of the role
  - `locked` (boolean, read-only): Built-in role whose permissions cannot be changed
  - `memberCount` (integer, read-only): Number of employees holding the role
  - `permissions` (array of string): Permissions of the role
  - `systemKey` (string, read-only): Key of a built-in role, empty for roles of the tenant
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `sections` (array of object): Sections that group the fields in forms
  - `key` (string): Key of the section
  - `label` (string): Display name of the section
- `settings` (Settings)
  - `displayFields` (array of string): Field keys whose values make up the display name of employees
  - `loginDomains` (array of string): Lowercase FQDNs of the tenant. Omitted on save keeps the stored list. A domain belongs to one customer only (409 domain_taken).
  - `loginPolicy` (string): Omitted on save keeps the stored value. Default create_user. (one of `create_user`, `existing_only`)
  - `subdomain` (string): The tenant's label on the platform domain (`<subdomain>.on.<domain>`); its mail addresses hang below it. Unique on the platform, platform names (www, portal, mail, …) are reserved. Omitted or empty on save keeps the stored value; once set it cannot be changed (400, field subdomain). A subdomain another tenant has is 400 as well.
- `workSettings` (WorkSettings)
  - `absencesVisibleToColleagues` (boolean): Colleagues see each other's absences in the team calendar and presence; off: only the caller and the people they decide for
  - `autoEndAtMidnight` (boolean): A clock segment nobody clocked out of is ended at 24:00 of its day (tenant time zone) and marked `autoEnded` for checking. Off for tenants whose shifts run past midnight. (default `true`)
  - `carryoverExpiry` (string): MM-DD the previous year's vacation expires (default `"03-31"`)
  - `defaultDayMinutes` (array of integer): Target minutes Monday … Sunday without a working-time model
  - `defaultVacationDays` (number): Vacation days per year of employees without a working-time model
  - `federalState` (string): Bundesland code (BW, BY, …); empty = nationwide holidays only
  - `selfEditDays` (integer): Days back employees change their own time without a reason
  - `timeZone` (string): IANA time zone of the tenant, e.g. Europe/Berlin (default `"Europe/Berlin"`)
  - `trackingStart` (string (date)): First day time accounts count

Example 200 answer:

```json
{
  "absenceTypes": [
    {
      "allowHalfDays": true,
      "archived": false,
      "color": "primary",
      "countsAgainstVacation": true,
      "icon": "i-lucide-palmtree",
      "id": "8c0e2a4c-6e8a-4c0e-9a4c-6e8a0c2e4a13",
      "key": "vacation",
      "name": "Erholungsurlaub",
      "paid": true,
      "requiresApproval": true,
      "sensitive": false,
      "sortOrder": 10,
      "timeEffect": "credit",
      "version": 1
    }
  ],
  "customHolidays": [
    {
      "date": "2026-12-24",
      "fraction": 0.5,
      "id": "0e2a4c6e-8a0c-4e2a-8c6e-8a0c2e4a6c14",
      "name": "Heiligabend (halber Tag)",
      "recurring": true,
      "version": 1
    }
  ],
  "employeeCount": 26,
  "federalStates": [
    {
      "code": "BY",
      "name": "Bayern"
    },
    {
      "code": "BW",
      "name": "Baden-Württemberg"
    }
  ],
  "fields": [
    {
      "archived": false,
      "id": "4e6a8c0e-2a4c-4e6a-8c0e-2a4c6e8a0c11",
      "key": "first_name",
      "kind": "text",
      "label": "Vorname",
      "required": false,
      "restricted": false,
      "section": "person",
      "sortOrder": 10,
      "standard": true,
      "version": 1,
      "visibleToColleagues": false
    },
    {
      "archived": false,
      "id": "6a8c0e2a-4c6e-4a8c-9e2a-4c6e8a0c2e12",
      "key": "department",
      "kind": "select",
      "label": "Abteilung",
      "options": [
        {
          "label": "Service",
          "value": "service"
        },
        {
          "label": "Technik",
          "value": "technik"
        },
        {
          "label": "Vertrieb",
          "value": "vertrieb"
        }
      ],
      "required": false,
      "restricted": false,
      "section": "employment",
      "sortOrder": 20,
      "standard": true,
      "version": 2,
      "visibleToColleagues": false
    }
  ],
  "grantable": [
    "hr:read",
    "hr:write",
    "tenant:access"
  ],
  "groups": [
    {
      "description": "Erste Annahme und Bearbeitung von Tickets",
      "id": "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91",
      "memberCount": 4,
      "name": "Service Desk 1st Level",
      "roleIds": [],
      "version": 3
    }
  ],
  "permissions": [
    {
      "area": "hr",
      "customerWide": false,
      "description": "Mitarbeitende und ihre Felder ansehen.",
      "key": "hr:read",
      "label": "Personal lesen"
    }
  ],
  "roles": [
    {
      "description": "Portal, Tickets und CRM nutzen.",
      "id": "13e5a7c9-1d3f-4a5c-9e7a-9b1d3f5a7c82",
      "key": "viewer",
      "locked": false,
      "memberCount": 17,
      "name": "Mitarbeiter",
      "permissions": [
        "desk:read",
        "desk:write",
        "hr:absence:request",
        "hr:time:record",
        "tenant:access"
      ],
      "systemKey": "viewer",
      "version": 4
    }
  ],
  "sections": [
    {
      "key": "person",
      "label": "Person"
    },
    {
      "key": "contact",
      "label": "Kontakt"
    },
    {
      "key": "employment",
      "label": "Beschäftigung"
    }
  ],
  "settings": {
    "displayFields": [
      "first_name",
      "last_name"
    ],
    "loginDomains": [
      "muster-it.example"
    ],
    "loginPolicy": "existing_only",
    "subdomain": "demo"
  },
  "workSettings": {
    "absencesVisibleToColleagues": true,
    "autoEndAtMidnight": true,
    "carryoverExpiry": "03-31",
    "defaultDayMinutes": [
      480,
      480,
      480,
      480,
      480,
      0,
      0
    ],
    "defaultVacationDays": 30,
    "federalState": "BY",
    "selfEditDays": 14,
    "timeZone": "Europe/Berlin",
    "trackingStart": "2026-01-01"
  }
}
```

### Example request

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

## Save display and login settings (hr:admin)

`PUT /api/hr/v1/settings`

Module: HR · operationId: `setSettings` · Tag: Configuration · Auth: access token (`Authorization: Bearer <accessToken>`)

### Request body

`application/json` (required)

- `displayFields` (array of string): Field keys whose values make up the display name of employees
- `loginDomains` (array of string): Lowercase FQDNs of the tenant. Omitted on save keeps the stored list. A domain belongs to one customer only (409 domain_taken).
- `loginPolicy` (string): Omitted on save keeps the stored value. Default create_user. (one of `create_user`, `existing_only`)
- `subdomain` (string): The tenant's label on the platform domain (`<subdomain>.on.<domain>`); its mail addresses hang below it. Unique on the platform, platform names (www, portal, mail, …) are reserved. Omitted or empty on save keeps the stored value; once set it cannot be changed (400, field subdomain). A subdomain another tenant has is 400 as well.

Example:

```json
{
  "displayFields": [
    "first_name",
    "last_name"
  ],
  "loginDomains": [
    "muster-it.example"
  ],
  "loginPolicy": "existing_only",
  "subdomain": "demo"
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `displayFields` (array of string): Field keys whose values make up the display name of employees
- `loginDomains` (array of string): Lowercase FQDNs of the tenant. Omitted on save keeps the stored list. A domain belongs to one customer only (409 domain_taken).
- `loginPolicy` (string): Omitted on save keeps the stored value. Default create_user. (one of `create_user`, `existing_only`)
- `subdomain` (string): The tenant's label on the platform domain (`<subdomain>.on.<domain>`); its mail addresses hang below it. Unique on the platform, platform names (www, portal, mail, …) are reserved. Omitted or empty on save keeps the stored value; once set it cannot be changed (400, field subdomain). A subdomain another tenant has is 400 as well.

Example 200 answer:

```json
{
  "displayFields": [
    "first_name",
    "last_name"
  ],
  "loginDomains": [
    "muster-it.example"
  ],
  "loginPolicy": "existing_only",
  "subdomain": "demo"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/settings' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"displayFields":["first_name","last_name"],"loginDomains":["muster-it.example"],"loginPolicy":"existing_only","subdomain":"demo"}'
```

## Create an employee field (hr:admin)

`POST /api/hr/v1/fields`

Module: HR · operationId: `createField` · Tag: Configuration · Auth: access token (`Authorization: Bearer <accessToken>`)

### Request body

`application/json` (required)

- `key` (string, required): Stable key; the key in customFields
- `kind` (string, required): Kind of value; `phone` takes digits, spaces and `+ ( ) / . -` (at least 3 digits, `+` only first, at most 40 characters), `email` the shape `local@domain.tld` (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `url`, `phone`, `email`)
- `label` (string, required): Display name
- `archived` (boolean): Archived: no longer offered for new data, kept for existing data
- `description` (string): Help text of the field
- `id` (string): Id of the field
- `options` (array of object): Choices of select and multiselect fields
  - `color` (string): Colour of the choice
  - `label` (string): Display text of the choice
  - `value` (string): Stored value of the choice
- `required` (boolean): A value is required
- `restricted` (boolean): Values are visible only to callers with hr:write
- `section` (string): Group in forms; defaults to other (one of `person`, `contact`, `employment`, `working_time`, `confidential`, `other`)
- `sortOrder` (integer): Position within the section
- `standard` (boolean, read-only): From the built-in catalogue; switched on and off with archived, key and kind are fixed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `visibleToColleagues` (boolean): Values are shown to every colleague in the directory (listColleagues); not together with restricted (400)

Example:

```json
{
  "archived": false,
  "description": "Herstellerzertifikate, z. B. MS-102 oder CCNA",
  "id": "2c4e6a8c-0e2a-4c4e-8a6c-0e2a4c6e8a10",
  "key": "zertifizierungen",
  "kind": "multiselect",
  "label": "Zertifizierungen",
  "options": [
    {
      "color": "info",
      "label": "MS-102",
      "value": "ms_102"
    },
    {
      "color": "info",
      "label": "MD-102",
      "value": "md_102"
    },
    {
      "color": "success",
      "label": "CCNA",
      "value": "ccna"
    }
  ],
  "required": false,
  "restricted": false,
  "section": "employment",
  "sortOrder": 70,
  "standard": false,
  "version": 1,
  "visibleToColleagues": true
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `key` (string, required): Stable key; the key in customFields
- `kind` (string, required): Kind of value; `phone` takes digits, spaces and `+ ( ) / . -` (at least 3 digits, `+` only first, at most 40 characters), `email` the shape `local@domain.tld` (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `url`, `phone`, `email`)
- `label` (string, required): Display name
- `archived` (boolean): Archived: no longer offered for new data, kept for existing data
- `description` (string): Help text of the field
- `id` (string): Id of the field
- `options` (array of object): Choices of select and multiselect fields
  - `color` (string): Colour of the choice
  - `label` (string): Display text of the choice
  - `value` (string): Stored value of the choice
- `required` (boolean): A value is required
- `restricted` (boolean): Values are visible only to callers with hr:write
- `section` (string): Group in forms; defaults to other (one of `person`, `contact`, `employment`, `working_time`, `confidential`, `other`)
- `sortOrder` (integer): Position within the section
- `standard` (boolean, read-only): From the built-in catalogue; switched on and off with archived, key and kind are fixed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `visibleToColleagues` (boolean): Values are shown to every colleague in the directory (listColleagues); not together with restricted (400)

Example 201 answer:

```json
{
  "archived": false,
  "description": "Herstellerzertifikate, z. B. MS-102 oder CCNA",
  "id": "2c4e6a8c-0e2a-4c4e-8a6c-0e2a4c6e8a10",
  "key": "zertifizierungen",
  "kind": "multiselect",
  "label": "Zertifizierungen",
  "options": [
    {
      "color": "info",
      "label": "MS-102",
      "value": "ms_102"
    },
    {
      "color": "info",
      "label": "MD-102",
      "value": "md_102"
    },
    {
      "color": "success",
      "label": "CCNA",
      "value": "ccna"
    }
  ],
  "required": false,
  "restricted": false,
  "section": "employment",
  "sortOrder": 70,
  "standard": false,
  "version": 1,
  "visibleToColleagues": true
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/fields' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"archived":false,"description":"Herstellerzertifikate, z. B. MS-102 oder CCNA","id":"2c4e6a8c-0e2a-4c4e-8a6c-0e2a4c6e8a10","key":"zertifizierungen","kind":"multiselect","label":"Zertifizierungen","options":[{"color":"info","label":"MS-102","value":"ms_102"},{"color":"info","label":"MD-102","value":"md_102"},{"color":"success","label":"CCNA","value":"ccna"}],"required":false,"restricted":false,"section":"employment","sortOrder":70,"standard":false,"version":1,"visibleToColleagues":true}'
```

## Update an employee field (hr:admin); key and kind cannot change

`PUT /api/hr/v1/fields/{id}`

Module: HR · operationId: `updateField` · Tag: Configuration · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `key` (string, required): Stable key; the key in customFields
- `kind` (string, required): Kind of value; `phone` takes digits, spaces and `+ ( ) / . -` (at least 3 digits, `+` only first, at most 40 characters), `email` the shape `local@domain.tld` (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `url`, `phone`, `email`)
- `label` (string, required): Display name
- `archived` (boolean): Archived: no longer offered for new data, kept for existing data
- `description` (string): Help text of the field
- `id` (string): Id of the field
- `options` (array of object): Choices of select and multiselect fields
  - `color` (string): Colour of the choice
  - `label` (string): Display text of the choice
  - `value` (string): Stored value of the choice
- `required` (boolean): A value is required
- `restricted` (boolean): Values are visible only to callers with hr:write
- `section` (string): Group in forms; defaults to other (one of `person`, `contact`, `employment`, `working_time`, `confidential`, `other`)
- `sortOrder` (integer): Position within the section
- `standard` (boolean, read-only): From the built-in catalogue; switched on and off with archived, key and kind are fixed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `visibleToColleagues` (boolean): Values are shown to every colleague in the directory (listColleagues); not together with restricted (400)

Example:

```json
{
  "archived": false,
  "description": "Herstellerzertifikate, z. B. MS-102 oder CCNA",
  "id": "2c4e6a8c-0e2a-4c4e-8a6c-0e2a4c6e8a10",
  "key": "zertifizierungen",
  "kind": "multiselect",
  "label": "Zertifizierungen",
  "options": [
    {
      "color": "info",
      "label": "MS-102",
      "value": "ms_102"
    },
    {
      "color": "info",
      "label": "MD-102",
      "value": "md_102"
    },
    {
      "color": "success",
      "label": "CCNA",
      "value": "ccna"
    }
  ],
  "required": false,
  "restricted": false,
  "section": "employment",
  "sortOrder": 70,
  "standard": false,
  "version": 1,
  "visibleToColleagues": true
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `key` (string, required): Stable key; the key in customFields
- `kind` (string, required): Kind of value; `phone` takes digits, spaces and `+ ( ) / . -` (at least 3 digits, `+` only first, at most 40 characters), `email` the shape `local@domain.tld` (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `url`, `phone`, `email`)
- `label` (string, required): Display name
- `archived` (boolean): Archived: no longer offered for new data, kept for existing data
- `description` (string): Help text of the field
- `id` (string): Id of the field
- `options` (array of object): Choices of select and multiselect fields
  - `color` (string): Colour of the choice
  - `label` (string): Display text of the choice
  - `value` (string): Stored value of the choice
- `required` (boolean): A value is required
- `restricted` (boolean): Values are visible only to callers with hr:write
- `section` (string): Group in forms; defaults to other (one of `person`, `contact`, `employment`, `working_time`, `confidential`, `other`)
- `sortOrder` (integer): Position within the section
- `standard` (boolean, read-only): From the built-in catalogue; switched on and off with archived, key and kind are fixed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `visibleToColleagues` (boolean): Values are shown to every colleague in the directory (listColleagues); not together with restricted (400)

Example 200 answer:

```json
{
  "archived": false,
  "description": "Herstellerzertifikate, z. B. MS-102 oder CCNA",
  "id": "2c4e6a8c-0e2a-4c4e-8a6c-0e2a4c6e8a10",
  "key": "zertifizierungen",
  "kind": "multiselect",
  "label": "Zertifizierungen",
  "options": [
    {
      "color": "info",
      "label": "MS-102",
      "value": "ms_102"
    },
    {
      "color": "info",
      "label": "MD-102",
      "value": "md_102"
    },
    {
      "color": "success",
      "label": "CCNA",
      "value": "ccna"
    }
  ],
  "required": false,
  "restricted": false,
  "section": "employment",
  "sortOrder": 70,
  "standard": false,
  "version": 1,
  "visibleToColleagues": true
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/fields/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"archived":false,"description":"Herstellerzertifikate, z. B. MS-102 oder CCNA","id":"2c4e6a8c-0e2a-4c4e-8a6c-0e2a4c6e8a10","key":"zertifizierungen","kind":"multiselect","label":"Zertifizierungen","options":[{"color":"info","label":"MS-102","value":"ms_102"},{"color":"info","label":"MD-102","value":"md_102"},{"color":"success","label":"CCNA","value":"ccna"}],"required":false,"restricted":false,"section":"employment","sortOrder":70,"standard":false,"version":1,"visibleToColleagues":true}'
```

## Create an absence type (hr:admin)

`POST /api/hr/v1/absence-types`

Module: HR · operationId: `createAbsenceType` · Tag: Configuration · Auth: access token (`Authorization: Bearer <accessToken>`)

### Request body

`application/json` (required)

- `key` (string, required): Stable key of the type
- `name` (string, required): Display name
- `allowHalfDays` (boolean): Half days may be requested
- `archived` (boolean): Archived: no longer offered for new data, kept for existing data
- `color` (string): Semantic colour of the type in calendars (one of `primary`, `info`, `success`, `warning`, `error`, `neutral`)
- `countsAgainstVacation` (boolean): Days of this type are taken from the vacation account
- `icon` (string): Lucide icon (i-lucide-…)
- `id` (string): Id of the absence type
- `paid` (boolean): The absence is paid time
- `requiresApproval` (boolean): Requests start as requested and need a decision; otherwise they are approved when entered
- `sensitive` (boolean): Colleagues see only "abwesend"
- `sortOrder` (integer): Position in lists (ascending)
- `timeEffect` (string): credit: counts as worked; none: the time account pays (Überstundenabbau); reduce_target: no target (unpaid) (one of `credit`, `none`, `reduce_target`)
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example:

```json
{
  "allowHalfDays": false,
  "archived": false,
  "color": "info",
  "countsAgainstVacation": false,
  "icon": "i-lucide-school",
  "id": "1a3c5e7a-9c1e-4a3c-8e5a-7c9e1a3c5e15",
  "key": "berufsschule",
  "name": "Berufsschule",
  "paid": true,
  "requiresApproval": false,
  "sensitive": false,
  "sortOrder": 80,
  "timeEffect": "credit",
  "version": 1
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `key` (string, required): Stable key of the type
- `name` (string, required): Display name
- `allowHalfDays` (boolean): Half days may be requested
- `archived` (boolean): Archived: no longer offered for new data, kept for existing data
- `color` (string): Semantic colour of the type in calendars (one of `primary`, `info`, `success`, `warning`, `error`, `neutral`)
- `countsAgainstVacation` (boolean): Days of this type are taken from the vacation account
- `icon` (string): Lucide icon (i-lucide-…)
- `id` (string): Id of the absence type
- `paid` (boolean): The absence is paid time
- `requiresApproval` (boolean): Requests start as requested and need a decision; otherwise they are approved when entered
- `sensitive` (boolean): Colleagues see only "abwesend"
- `sortOrder` (integer): Position in lists (ascending)
- `timeEffect` (string): credit: counts as worked; none: the time account pays (Überstundenabbau); reduce_target: no target (unpaid) (one of `credit`, `none`, `reduce_target`)
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 201 answer:

```json
{
  "allowHalfDays": false,
  "archived": false,
  "color": "info",
  "countsAgainstVacation": false,
  "icon": "i-lucide-school",
  "id": "1a3c5e7a-9c1e-4a3c-8e5a-7c9e1a3c5e15",
  "key": "berufsschule",
  "name": "Berufsschule",
  "paid": true,
  "requiresApproval": false,
  "sensitive": false,
  "sortOrder": 80,
  "timeEffect": "credit",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/absence-types' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"allowHalfDays":false,"archived":false,"color":"info","countsAgainstVacation":false,"icon":"i-lucide-school","id":"1a3c5e7a-9c1e-4a3c-8e5a-7c9e1a3c5e15","key":"berufsschule","name":"Berufsschule","paid":true,"requiresApproval":false,"sensitive":false,"sortOrder":80,"timeEffect":"credit","version":1}'
```

## Change or archive an absence type (hr:admin)

`PUT /api/hr/v1/absence-types/{id}`

Module: HR · operationId: `updateAbsenceType` · Tag: Configuration · Auth: access token (`Authorization: Bearer <accessToken>`)

The key is fixed. Vacation and time-account effects cannot change once absences use the type (`409 in_use`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `key` (string, required): Stable key of the type
- `name` (string, required): Display name
- `allowHalfDays` (boolean): Half days may be requested
- `archived` (boolean): Archived: no longer offered for new data, kept for existing data
- `color` (string): Semantic colour of the type in calendars (one of `primary`, `info`, `success`, `warning`, `error`, `neutral`)
- `countsAgainstVacation` (boolean): Days of this type are taken from the vacation account
- `icon` (string): Lucide icon (i-lucide-…)
- `id` (string): Id of the absence type
- `paid` (boolean): The absence is paid time
- `requiresApproval` (boolean): Requests start as requested and need a decision; otherwise they are approved when entered
- `sensitive` (boolean): Colleagues see only "abwesend"
- `sortOrder` (integer): Position in lists (ascending)
- `timeEffect` (string): credit: counts as worked; none: the time account pays (Überstundenabbau); reduce_target: no target (unpaid) (one of `credit`, `none`, `reduce_target`)
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example:

```json
{
  "allowHalfDays": false,
  "archived": false,
  "color": "info",
  "countsAgainstVacation": false,
  "icon": "i-lucide-school",
  "id": "1a3c5e7a-9c1e-4a3c-8e5a-7c9e1a3c5e15",
  "key": "berufsschule",
  "name": "Berufsschule",
  "paid": true,
  "requiresApproval": false,
  "sensitive": false,
  "sortOrder": 80,
  "timeEffect": "credit",
  "version": 1
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `key` (string, required): Stable key of the type
- `name` (string, required): Display name
- `allowHalfDays` (boolean): Half days may be requested
- `archived` (boolean): Archived: no longer offered for new data, kept for existing data
- `color` (string): Semantic colour of the type in calendars (one of `primary`, `info`, `success`, `warning`, `error`, `neutral`)
- `countsAgainstVacation` (boolean): Days of this type are taken from the vacation account
- `icon` (string): Lucide icon (i-lucide-…)
- `id` (string): Id of the absence type
- `paid` (boolean): The absence is paid time
- `requiresApproval` (boolean): Requests start as requested and need a decision; otherwise they are approved when entered
- `sensitive` (boolean): Colleagues see only "abwesend"
- `sortOrder` (integer): Position in lists (ascending)
- `timeEffect` (string): credit: counts as worked; none: the time account pays (Überstundenabbau); reduce_target: no target (unpaid) (one of `credit`, `none`, `reduce_target`)
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "allowHalfDays": false,
  "archived": false,
  "color": "info",
  "countsAgainstVacation": false,
  "icon": "i-lucide-school",
  "id": "1a3c5e7a-9c1e-4a3c-8e5a-7c9e1a3c5e15",
  "key": "berufsschule",
  "name": "Berufsschule",
  "paid": true,
  "requiresApproval": false,
  "sensitive": false,
  "sortOrder": 80,
  "timeEffect": "credit",
  "version": 1
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/absence-types/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"allowHalfDays":false,"archived":false,"color":"info","countsAgainstVacation":false,"icon":"i-lucide-school","id":"1a3c5e7a-9c1e-4a3c-8e5a-7c9e1a3c5e15","key":"berufsschule","name":"Berufsschule","paid":true,"requiresApproval":false,"sensitive":false,"sortOrder":80,"timeEffect":"credit","version":1}'
```

## Public holidays of a Bundesland plus the tenant's own (tenant:access)

`GET /api/hr/v1/holidays`

Module: HR · operationId: `listHolidays` · Tag: Configuration · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `year` | query | integer |  |  |
| `state` | query | string |  | Bundesland code; defaults to the tenant's |

### Responses

- **200** Holidays (`application/json`)
- **400** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Holiday, required): Holidays of the year, by date
  - `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

Example 200 answer:

```json
{
  "items": [
    {
      "custom": false,
      "date": "2026-10-03",
      "fraction": 1,
      "name": "Tag der Deutschen Einheit"
    },
    {
      "custom": false,
      "date": "2026-11-01",
      "fraction": 1,
      "name": "Allerheiligen"
    },
    {
      "custom": true,
      "date": "2026-12-24",
      "fraction": 0.5,
      "name": "Heiligabend (halber Tag)"
    },
    {
      "custom": false,
      "date": "2026-12-25",
      "fraction": 1,
      "name": "1. Weihnachtstag"
    },
    {
      "custom": false,
      "date": "2026-12-26",
      "fraction": 1,
      "name": "2. Weihnachtstag"
    }
  ]
}
```

### Example request

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

## Add a tenant holiday (hr:admin)

`POST /api/hr/v1/custom-holidays`

Module: HR · operationId: `createCustomHoliday` · Tag: Configuration · Auth: access token (`Authorization: Bearer <accessToken>`)

### Request body

`application/json` (required)

- `date` (string (date), required): Date (YYYY-MM-DD)
- `fraction` (number, required): 1 for a full day, 0.5 for a half day (one of `0.5`, `1`)
- `name` (string, required): Name of the holiday
- `id` (string): Id of the tenant holiday
- `recurring` (boolean): Every year on the same day
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example:

```json
{
  "date": "2026-12-24",
  "fraction": 0.5,
  "id": "0e2a4c6e-8a0c-4e2a-8c6e-8a0c2e4a6c14",
  "name": "Heiligabend (halber Tag)",
  "recurring": true,
  "version": 1
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)

Fields of the 201 answer:

- `date` (string (date), required): Date (YYYY-MM-DD)
- `fraction` (number, required): 1 for a full day, 0.5 for a half day (one of `0.5`, `1`)
- `name` (string, required): Name of the holiday
- `id` (string): Id of the tenant holiday
- `recurring` (boolean): Every year on the same day
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 201 answer:

```json
{
  "date": "2026-12-24",
  "fraction": 0.5,
  "id": "0e2a4c6e-8a0c-4e2a-8c6e-8a0c2e4a6c14",
  "name": "Heiligabend (halber Tag)",
  "recurring": true,
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/custom-holidays' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"date":"2026-12-24","fraction":0.5,"id":"0e2a4c6e-8a0c-4e2a-8c6e-8a0c2e4a6c14","name":"Heiligabend (halber Tag)","recurring":true,"version":1}'
```

## Change a tenant holiday (hr:admin)

`PUT /api/hr/v1/custom-holidays/{id}`

Module: HR · operationId: `updateCustomHoliday` · Tag: Configuration · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `date` (string (date), required): Date (YYYY-MM-DD)
- `fraction` (number, required): 1 for a full day, 0.5 for a half day (one of `0.5`, `1`)
- `name` (string, required): Name of the holiday
- `id` (string): Id of the tenant holiday
- `recurring` (boolean): Every year on the same day
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example:

```json
{
  "date": "2026-12-24",
  "fraction": 0.5,
  "id": "0e2a4c6e-8a0c-4e2a-8c6e-8a0c2e4a6c14",
  "name": "Heiligabend (halber Tag)",
  "recurring": true,
  "version": 1
}
```

### Responses

- **200** Saved (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `date` (string (date), required): Date (YYYY-MM-DD)
- `fraction` (number, required): 1 for a full day, 0.5 for a half day (one of `0.5`, `1`)
- `name` (string, required): Name of the holiday
- `id` (string): Id of the tenant holiday
- `recurring` (boolean): Every year on the same day
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "date": "2026-12-24",
  "fraction": 0.5,
  "id": "0e2a4c6e-8a0c-4e2a-8c6e-8a0c2e4a6c14",
  "name": "Heiligabend (halber Tag)",
  "recurring": true,
  "version": 1
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/custom-holidays/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"date":"2026-12-24","fraction":0.5,"id":"0e2a4c6e-8a0c-4e2a-8c6e-8a0c2e4a6c14","name":"Heiligabend (halber Tag)","recurring":true,"version":1}'
```

## Remove a tenant holiday (hr:admin)

`DELETE /api/hr/v1/custom-holidays/{id}`

Module: HR · operationId: `deleteCustomHoliday` · Tag: Configuration · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Removed
- **404** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/hr/v1/custom-holidays/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Save the absence and working-time settings (hr:admin)

`PUT /api/hr/v1/work-settings`

Module: HR · operationId: `setWorkSettings` · Tag: Configuration · Auth: access token (`Authorization: Bearer <accessToken>`)

### Request body

`application/json` (required)

- `absencesVisibleToColleagues` (boolean): Colleagues see each other's absences in the team calendar and presence; off: only the caller and the people they decide for
- `autoEndAtMidnight` (boolean): A clock segment nobody clocked out of is ended at 24:00 of its day (tenant time zone) and marked `autoEnded` for checking. Off for tenants whose shifts run past midnight. (default `true`)
- `carryoverExpiry` (string): MM-DD the previous year's vacation expires (default `"03-31"`)
- `defaultDayMinutes` (array of integer): Target minutes Monday … Sunday without a working-time model
- `defaultVacationDays` (number): Vacation days per year of employees without a working-time model
- `federalState` (string): Bundesland code (BW, BY, …); empty = nationwide holidays only
- `selfEditDays` (integer): Days back employees change their own time without a reason
- `timeZone` (string): IANA time zone of the tenant, e.g. Europe/Berlin (default `"Europe/Berlin"`)
- `trackingStart` (string (date)): First day time accounts count

Example:

```json
{
  "absencesVisibleToColleagues": true,
  "autoEndAtMidnight": true,
  "carryoverExpiry": "03-31",
  "defaultDayMinutes": [
    480,
    480,
    480,
    480,
    480,
    0,
    0
  ],
  "defaultVacationDays": 30,
  "federalState": "BY",
  "selfEditDays": 14,
  "timeZone": "Europe/Berlin",
  "trackingStart": "2026-01-01"
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)

Fields of the 200 answer:

- `absencesVisibleToColleagues` (boolean): Colleagues see each other's absences in the team calendar and presence; off: only the caller and the people they decide for
- `autoEndAtMidnight` (boolean): A clock segment nobody clocked out of is ended at 24:00 of its day (tenant time zone) and marked `autoEnded` for checking. Off for tenants whose shifts run past midnight. (default `true`)
- `carryoverExpiry` (string): MM-DD the previous year's vacation expires (default `"03-31"`)
- `defaultDayMinutes` (array of integer): Target minutes Monday … Sunday without a working-time model
- `defaultVacationDays` (number): Vacation days per year of employees without a working-time model
- `federalState` (string): Bundesland code (BW, BY, …); empty = nationwide holidays only
- `selfEditDays` (integer): Days back employees change their own time without a reason
- `timeZone` (string): IANA time zone of the tenant, e.g. Europe/Berlin (default `"Europe/Berlin"`)
- `trackingStart` (string (date)): First day time accounts count

Example 200 answer:

```json
{
  "absencesVisibleToColleagues": true,
  "autoEndAtMidnight": true,
  "carryoverExpiry": "03-31",
  "defaultDayMinutes": [
    480,
    480,
    480,
    480,
    480,
    0,
    0
  ],
  "defaultVacationDays": 30,
  "federalState": "BY",
  "selfEditDays": 14,
  "timeZone": "Europe/Berlin",
  "trackingStart": "2026-01-01"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/work-settings' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"absencesVisibleToColleagues":true,"autoEndAtMidnight":true,"carryoverExpiry":"03-31","defaultDayMinutes":[480,480,480,480,480,0,0],"defaultVacationDays":30,"federalState":"BY","selfEditDays":14,"timeZone":"Europe/Berlin","trackingStart":"2026-01-01"}'
```

## Module configuration (tenant:settings:read)

`GET /api/hr/v1/config`

Module: HR · operationId: `getConfig` · Tag: Configuration · Auth: access token (`Authorization: Bearer <accessToken>`)

### Responses

- **200** Configuration (`application/json`)

Example 200 answer:

```json
{
  "active": true,
  "autoApproveSickLeaves": true,
  "defaultVacationDays": 30,
  "standardWeeklyHours": 40
}
```

### Example request

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

## Save the module configuration (tenant:settings:write)

`PUT /api/hr/v1/config`

Module: HR · operationId: `setConfig` · Tag: Configuration · Auth: access token (`Authorization: Bearer <accessToken>`)

The work settings (`work`) are not written here – a sent `work` part is ignored and the stored one stays; save them with `setWorkEntrySettings` (hr:work:manage).

### Request body

`application/json` (required)

Example:

```json
{
  "active": true,
  "autoApproveSickLeaves": true,
  "defaultVacationDays": 30,
  "standardWeeklyHours": 40
}
```

### Responses

- **200** Saved

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/config' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"active":true,"autoApproveSickLeaves":true,"defaultVacationDays":30,"standardWeeklyHours":40}'
```

# Employees

## The signed-in user's employee record in the active tenant

`GET /api/hr/v1/me`

Module: HR · operationId: `getMe` · Tag: Employees · Auth: access token (`Authorization: Bearer <accessToken>`)

### Responses

- **200** Employee (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `addressId` (string, read-only): Person address of the employee in masterdata (roles customer and supplier), kept by HR
- `addressUnmatched` (boolean, read-only): The masterdata address was deleted by the operator's microtech address import and the employee is not matched to a new one yet (addressId is empty; HR does not create one by itself). Omitted when false.
- `createdAt` (string (date-time)): When the employee was created
- `createdBy` (string): Who created the employee (e-mail of the caller)
- `customFields` (object): Values of the tenant-defined fields by field key; restricted fields only with hr:write
- `displayName` (string): Name built from the tenant's display fields (falls back to the e-mail)
- `email` (string): E-mail address; the sign-in identity
- `groupIds` (array of string): Ids of the groups the employee belongs to
- `id` (string): Id of the employee
- `invitationSent` (boolean): Only on create: whether the invitation mail was sent
- `lastLoginAt` (string (date-time)): Last sign-in
- `roleIds` (array of string): Ids of the directly assigned roles
- `status` (string): disabled employees cannot sign in (one of `active`, `disabled`)
- `tenantColor` (string): Only on getMe: the active tenant's colour (a portal tenant colour name such as blue), for the identity stripe of the app; omitted when masterdata does not answer
- `updatedAt` (string (date-time)): When the employee was last changed
- `updatedBy` (string): Who last changed the employee (e-mail of the caller)
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "addressId": "7e9a1c3e-5b7d-4f9a-8c1e-3b5d7f9a1c20",
  "addressUnmatched": false,
  "createdAt": "2023-10-12T09:14:00Z",
  "createdBy": "clara.becker@muster-it.example",
  "customFields": {
    "department": "service",
    "employment_type": "vollzeit",
    "entry_date": "2023-11-02",
    "first_name": "Sophie",
    "last_name": "Huber",
    "personnel_number": "1017",
    "phone": "+49 941 123450-17",
    "position": "Service Desk Agentin"
  },
  "displayName": "Sophie Huber",
  "email": "sophie.huber@muster-it.example",
  "groupIds": [
    "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91"
  ],
  "id": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "lastLoginAt": "2026-11-19T07:28:41Z",
  "roleIds": [
    "13e5a7c9-1d3f-4a5c-9e7a-9b1d3f5a7c82"
  ],
  "status": "active",
  "updatedAt": "2026-09-01T08:02:00Z",
  "updatedBy": "clara.becker@muster-it.example",
  "version": 6
}
```

### Example request

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

## List employees (hr:read)

`GET /api/hr/v1/employees`

Module: HR · operationId: `listEmployees` · Tag: Employees · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `q` | query | string |  | Searches email and non-restricted text fields |
| `status` | query | string |  | (one of `active`, `disabled`) |
| `groupId` | query | string |  |  |
| `roleId` | query | string |  | Direct or through a group |
| `orgUnitId` | query | string |  | Only employees of this org unit |
| `subUnits` | query | boolean |  | Include the unit's sub-units |
| `team` | query | string |  | `mine` = only the people the caller is responsible for (one of `mine`) |
| `sort` | query | string |  | `email`, `status`, `createdAt`, `updatedAt` or `cf.<key>`; prefix `-` for descending |
| `limit` | query | integer |  | 1–200; another value is a 400 invalid. (default `50`; max 200) |
| `offset` | query | integer |  | (default `0`) |

### Responses

- **200** A page of employees (`application/json`)

Fields of the 200 answer:

- `items` (array of Employee): Employees of this page
  - `addressId` (string, read-only): Person address of the employee in masterdata (roles customer and supplier), kept by HR
  - `addressUnmatched` (boolean, read-only): The masterdata address was deleted by the operator's microtech address import and the employee is not matched to a new one yet (addressId is empty; HR does not create one by itself). Omitted when false.
  - `createdAt` (string (date-time)): When the employee was created
  - `createdBy` (string): Who created the employee (e-mail of the caller)
  - `customFields` (object): Values of the tenant-defined fields by field key; restricted fields only with hr:write
  - `displayName` (string): Name built from the tenant's display fields (falls back to the e-mail)
  - `email` (string): E-mail address; the sign-in identity
  - `groupIds` (array of string): Ids of the groups the employee belongs to
  - `id` (string): Id of the employee
  - `invitationSent` (boolean): Only on create: whether the invitation mail was sent
  - `lastLoginAt` (string (date-time)): Last sign-in
  - `roleIds` (array of string): Ids of the directly assigned roles
  - `status` (string): disabled employees cannot sign in (one of `active`, `disabled`)
  - `tenantColor` (string): Only on getMe: the active tenant's colour (a portal tenant colour name such as blue), for the identity stripe of the app; omitted when masterdata does not answer
  - `updatedAt` (string (date-time)): When the employee was last changed
  - `updatedBy` (string): Who last changed the employee (e-mail of the caller)
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `total` (integer): Number of all matching employees

Example 200 answer:

```json
{
  "items": [
    {
      "addressId": "7e9a1c3e-5b7d-4f9a-8c1e-3b5d7f9a1c20",
      "addressUnmatched": false,
      "createdAt": "2023-10-12T09:14:00Z",
      "createdBy": "clara.becker@muster-it.example",
      "customFields": {
        "department": "service",
        "entry_date": "2023-11-02",
        "first_name": "Sophie",
        "last_name": "Huber",
        "personnel_number": "1017",
        "phone": "+49 941 123450-17",
        "position": "Service Desk Agentin"
      },
      "displayName": "Sophie Huber",
      "email": "sophie.huber@muster-it.example",
      "groupIds": [
        "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91"
      ],
      "id": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "lastLoginAt": "2026-11-19T07:28:41Z",
      "roleIds": [
        "13e5a7c9-1d3f-4a5c-9e7a-9b1d3f5a7c82"
      ],
      "status": "active",
      "updatedAt": "2026-09-01T08:02:00Z",
      "updatedBy": "clara.becker@muster-it.example",
      "version": 6
    },
    {
      "addressId": "9a1c3e5b-7d9f-4a1c-8e3b-5d7f9a1c3e22",
      "addressUnmatched": false,
      "createdAt": "2024-10-21T13:40:00Z",
      "createdBy": "clara.becker@muster-it.example",
      "customFields": {
        "department": "service",
        "entry_date": "2024-11-04",
        "first_name": "Elias",
        "last_name": "Gruber",
        "mobile": "+49 160 2230054",
        "personnel_number": "1021",
        "position": "Service Desk Agent"
      },
      "displayName": "Elias Gruber",
      "email": "elias.gruber@muster-it.example",
      "groupIds": [
        "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91",
        "23c5e7a9-1b3d-4f5a-9c7e-9b1d3f5a7c92"
      ],
      "id": "c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06",
      "lastLoginAt": "2026-11-18T07:02:13Z",
      "roleIds": [
        "13e5a7c9-1d3f-4a5c-9e7a-9b1d3f5a7c82"
      ],
      "status": "active",
      "updatedAt": "2025-11-03T09:15:00Z",
      "updatedBy": "clara.becker@muster-it.example",
      "version": 3
    }
  ],
  "total": 2
}
```

### Example request

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

## Create an employee (hr:write; roles and groups need identity:admin)

`POST /api/hr/v1/employees`

Module: HR · operationId: `createEmployee` · Tag: Employees · Auth: access token (`Authorization: Bearer <accessToken>`)

### Request body

`application/json` (required)

- `email` (string (email), required): E-mail address; the sign-in identity, unique in the tenant
- `customFields` (object): Values of the tenant-defined fields by field key
- `groupIds` (array of string): Ids of the groups to add the employee to (needs identity:admin)
- `roleIds` (array of string): Ids of the roles to assign directly (needs identity:admin)
- `sendInvitation` (boolean): Email a one-time link to register a passkey

Example:

```json
{
  "customFields": {
    "department": "service",
    "employment_type": "ausbildung",
    "entry_date": "2026-03-02",
    "first_name": "Noah",
    "last_name": "Fischer",
    "personnel_number": "1024",
    "position": "Auszubildender Fachinformatiker"
  },
  "email": "noah.fischer@muster-it.example",
  "groupIds": [
    "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91"
  ],
  "roleIds": [
    "13e5a7c9-1d3f-4a5c-9e7a-9b1d3f5a7c82"
  ],
  "sendInvitation": false
}
```

### Responses

- **201** Created; `invitationSent` reports the invitation when requested (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)

Fields of the 201 answer:

- `addressId` (string, read-only): Person address of the employee in masterdata (roles customer and supplier), kept by HR
- `addressUnmatched` (boolean, read-only): The masterdata address was deleted by the operator's microtech address import and the employee is not matched to a new one yet (addressId is empty; HR does not create one by itself). Omitted when false.
- `createdAt` (string (date-time)): When the employee was created
- `createdBy` (string): Who created the employee (e-mail of the caller)
- `customFields` (object): Values of the tenant-defined fields by field key; restricted fields only with hr:write
- `displayName` (string): Name built from the tenant's display fields (falls back to the e-mail)
- `email` (string): E-mail address; the sign-in identity
- `groupIds` (array of string): Ids of the groups the employee belongs to
- `id` (string): Id of the employee
- `invitationSent` (boolean): Only on create: whether the invitation mail was sent
- `lastLoginAt` (string (date-time)): Last sign-in
- `roleIds` (array of string): Ids of the directly assigned roles
- `status` (string): disabled employees cannot sign in (one of `active`, `disabled`)
- `tenantColor` (string): Only on getMe: the active tenant's colour (a portal tenant colour name such as blue), for the identity stripe of the app; omitted when masterdata does not answer
- `updatedAt` (string (date-time)): When the employee was last changed
- `updatedBy` (string): Who last changed the employee (e-mail of the caller)
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 201 answer:

```json
{
  "addressId": "7e9a1c3e-5b7d-4f9a-8c1e-3b5d7f9a1c20",
  "addressUnmatched": false,
  "createdAt": "2023-10-12T09:14:00Z",
  "createdBy": "clara.becker@muster-it.example",
  "customFields": {
    "department": "service",
    "employment_type": "vollzeit",
    "entry_date": "2023-11-02",
    "first_name": "Sophie",
    "last_name": "Huber",
    "personnel_number": "1017",
    "phone": "+49 941 123450-17",
    "position": "Service Desk Agentin"
  },
  "displayName": "Sophie Huber",
  "email": "sophie.huber@muster-it.example",
  "groupIds": [
    "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91"
  ],
  "id": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "lastLoginAt": "2026-11-19T07:28:41Z",
  "roleIds": [
    "13e5a7c9-1d3f-4a5c-9e7a-9b1d3f5a7c82"
  ],
  "status": "active",
  "updatedAt": "2026-09-01T08:02:00Z",
  "updatedBy": "clara.becker@muster-it.example",
  "version": 6
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/employees' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"customFields":{"department":"service","employment_type":"ausbildung","entry_date":"2026-03-02","first_name":"Noah","last_name":"Fischer","personnel_number":"1024","position":"Auszubildender Fachinformatiker"},"email":"noah.fischer@muster-it.example","groupIds":["21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91"],"roleIds":["13e5a7c9-1d3f-4a5c-9e7a-9b1d3f5a7c82"],"sendInvitation":false}'
```

## Get an employee (hr:read, the person themself, or their managers and deputies)

`GET /api/hr/v1/employees/{id}`

Module: HR · operationId: `getEmployee` · Tag: Employees · Auth: access token (`Authorization: Bearer <accessToken>`)

Managers and deputies in the chain of command read their team's records; restricted fields stay hidden unless the caller has hr:write. People outside the caller's scope answer `404`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Employee (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `addressId` (string, read-only): Person address of the employee in masterdata (roles customer and supplier), kept by HR
- `addressUnmatched` (boolean, read-only): The masterdata address was deleted by the operator's microtech address import and the employee is not matched to a new one yet (addressId is empty; HR does not create one by itself). Omitted when false.
- `createdAt` (string (date-time)): When the employee was created
- `createdBy` (string): Who created the employee (e-mail of the caller)
- `customFields` (object): Values of the tenant-defined fields by field key; restricted fields only with hr:write
- `displayName` (string): Name built from the tenant's display fields (falls back to the e-mail)
- `email` (string): E-mail address; the sign-in identity
- `groupIds` (array of string): Ids of the groups the employee belongs to
- `id` (string): Id of the employee
- `invitationSent` (boolean): Only on create: whether the invitation mail was sent
- `lastLoginAt` (string (date-time)): Last sign-in
- `roleIds` (array of string): Ids of the directly assigned roles
- `status` (string): disabled employees cannot sign in (one of `active`, `disabled`)
- `tenantColor` (string): Only on getMe: the active tenant's colour (a portal tenant colour name such as blue), for the identity stripe of the app; omitted when masterdata does not answer
- `updatedAt` (string (date-time)): When the employee was last changed
- `updatedBy` (string): Who last changed the employee (e-mail of the caller)
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "addressId": "7e9a1c3e-5b7d-4f9a-8c1e-3b5d7f9a1c20",
  "addressUnmatched": false,
  "createdAt": "2023-10-12T09:14:00Z",
  "createdBy": "clara.becker@muster-it.example",
  "customFields": {
    "department": "service",
    "employment_type": "vollzeit",
    "entry_date": "2023-11-02",
    "first_name": "Sophie",
    "last_name": "Huber",
    "personnel_number": "1017",
    "phone": "+49 941 123450-17",
    "position": "Service Desk Agentin"
  },
  "displayName": "Sophie Huber",
  "email": "sophie.huber@muster-it.example",
  "groupIds": [
    "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91"
  ],
  "id": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "lastLoginAt": "2026-11-19T07:28:41Z",
  "roleIds": [
    "13e5a7c9-1d3f-4a5c-9e7a-9b1d3f5a7c82"
  ],
  "status": "active",
  "updatedAt": "2026-09-01T08:02:00Z",
  "updatedBy": "clara.becker@muster-it.example",
  "version": 6
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/employees/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Update email and fields (hr:write; changing the email needs identity:admin)

`PATCH /api/hr/v1/employees/{id}`

Module: HR · operationId: `updateEmployee` · Tag: Employees · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `version` (integer, required): Version of the employee the change is based on
- `customFields` (object): Keys to change; `null` clears a value
- `email` (string (email)): New e-mail address (needs identity:admin)

Example:

```json
{
  "customFields": {
    "cost_center": null,
    "phone": "+49 941 123450-27",
    "position": "Service Desk Agentin (2nd Level)"
  },
  "version": 6
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `addressId` (string, read-only): Person address of the employee in masterdata (roles customer and supplier), kept by HR
- `addressUnmatched` (boolean, read-only): The masterdata address was deleted by the operator's microtech address import and the employee is not matched to a new one yet (addressId is empty; HR does not create one by itself). Omitted when false.
- `createdAt` (string (date-time)): When the employee was created
- `createdBy` (string): Who created the employee (e-mail of the caller)
- `customFields` (object): Values of the tenant-defined fields by field key; restricted fields only with hr:write
- `displayName` (string): Name built from the tenant's display fields (falls back to the e-mail)
- `email` (string): E-mail address; the sign-in identity
- `groupIds` (array of string): Ids of the groups the employee belongs to
- `id` (string): Id of the employee
- `invitationSent` (boolean): Only on create: whether the invitation mail was sent
- `lastLoginAt` (string (date-time)): Last sign-in
- `roleIds` (array of string): Ids of the directly assigned roles
- `status` (string): disabled employees cannot sign in (one of `active`, `disabled`)
- `tenantColor` (string): Only on getMe: the active tenant's colour (a portal tenant colour name such as blue), for the identity stripe of the app; omitted when masterdata does not answer
- `updatedAt` (string (date-time)): When the employee was last changed
- `updatedBy` (string): Who last changed the employee (e-mail of the caller)
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "addressId": "7e9a1c3e-5b7d-4f9a-8c1e-3b5d7f9a1c20",
  "addressUnmatched": false,
  "createdAt": "2023-10-12T09:14:00Z",
  "createdBy": "clara.becker@muster-it.example",
  "customFields": {
    "department": "service",
    "employment_type": "vollzeit",
    "entry_date": "2023-11-02",
    "first_name": "Sophie",
    "last_name": "Huber",
    "personnel_number": "1017",
    "phone": "+49 941 123450-17",
    "position": "Service Desk Agentin"
  },
  "displayName": "Sophie Huber",
  "email": "sophie.huber@muster-it.example",
  "groupIds": [
    "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91"
  ],
  "id": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "lastLoginAt": "2026-11-19T07:28:41Z",
  "roleIds": [
    "13e5a7c9-1d3f-4a5c-9e7a-9b1d3f5a7c82"
  ],
  "status": "active",
  "updatedAt": "2026-09-01T08:02:00Z",
  "updatedBy": "clara.becker@muster-it.example",
  "version": 6
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/hr/v1/employees/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"customFields":{"cost_center":null,"phone":"+49 941 123450-27","position":"Service Desk Agentin (2nd Level)"},"version":6}'
```

## List the employee's accounts in NFON and TeamViewer (hr:write)

`GET /api/hr/v1/employees/{id}/linked-accounts`

Module: HR · operationId: `listEmployeeLinkedAccounts` · Tag: Employees · Auth: access token (`Authorization: Bearer <accessToken>`)

The accounts comms links to the employee's e-mail (ADR 0039: comms keeps the links, HR decides who sees and changes them) and the providers that know accounts. TeamViewer accounts are learned by comms from the TeamViewer user's e-mail (`learned`); a person corrects them here. An employee without e-mail has none.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Linked accounts (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **503** comms is not configured or not reachable (`linked_accounts_unavailable`) (`application/json`)

Fields of the 200 answer:

- `items` (array of LinkedAccount, required): Linked accounts of the employee
  - `key` (string, required): The provider's id of the account (NFON extension, TeamViewer user id)
  - `learned` (boolean, required): comms linked it by itself (TeamViewer e-mail); false: a person set it
  - `provider` (string, required): The provider of the account (one of `nfon`, `teamviewer`)
  - `updatedAt` (string (date-time), required): When the link was last set
  - `label` (string): The account's name in the provider, when known
- `providers` (array of LinkedAccountProvider, required): The providers and what they offer
  - `candidates` (boolean, required): The provider's accounts can be listed to pick from (listLinkedAccountCandidates)
  - `connected` (boolean, required): The tenant connected the provider in comms (Settings › Integrations)
  - `provider` (string, required): The provider (one of `nfon`, `teamviewer`)

Example 200 answer:

```json
{
  "items": [
    {
      "key": "217",
      "label": "Sophie Huber",
      "learned": false,
      "provider": "nfon",
      "updatedAt": "2026-10-05T10:12:00Z"
    },
    {
      "key": "u98765432",
      "label": "Sophie Huber",
      "learned": true,
      "provider": "teamviewer",
      "updatedAt": "2026-10-07T14:31:00Z"
    }
  ],
  "providers": [
    {
      "candidates": true,
      "connected": true,
      "provider": "nfon"
    },
    {
      "candidates": true,
      "connected": true,
      "provider": "teamviewer"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/employees/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/linked-accounts' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Link an NFON or TeamViewer account to the employee (hr:write)

`PUT /api/hr/v1/employees/{id}/linked-accounts`

Module: HR · operationId: `linkEmployeeAccount` · Tag: Employees · Auth: access token (`Authorization: Bearer <accessToken>`)

Sets the account as the employee's (by the employee's e-mail). An account linked to another person moves to this employee; a link set here is never replaced by a learned one.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `key` (string, required): The provider's id of the account (NFON extension, TeamViewer user id); surrounding spaces are removed (max length 256)
- `provider` (string, required): The provider of the account (one of `nfon`, `teamviewer`)

Example:

```json
{
  "key": "217",
  "provider": "nfon"
}
```

### Responses

- **204** Linked
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** The tenant has not connected the provider (`provider_not_connected`) (`application/json`)
- **422** The account cannot be linked (`linked_account_rejected`) or the employee has no e-mail (`employee_without_email`) (`application/json`)
- **503** comms is not configured or not reachable (`linked_accounts_unavailable`) (`application/json`)

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/employees/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/linked-accounts' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"key":"217","provider":"nfon"}'
```

## Remove an NFON or TeamViewer account from the employee (hr:write)

`DELETE /api/hr/v1/employees/{id}/linked-accounts/{provider}/{key}`

Module: HR · operationId: `unlinkEmployeeAccount` · Tag: Employees · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `provider` | path | string | yes | The provider of the account (one of `nfon`, `teamviewer`) |
| `key` | path | string | yes | The provider's id of the account (NFON extension, TeamViewer user id) (max length 256) |

### Responses

- **204** Removed
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** The employee does not exist or has no such account (`application/json`)
- **409** The tenant has not connected the provider (`provider_not_connected`) (`application/json`)
- **503** comms is not configured or not reachable (`linked_accounts_unavailable`) (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/hr/v1/employees/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/linked-accounts/nfon/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List a provider's accounts to link to employees (hr:write)

`GET /api/hr/v1/linked-accounts/candidates`

Module: HR · operationId: `listLinkedAccountCandidates` · Tag: Employees · Auth: access token (`Authorization: Bearer <accessToken>`)

Read live from the provider by comms, with the e-mail of the person each account is linked to.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `provider` | query | string | yes | The provider (one of `nfon`, `teamviewer`) |

### Responses

- **200** Accounts (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **409** The tenant has not connected the provider (`provider_not_connected`) (`application/json`)
- **503** comms is not configured or not reachable (`linked_accounts_unavailable`) (`application/json`)

Fields of the 200 answer:

- `items` (array of LinkedAccountCandidate, required): The provider's accounts
  - `key` (string, required): The provider's id of the account
  - `label` (string, required): The account's name in the provider
  - `email` (string): The account's e-mail in the provider, when known
  - `person` (string): E-mail of the person the account is linked to; empty: not linked

Example 200 answer:

```json
{
  "items": [
    {
      "email": "sophie.huber@muster-it.example",
      "key": "217",
      "label": "Sophie Huber",
      "person": "sophie.huber@muster-it.example"
    },
    {
      "key": "221",
      "label": "Elias Gruber",
      "person": "elias.gruber@muster-it.example"
    },
    {
      "key": "230",
      "label": "Empfang Zentrale",
      "person": ""
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/linked-accounts/candidates?provider=nfon' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Access

## Disable an employee (identity:admin); revokes open invitations

`POST /api/hr/v1/employees/{id}/disable`

Module: HR · operationId: `disableEmployee` · Tag: Access · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Disabled (`application/json`)
- **403** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `addressId` (string, read-only): Person address of the employee in masterdata (roles customer and supplier), kept by HR
- `addressUnmatched` (boolean, read-only): The masterdata address was deleted by the operator's microtech address import and the employee is not matched to a new one yet (addressId is empty; HR does not create one by itself). Omitted when false.
- `createdAt` (string (date-time)): When the employee was created
- `createdBy` (string): Who created the employee (e-mail of the caller)
- `customFields` (object): Values of the tenant-defined fields by field key; restricted fields only with hr:write
- `displayName` (string): Name built from the tenant's display fields (falls back to the e-mail)
- `email` (string): E-mail address; the sign-in identity
- `groupIds` (array of string): Ids of the groups the employee belongs to
- `id` (string): Id of the employee
- `invitationSent` (boolean): Only on create: whether the invitation mail was sent
- `lastLoginAt` (string (date-time)): Last sign-in
- `roleIds` (array of string): Ids of the directly assigned roles
- `status` (string): disabled employees cannot sign in (one of `active`, `disabled`)
- `tenantColor` (string): Only on getMe: the active tenant's colour (a portal tenant colour name such as blue), for the identity stripe of the app; omitted when masterdata does not answer
- `updatedAt` (string (date-time)): When the employee was last changed
- `updatedBy` (string): Who last changed the employee (e-mail of the caller)
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "addressId": "7e9a1c3e-5b7d-4f9a-8c1e-3b5d7f9a1c20",
  "addressUnmatched": false,
  "createdAt": "2023-10-12T09:14:00Z",
  "createdBy": "clara.becker@muster-it.example",
  "customFields": {
    "department": "service",
    "employment_type": "vollzeit",
    "entry_date": "2023-11-02",
    "first_name": "Sophie",
    "last_name": "Huber",
    "personnel_number": "1017",
    "phone": "+49 941 123450-17",
    "position": "Service Desk Agentin"
  },
  "displayName": "Sophie Huber",
  "email": "sophie.huber@muster-it.example",
  "groupIds": [
    "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91"
  ],
  "id": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "lastLoginAt": "2026-11-19T07:28:41Z",
  "roleIds": [
    "13e5a7c9-1d3f-4a5c-9e7a-9b1d3f5a7c82"
  ],
  "status": "active",
  "updatedAt": "2026-09-01T08:02:00Z",
  "updatedBy": "clara.becker@muster-it.example",
  "version": 6
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/employees/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/disable' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Enable an employee (identity:admin)

`POST /api/hr/v1/employees/{id}/enable`

Module: HR · operationId: `enableEmployee` · Tag: Access · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Enabled (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `addressId` (string, read-only): Person address of the employee in masterdata (roles customer and supplier), kept by HR
- `addressUnmatched` (boolean, read-only): The masterdata address was deleted by the operator's microtech address import and the employee is not matched to a new one yet (addressId is empty; HR does not create one by itself). Omitted when false.
- `createdAt` (string (date-time)): When the employee was created
- `createdBy` (string): Who created the employee (e-mail of the caller)
- `customFields` (object): Values of the tenant-defined fields by field key; restricted fields only with hr:write
- `displayName` (string): Name built from the tenant's display fields (falls back to the e-mail)
- `email` (string): E-mail address; the sign-in identity
- `groupIds` (array of string): Ids of the groups the employee belongs to
- `id` (string): Id of the employee
- `invitationSent` (boolean): Only on create: whether the invitation mail was sent
- `lastLoginAt` (string (date-time)): Last sign-in
- `roleIds` (array of string): Ids of the directly assigned roles
- `status` (string): disabled employees cannot sign in (one of `active`, `disabled`)
- `tenantColor` (string): Only on getMe: the active tenant's colour (a portal tenant colour name such as blue), for the identity stripe of the app; omitted when masterdata does not answer
- `updatedAt` (string (date-time)): When the employee was last changed
- `updatedBy` (string): Who last changed the employee (e-mail of the caller)
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "addressId": "7e9a1c3e-5b7d-4f9a-8c1e-3b5d7f9a1c20",
  "addressUnmatched": false,
  "createdAt": "2023-10-12T09:14:00Z",
  "createdBy": "clara.becker@muster-it.example",
  "customFields": {
    "department": "service",
    "employment_type": "vollzeit",
    "entry_date": "2023-11-02",
    "first_name": "Sophie",
    "last_name": "Huber",
    "personnel_number": "1017",
    "phone": "+49 941 123450-17",
    "position": "Service Desk Agentin"
  },
  "displayName": "Sophie Huber",
  "email": "sophie.huber@muster-it.example",
  "groupIds": [
    "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91"
  ],
  "id": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "lastLoginAt": "2026-11-19T07:28:41Z",
  "roleIds": [
    "13e5a7c9-1d3f-4a5c-9e7a-9b1d3f5a7c82"
  ],
  "status": "active",
  "updatedAt": "2026-09-01T08:02:00Z",
  "updatedBy": "clara.becker@muster-it.example",
  "version": 6
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/employees/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/enable' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Replace the direct roles (identity:admin)

`PUT /api/hr/v1/employees/{id}/roles`

Module: HR · operationId: `setEmployeeRoles` · Tag: Access · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `ids` (array of string): The ids

Example:

```json
{
  "ids": [
    "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
    "c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06",
    "d1f3b5c7-9e1a-4d3f-8b5c-7a9e1f3b5d08"
  ]
}
```

### Responses

- **200** Saved (`application/json`)
- **403** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `addressId` (string, read-only): Person address of the employee in masterdata (roles customer and supplier), kept by HR
- `addressUnmatched` (boolean, read-only): The masterdata address was deleted by the operator's microtech address import and the employee is not matched to a new one yet (addressId is empty; HR does not create one by itself). Omitted when false.
- `createdAt` (string (date-time)): When the employee was created
- `createdBy` (string): Who created the employee (e-mail of the caller)
- `customFields` (object): Values of the tenant-defined fields by field key; restricted fields only with hr:write
- `displayName` (string): Name built from the tenant's display fields (falls back to the e-mail)
- `email` (string): E-mail address; the sign-in identity
- `groupIds` (array of string): Ids of the groups the employee belongs to
- `id` (string): Id of the employee
- `invitationSent` (boolean): Only on create: whether the invitation mail was sent
- `lastLoginAt` (string (date-time)): Last sign-in
- `roleIds` (array of string): Ids of the directly assigned roles
- `status` (string): disabled employees cannot sign in (one of `active`, `disabled`)
- `tenantColor` (string): Only on getMe: the active tenant's colour (a portal tenant colour name such as blue), for the identity stripe of the app; omitted when masterdata does not answer
- `updatedAt` (string (date-time)): When the employee was last changed
- `updatedBy` (string): Who last changed the employee (e-mail of the caller)
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "addressId": "7e9a1c3e-5b7d-4f9a-8c1e-3b5d7f9a1c20",
  "addressUnmatched": false,
  "createdAt": "2023-10-12T09:14:00Z",
  "createdBy": "clara.becker@muster-it.example",
  "customFields": {
    "department": "service",
    "employment_type": "vollzeit",
    "entry_date": "2023-11-02",
    "first_name": "Sophie",
    "last_name": "Huber",
    "personnel_number": "1017",
    "phone": "+49 941 123450-17",
    "position": "Service Desk Agentin"
  },
  "displayName": "Sophie Huber",
  "email": "sophie.huber@muster-it.example",
  "groupIds": [
    "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91"
  ],
  "id": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "lastLoginAt": "2026-11-19T07:28:41Z",
  "roleIds": [
    "13e5a7c9-1d3f-4a5c-9e7a-9b1d3f5a7c82"
  ],
  "status": "active",
  "updatedAt": "2026-09-01T08:02:00Z",
  "updatedBy": "clara.becker@muster-it.example",
  "version": 6
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/employees/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/roles' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"ids":["e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02","c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06","d1f3b5c7-9e1a-4d3f-8b5c-7a9e1f3b5d08"]}'
```

## Replace the groups (identity:admin)

`PUT /api/hr/v1/employees/{id}/groups`

Module: HR · operationId: `setEmployeeGroups` · Tag: Access · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `ids` (array of string): The ids

Example:

```json
{
  "ids": [
    "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
    "c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06",
    "d1f3b5c7-9e1a-4d3f-8b5c-7a9e1f3b5d08"
  ]
}
```

### Responses

- **200** Saved (`application/json`)
- **403** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `addressId` (string, read-only): Person address of the employee in masterdata (roles customer and supplier), kept by HR
- `addressUnmatched` (boolean, read-only): The masterdata address was deleted by the operator's microtech address import and the employee is not matched to a new one yet (addressId is empty; HR does not create one by itself). Omitted when false.
- `createdAt` (string (date-time)): When the employee was created
- `createdBy` (string): Who created the employee (e-mail of the caller)
- `customFields` (object): Values of the tenant-defined fields by field key; restricted fields only with hr:write
- `displayName` (string): Name built from the tenant's display fields (falls back to the e-mail)
- `email` (string): E-mail address; the sign-in identity
- `groupIds` (array of string): Ids of the groups the employee belongs to
- `id` (string): Id of the employee
- `invitationSent` (boolean): Only on create: whether the invitation mail was sent
- `lastLoginAt` (string (date-time)): Last sign-in
- `roleIds` (array of string): Ids of the directly assigned roles
- `status` (string): disabled employees cannot sign in (one of `active`, `disabled`)
- `tenantColor` (string): Only on getMe: the active tenant's colour (a portal tenant colour name such as blue), for the identity stripe of the app; omitted when masterdata does not answer
- `updatedAt` (string (date-time)): When the employee was last changed
- `updatedBy` (string): Who last changed the employee (e-mail of the caller)
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "addressId": "7e9a1c3e-5b7d-4f9a-8c1e-3b5d7f9a1c20",
  "addressUnmatched": false,
  "createdAt": "2023-10-12T09:14:00Z",
  "createdBy": "clara.becker@muster-it.example",
  "customFields": {
    "department": "service",
    "employment_type": "vollzeit",
    "entry_date": "2023-11-02",
    "first_name": "Sophie",
    "last_name": "Huber",
    "personnel_number": "1017",
    "phone": "+49 941 123450-17",
    "position": "Service Desk Agentin"
  },
  "displayName": "Sophie Huber",
  "email": "sophie.huber@muster-it.example",
  "groupIds": [
    "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91"
  ],
  "id": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "lastLoginAt": "2026-11-19T07:28:41Z",
  "roleIds": [
    "13e5a7c9-1d3f-4a5c-9e7a-9b1d3f5a7c82"
  ],
  "status": "active",
  "updatedAt": "2026-09-01T08:02:00Z",
  "updatedBy": "clara.becker@muster-it.example",
  "version": 6
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/employees/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/groups' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"ids":["e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02","c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06","d1f3b5c7-9e1a-4d3f-8b5c-7a9e1f3b5d08"]}'
```

## Effective permissions with their sources (identity:admin)

`GET /api/hr/v1/employees/{id}/access`

Module: HR · operationId: `getEmployeeAccess` · Tag: Access · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Access (`application/json`)

Fields of the 200 answer:

- `permissions` (array of object): Effective permissions, sorted
  - `permission` (string): The permission
  - `sources` (array of object): Roles that grant it, directly or through a group
    - `groupId` (string): Id of the group the role comes through (omitted for a direct role)
    - `groupName` (string): Name of that group
    - `roleId` (string): Id of the role
    - `roleName` (string): Name of the role

Example 200 answer:

```json
{
  "permissions": [
    {
      "permission": "desk:write",
      "sources": [
        {
          "groupId": "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91",
          "groupName": "Service Desk 1st Level",
          "roleId": "31b3d5f7-9a1c-4e3b-8d5f-7a9c1e3b5d40",
          "roleName": "Service Desk"
        }
      ]
    },
    {
      "permission": "tenant:access",
      "sources": [
        {
          "roleId": "13e5a7c9-1d3f-4a5c-9e7a-9b1d3f5a7c82",
          "roleName": "Mitarbeiter"
        },
        {
          "groupId": "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91",
          "groupName": "Service Desk 1st Level",
          "roleId": "31b3d5f7-9a1c-4e3b-8d5f-7a9c1e3b5d40",
          "roleName": "Service Desk"
        }
      ]
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/employees/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/access' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## How the employee can sign in (identity:admin); never contains credentials

`GET /api/hr/v1/employees/{id}/sign-in`

Module: HR · operationId: `getEmployeeSignIn` · Tag: Access · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Sign-in summary (`application/json`)

Fields of the 200 answer:

- `invitationExpiresAt` (string (date-time)): When the open invitation expires
- `invitationOpen` (boolean): An invitation link is open
- `lastLoginAt` (string (date-time)): Last sign-in
- `microsoftLinked` (boolean): A Microsoft account is linked
- `passkeyCount` (integer): Number of registered passkeys

Example 200 answer:

```json
{
  "invitationOpen": false,
  "lastLoginAt": "2026-11-19T07:28:41Z",
  "microsoftLinked": true,
  "passkeyCount": 2
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/employees/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/sign-in' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Email a one-time passkey registration link (identity:admin)

`POST /api/hr/v1/employees/{id}/invitation`

Module: HR · operationId: `inviteEmployee` · Tag: Access · Auth: access token (`Authorization: Bearer <accessToken>`)

Earlier open links are revoked. The link is only sent by email and never returned.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Sent
- **400** Error (`application/json`)
- **503** Error (`application/json`)

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/employees/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/invitation' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create a role (identity:admin)

`POST /api/hr/v1/roles`

Module: HR · operationId: `createRole` · Tag: Access · Auth: access token (`Authorization: Bearer <accessToken>`)

### Request body

`application/json` (required)

- `name` (string, required): Name of the role
- `description` (string): Description of the role
- `id` (string): Id of the role
- `key` (string, read-only): Stable key of the role
- `locked` (boolean, read-only): Built-in role whose permissions cannot be changed
- `memberCount` (integer, read-only): Number of employees holding the role
- `permissions` (array of string): Permissions of the role
- `systemKey` (string, read-only): Key of a built-in role, empty for roles of the tenant
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example:

```json
{
  "description": "Tickets bearbeiten, Wissen lesen, eigene Zeiten und Abwesenheiten erfassen.",
  "id": "31b3d5f7-9a1c-4e3b-8d5f-7a9c1e3b5d40",
  "locked": false,
  "memberCount": 4,
  "name": "Service Desk",
  "permissions": [
    "desk:read",
    "desk:write",
    "hr:absence:request",
    "hr:time:record",
    "tenant:access",
    "tenant:knowledge:read"
  ],
  "version": 2
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)

Fields of the 201 answer:

- `name` (string, required): Name of the role
- `description` (string): Description of the role
- `id` (string): Id of the role
- `key` (string, read-only): Stable key of the role
- `locked` (boolean, read-only): Built-in role whose permissions cannot be changed
- `memberCount` (integer, read-only): Number of employees holding the role
- `permissions` (array of string): Permissions of the role
- `systemKey` (string, read-only): Key of a built-in role, empty for roles of the tenant
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 201 answer:

```json
{
  "description": "Tickets bearbeiten, Wissen lesen, eigene Zeiten und Abwesenheiten erfassen.",
  "id": "31b3d5f7-9a1c-4e3b-8d5f-7a9c1e3b5d40",
  "locked": false,
  "memberCount": 4,
  "name": "Service Desk",
  "permissions": [
    "desk:read",
    "desk:write",
    "hr:absence:request",
    "hr:time:record",
    "tenant:access",
    "tenant:knowledge:read"
  ],
  "version": 2
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/roles' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"description":"Tickets bearbeiten, Wissen lesen, eigene Zeiten und Abwesenheiten erfassen.","id":"31b3d5f7-9a1c-4e3b-8d5f-7a9c1e3b5d40","locked":false,"memberCount":4,"name":"Service Desk","permissions":["desk:read","desk:write","hr:absence:request","hr:time:record","tenant:access","tenant:knowledge:read"],"version":2}'
```

## Update a role (identity:admin); the Administrator role keeps its permissions

`PUT /api/hr/v1/roles/{id}`

Module: HR · operationId: `updateRole` · Tag: Access · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `name` (string, required): Name of the role
- `description` (string): Description of the role
- `id` (string): Id of the role
- `key` (string, read-only): Stable key of the role
- `locked` (boolean, read-only): Built-in role whose permissions cannot be changed
- `memberCount` (integer, read-only): Number of employees holding the role
- `permissions` (array of string): Permissions of the role
- `systemKey` (string, read-only): Key of a built-in role, empty for roles of the tenant
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example:

```json
{
  "description": "Tickets bearbeiten, Wissen lesen, eigene Zeiten und Abwesenheiten erfassen.",
  "id": "31b3d5f7-9a1c-4e3b-8d5f-7a9c1e3b5d40",
  "locked": false,
  "memberCount": 4,
  "name": "Service Desk",
  "permissions": [
    "desk:read",
    "desk:write",
    "hr:absence:request",
    "hr:time:record",
    "tenant:access",
    "tenant:knowledge:read"
  ],
  "version": 2
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `name` (string, required): Name of the role
- `description` (string): Description of the role
- `id` (string): Id of the role
- `key` (string, read-only): Stable key of the role
- `locked` (boolean, read-only): Built-in role whose permissions cannot be changed
- `memberCount` (integer, read-only): Number of employees holding the role
- `permissions` (array of string): Permissions of the role
- `systemKey` (string, read-only): Key of a built-in role, empty for roles of the tenant
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "description": "Tickets bearbeiten, Wissen lesen, eigene Zeiten und Abwesenheiten erfassen.",
  "id": "31b3d5f7-9a1c-4e3b-8d5f-7a9c1e3b5d40",
  "locked": false,
  "memberCount": 4,
  "name": "Service Desk",
  "permissions": [
    "desk:read",
    "desk:write",
    "hr:absence:request",
    "hr:time:record",
    "tenant:access",
    "tenant:knowledge:read"
  ],
  "version": 2
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/roles/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"description":"Tickets bearbeiten, Wissen lesen, eigene Zeiten und Abwesenheiten erfassen.","id":"31b3d5f7-9a1c-4e3b-8d5f-7a9c1e3b5d40","locked":false,"memberCount":4,"name":"Service Desk","permissions":["desk:read","desk:write","hr:absence:request","hr:time:record","tenant:access","tenant:knowledge:read"],"version":2}'
```

## Delete a role (identity:admin)

`DELETE /api/hr/v1/roles/{id}`

Module: HR · operationId: `deleteRole` · Tag: Access · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **403** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/hr/v1/roles/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Names of the tenant's groups (tenant:access)

`GET /api/hr/v1/groups`

Module: HR · operationId: `listGroups` · Tag: Access · Auth: access token (`Authorization: Bearer <accessToken>`)

Id and name of every group of the active tenant, sorted by name. Sessions carry only the group ids (`groupMemberships`); this resolves them to names. No members, no roles.

### Responses

- **200** Groups (`application/json`)
- **401** Error (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of GroupName, required): The tenant's groups
  - `id` (string (uuid), required): Id of the group
  - `name` (string, required): Name of the group

Example 200 answer:

```json
{
  "items": [
    {
      "id": "23c5e7a9-1b3d-4f5a-9c7e-9b1d3f5a7c92",
      "name": "Bereitschaft"
    },
    {
      "id": "25e7a9c1-3d5f-4a7c-8e9b-1d3f5a7c9e93",
      "name": "ER Freigabe"
    },
    {
      "id": "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91",
      "name": "Service Desk 1st Level"
    },
    {
      "id": "27a9c1e3-5f7a-4c9e-9b1d-3f5a7c9e1b94",
      "name": "Service Desk 2nd Level"
    }
  ]
}
```

### Example request

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

## Create a group (identity:admin)

`POST /api/hr/v1/groups`

Module: HR · operationId: `createGroup` · Tag: Access · Auth: access token (`Authorization: Bearer <accessToken>`)

### Request body

`application/json` (required)

- `name` (string, required): Name of the group
- `description` (string): Description of the group
- `id` (string): Id of the group
- `memberCount` (integer, read-only): Number of members
- `roleIds` (array of string, read-only): Ids of the roles the members receive
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example:

```json
{
  "description": "Erste Annahme und Bearbeitung von Tickets",
  "id": "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91",
  "memberCount": 4,
  "name": "Service Desk 1st Level",
  "roleIds": [
    "31b3d5f7-9a1c-4e3b-8d5f-7a9c1e3b5d40"
  ],
  "version": 3
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)

Fields of the 201 answer:

- `name` (string, required): Name of the group
- `description` (string): Description of the group
- `id` (string): Id of the group
- `memberCount` (integer, read-only): Number of members
- `roleIds` (array of string, read-only): Ids of the roles the members receive
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 201 answer:

```json
{
  "description": "Erste Annahme und Bearbeitung von Tickets",
  "id": "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91",
  "memberCount": 4,
  "name": "Service Desk 1st Level",
  "roleIds": [
    "31b3d5f7-9a1c-4e3b-8d5f-7a9c1e3b5d40"
  ],
  "version": 3
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/groups' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"description":"Erste Annahme und Bearbeitung von Tickets","id":"21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91","memberCount":4,"name":"Service Desk 1st Level","roleIds":["31b3d5f7-9a1c-4e3b-8d5f-7a9c1e3b5d40"],"version":3}'
```

## Rename a group (identity:admin)

`PUT /api/hr/v1/groups/{id}`

Module: HR · operationId: `updateGroup` · Tag: Access · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `name` (string, required): Name of the group
- `description` (string): Description of the group
- `id` (string): Id of the group
- `memberCount` (integer, read-only): Number of members
- `roleIds` (array of string, read-only): Ids of the roles the members receive
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example:

```json
{
  "description": "Erste Annahme und Bearbeitung von Tickets",
  "id": "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91",
  "memberCount": 4,
  "name": "Service Desk 1st Level",
  "roleIds": [
    "31b3d5f7-9a1c-4e3b-8d5f-7a9c1e3b5d40"
  ],
  "version": 3
}
```

### Responses

- **200** Saved (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `name` (string, required): Name of the group
- `description` (string): Description of the group
- `id` (string): Id of the group
- `memberCount` (integer, read-only): Number of members
- `roleIds` (array of string, read-only): Ids of the roles the members receive
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "description": "Erste Annahme und Bearbeitung von Tickets",
  "id": "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91",
  "memberCount": 4,
  "name": "Service Desk 1st Level",
  "roleIds": [
    "31b3d5f7-9a1c-4e3b-8d5f-7a9c1e3b5d40"
  ],
  "version": 3
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/groups/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"description":"Erste Annahme und Bearbeitung von Tickets","id":"21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91","memberCount":4,"name":"Service Desk 1st Level","roleIds":["31b3d5f7-9a1c-4e3b-8d5f-7a9c1e3b5d40"],"version":3}'
```

## Delete a group (identity:admin)

`DELETE /api/hr/v1/groups/{id}`

Module: HR · operationId: `deleteGroup` · Tag: Access · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **403** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/hr/v1/groups/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Member ids of a group (identity:admin)

`GET /api/hr/v1/groups/{id}/members`

Module: HR · operationId: `listGroupMembers` · Tag: Access · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Members (`application/json`)

Fields of the 200 answer:

- `ids` (array of string): The ids

Example 200 answer:

```json
{
  "ids": [
    "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
    "c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06",
    "d1f3b5c7-9e1a-4d3f-8b5c-7a9e1f3b5d08"
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/groups/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/members' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Replace the members of a group (identity:admin)

`PUT /api/hr/v1/groups/{id}/members`

Module: HR · operationId: `setGroupMembers` · Tag: Access · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `ids` (array of string): The ids

Example:

```json
{
  "ids": [
    "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
    "c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06",
    "d1f3b5c7-9e1a-4d3f-8b5c-7a9e1f3b5d08"
  ]
}
```

### Responses

- **200** Saved (`application/json`)
- **403** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `name` (string, required): Name of the group
- `description` (string): Description of the group
- `id` (string): Id of the group
- `memberCount` (integer, read-only): Number of members
- `roleIds` (array of string, read-only): Ids of the roles the members receive
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "description": "Erste Annahme und Bearbeitung von Tickets",
  "id": "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91",
  "memberCount": 4,
  "name": "Service Desk 1st Level",
  "roleIds": [
    "31b3d5f7-9a1c-4e3b-8d5f-7a9c1e3b5d40"
  ],
  "version": 3
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/groups/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/members' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"ids":["e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02","c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06","d1f3b5c7-9e1a-4d3f-8b5c-7a9e1f3b5d08"]}'
```

## Replace the roles of a group (identity:admin)

`PUT /api/hr/v1/groups/{id}/roles`

Module: HR · operationId: `setGroupRoles` · Tag: Access · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `ids` (array of string): The ids

Example:

```json
{
  "ids": [
    "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
    "c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06",
    "d1f3b5c7-9e1a-4d3f-8b5c-7a9e1f3b5d08"
  ]
}
```

### Responses

- **200** Saved (`application/json`)
- **403** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `name` (string, required): Name of the group
- `description` (string): Description of the group
- `id` (string): Id of the group
- `memberCount` (integer, read-only): Number of members
- `roleIds` (array of string, read-only): Ids of the roles the members receive
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "description": "Erste Annahme und Bearbeitung von Tickets",
  "id": "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91",
  "memberCount": 4,
  "name": "Service Desk 1st Level",
  "roleIds": [
    "31b3d5f7-9a1c-4e3b-8d5f-7a9c1e3b5d40"
  ],
  "version": 3
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/groups/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/roles' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"ids":["e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02","c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06","d1f3b5c7-9e1a-4d3f-8b5c-7a9e1f3b5d08"]}'
```

# Absences

## Absence types, holidays and working-time settings (tenant:access)

`GET /api/hr/v1/work-config`

Module: HR · operationId: `getWorkConfig` · Tag: Absences · Auth: access token (`Authorization: Bearer <accessToken>`)

### Responses

- **200** Configuration (`application/json`)

Fields of the 200 answer:

- `absenceTypes` (array of AbsenceType): Absence types of the tenant
  - `key` (string, required): Stable key of the type
  - `name` (string, required): Display name
  - `allowHalfDays` (boolean): Half days may be requested
  - `archived` (boolean): Archived: no longer offered for new data, kept for existing data
  - `color` (string): Semantic colour of the type in calendars (one of `primary`, `info`, `success`, `warning`, `error`, `neutral`)
  - `countsAgainstVacation` (boolean): Days of this type are taken from the vacation account
  - `icon` (string): Lucide icon (i-lucide-…)
  - `id` (string): Id of the absence type
  - `paid` (boolean): The absence is paid time
  - `requiresApproval` (boolean): Requests start as requested and need a decision; otherwise they are approved when entered
  - `sensitive` (boolean): Colleagues see only "abwesend"
  - `sortOrder` (integer): Position in lists (ascending)
  - `timeEffect` (string): credit: counts as worked; none: the time account pays (Überstundenabbau); reduce_target: no target (unpaid) (one of `credit`, `none`, `reduce_target`)
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `customHolidays` (array of CustomHoliday): The tenant's own holidays
  - `date` (string (date), required): Date (YYYY-MM-DD)
  - `fraction` (number, required): 1 for a full day, 0.5 for a half day (one of `0.5`, `1`)
  - `name` (string, required): Name of the holiday
  - `id` (string): Id of the tenant holiday
  - `recurring` (boolean): Every year on the same day
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `federalStates` (array of FederalState): German states (Bundesländer) to choose from
  - `code` (string): ISO 3166-2 suffix of the state (BW, BY, …)
  - `name` (string): Name of the state
- `workSettings` (WorkSettings)
  - `absencesVisibleToColleagues` (boolean): Colleagues see each other's absences in the team calendar and presence; off: only the caller and the people they decide for
  - `autoEndAtMidnight` (boolean): A clock segment nobody clocked out of is ended at 24:00 of its day (tenant time zone) and marked `autoEnded` for checking. Off for tenants whose shifts run past midnight. (default `true`)
  - `carryoverExpiry` (string): MM-DD the previous year's vacation expires (default `"03-31"`)
  - `defaultDayMinutes` (array of integer): Target minutes Monday … Sunday without a working-time model
  - `defaultVacationDays` (number): Vacation days per year of employees without a working-time model
  - `federalState` (string): Bundesland code (BW, BY, …); empty = nationwide holidays only
  - `selfEditDays` (integer): Days back employees change their own time without a reason
  - `timeZone` (string): IANA time zone of the tenant, e.g. Europe/Berlin (default `"Europe/Berlin"`)
  - `trackingStart` (string (date)): First day time accounts count

Example 200 answer:

```json
{
  "absenceTypes": [
    {
      "allowHalfDays": true,
      "archived": false,
      "color": "primary",
      "countsAgainstVacation": true,
      "icon": "i-lucide-palmtree",
      "id": "8c0e2a4c-6e8a-4c0e-9a4c-6e8a0c2e4a13",
      "key": "vacation",
      "name": "Erholungsurlaub",
      "paid": true,
      "requiresApproval": true,
      "sensitive": false,
      "sortOrder": 10,
      "timeEffect": "credit",
      "version": 1
    },
    {
      "allowHalfDays": true,
      "archived": false,
      "color": "error",
      "countsAgainstVacation": false,
      "icon": "i-lucide-thermometer",
      "id": "9e2a4c6e-8a0c-4e2a-9c6e-8a0c2e4a6c16",
      "key": "sick",
      "name": "Krankheit",
      "paid": true,
      "requiresApproval": false,
      "sensitive": true,
      "sortOrder": 20,
      "timeEffect": "credit",
      "version": 1
    }
  ],
  "customHolidays": [
    {
      "date": "2026-12-24",
      "fraction": 0.5,
      "id": "0e2a4c6e-8a0c-4e2a-8c6e-8a0c2e4a6c14",
      "name": "Heiligabend (halber Tag)",
      "recurring": true,
      "version": 1
    }
  ],
  "federalStates": [
    {
      "code": "BY",
      "name": "Bayern"
    },
    {
      "code": "BW",
      "name": "Baden-Württemberg"
    }
  ],
  "workSettings": {
    "absencesVisibleToColleagues": true,
    "autoEndAtMidnight": true,
    "carryoverExpiry": "03-31",
    "defaultDayMinutes": [
      480,
      480,
      480,
      480,
      480,
      0,
      0
    ],
    "defaultVacationDays": 30,
    "federalState": "BY",
    "selfEditDays": 14,
    "timeZone": "Europe/Berlin",
    "trackingStart": "2026-01-01"
  }
}
```

### Example request

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

## List absences

`GET /api/hr/v1/absences`

Module: HR · operationId: `listAbsences` · Tag: Absences · Auth: access token (`Authorization: Bearer <accessToken>`)

Tenant-wide approvers (hr:absence:approve) see everybody's absences, managers their own and those of the people they are responsible for (chain of command and deputies), everyone else only their own.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `orgUnitId` | query | string |  | Only people of this org unit |
| `subUnits` | query | boolean |  | Include the unit's sub-units |
| `team` | query | string |  | `mine` = only the people the caller is responsible for (one of `mine`) |
| `responsible` | query | string |  | `me` = requests where the caller should act first (first available manager or their deputy; for tenant-wide approvers also requests nobody else can decide) (one of `me`) |
| `employeeId` | query | string |  |  |
| `status` | query | string |  | Comma-separated statuses |
| `typeId` | query | string |  |  |
| `from` | query | string (date) |  | Absences ending on or after this date |
| `to` | query | string (date) |  | Absences starting on or before this date |
| `limit` | query | integer |  | 1–200; another value is a 400 invalid. (default `50`; max 200) |
| `offset` | query | integer |  | (default `0`) |

### Responses

- **200** A page of absences, latest first (`application/json`)
- **400** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Absence): Absences of this page
  - `createdAt` (string (date-time)): When the absence was created
  - `createdBy` (string): Who entered the absence (e-mail of the caller; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
  - `days` (number): Working days (halves allowed)
  - `decidedAt` (string (date-time)): When it was decided last
  - `decidedBy` (string): Who decided last (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
  - `decisionNote` (string): Note of the last decision (e.g. the reason of a rejection)
  - `employeeId` (string): Id of the employee
  - `employeeName` (string): Display name of the employee (in lists)
  - `endDate` (string (date)): Last day (YYYY-MM-DD), inclusive
  - `endHalf` (boolean): The last day is only the morning
  - `id` (string): Id of the absence
  - `note` (string): The employee's note
  - `startDate` (string (date)): First day (YYYY-MM-DD)
  - `startHalf` (boolean): The first day is only the afternoon
  - `status` (string): State of the absence; types without approval start as approved (one of `requested`, `approved`, `rejected`, `cancelled`, `cancellation_requested`)
  - `typeId` (string): Id of the absence type
  - `updatedAt` (string (date-time)): When the absence was last changed
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `total` (integer): Number of all matching absences

Example 200 answer:

```json
{
  "items": [
    {
      "createdAt": "2026-11-16T08:12:00Z",
      "createdBy": "sophie.huber@muster-it.example",
      "days": 5,
      "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "employeeName": "Sophie Huber",
      "endDate": "2026-12-18",
      "endHalf": false,
      "id": "3e5a7c9e-1a3c-4e5a-8c7e-9a1c3e5a7c31",
      "note": "Städtereise Wien",
      "startDate": "2026-12-14",
      "startHalf": false,
      "status": "requested",
      "typeId": "8c0e2a4c-6e8a-4c0e-9a4c-6e8a0c2e4a13",
      "updatedAt": "2026-11-16T08:12:00Z",
      "version": 1
    },
    {
      "createdAt": "2026-09-21T14:40:00Z",
      "createdBy": "sophie.huber@muster-it.example",
      "days": 3,
      "decidedAt": "2026-09-22T10:05:00Z",
      "decidedBy": "martin.brandl@muster-it.example",
      "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "employeeName": "Sophie Huber",
      "endDate": "2026-10-09",
      "endHalf": false,
      "id": "5a7c9e1a-3c5e-4a7c-9e1a-3c5e7a9c1e32",
      "note": "Brückentage",
      "startDate": "2026-10-07",
      "startHalf": false,
      "status": "approved",
      "typeId": "8c0e2a4c-6e8a-4c0e-9a4c-6e8a0c2e4a13",
      "updatedAt": "2026-09-22T10:05:00Z",
      "version": 2
    }
  ],
  "total": 2
}
```

### Example request

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

## Request an absence (own, or for anyone with hr:absence:approve)

`POST /api/hr/v1/absences`

Module: HR · operationId: `requestAbsence` · Tag: Absences · Auth: access token (`Authorization: Bearer <accessToken>`)

Types without approval, and absences an approver enters for someone else, are approved
right away. Fails with `409 overlap` when another active absence overlaps, `409 period_closed`
when a closed month is touched and `400` when vacation days are missing.

### Request body

`application/json` (required)

- `endDate` (string (date), required): Last day (YYYY-MM-DD), inclusive
- `startDate` (string (date), required): First day (YYYY-MM-DD)
- `typeId` (string, required): Id of the absence type
- `employeeId` (string): Defaults to the caller
- `endHalf` (boolean): The last day is only the morning
- `note` (string): Note of the employee (max length 2000)
- `startHalf` (boolean): The first day is only the afternoon
- `version` (integer): Required for PATCH

Example:

```json
{
  "endDate": "2026-12-18",
  "endHalf": false,
  "note": "Städtereise Wien",
  "startDate": "2026-12-14",
  "startHalf": false,
  "typeId": "8c0e2a4c-6e8a-4c0e-9a4c-6e8a0c2e4a13"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `createdAt` (string (date-time)): When the absence was created
- `createdBy` (string): Who entered the absence (e-mail of the caller; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `days` (number): Working days (halves allowed)
- `decidedAt` (string (date-time)): When it was decided last
- `decidedBy` (string): Who decided last (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `decisionNote` (string): Note of the last decision (e.g. the reason of a rejection)
- `employeeId` (string): Id of the employee
- `employeeName` (string): Display name of the employee (in lists)
- `endDate` (string (date)): Last day (YYYY-MM-DD), inclusive
- `endHalf` (boolean): The last day is only the morning
- `id` (string): Id of the absence
- `note` (string): The employee's note
- `startDate` (string (date)): First day (YYYY-MM-DD)
- `startHalf` (boolean): The first day is only the afternoon
- `status` (string): State of the absence; types without approval start as approved (one of `requested`, `approved`, `rejected`, `cancelled`, `cancellation_requested`)
- `typeId` (string): Id of the absence type
- `updatedAt` (string (date-time)): When the absence was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 201 answer:

```json
{
  "createdAt": "2026-11-16T08:12:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "days": 5,
  "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "employeeName": "Sophie Huber",
  "endDate": "2026-12-18",
  "endHalf": false,
  "id": "3e5a7c9e-1a3c-4e5a-8c7e-9a1c3e5a7c31",
  "note": "Städtereise Wien",
  "startDate": "2026-12-14",
  "startHalf": false,
  "status": "requested",
  "typeId": "8c0e2a4c-6e8a-4c0e-9a4c-6e8a0c2e4a13",
  "updatedAt": "2026-11-16T08:12:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/absences' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"endDate":"2026-12-18","endHalf":false,"note":"Städtereise Wien","startDate":"2026-12-14","startHalf":false,"typeId":"8c0e2a4c-6e8a-4c0e-9a4c-6e8a0c2e4a13"}'
```

## Team calendar (tenant:access)

`GET /api/hr/v1/absences/calendar`

Module: HR · operationId: `getAbsenceCalendar` · Tag: Absences · Auth: access token (`Authorization: Bearer <accessToken>`)

Active employees and their absences in a range of at most 93 days. Without
hr:absence:approve colleagues' absences come without type for sensitive types and only
when approved; with `absencesVisibleToColleagues` off only the caller is listed.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `from` | query | string (date) | yes |  |
| `to` | query | string (date) | yes |  |
| `groupId` | query | string |  |  |
| `orgUnitId` | query | string |  | Only people of this org unit |
| `subUnits` | query | boolean |  | Include the unit's sub-units |
| `team` | query | string |  | `mine` = only the people the caller is responsible for (one of `mine`) |

### Responses

- **200** Calendar (`application/json`)
- **400** Error (`application/json`)

Fields of the 200 answer:

- `employees` (array of object): People shown in the calendar
  - `id` (string): Id of the employee
  - `name` (string): Display name of the employee
- `entries` (array of object): Absences in the range
  - `employeeId` (string): Id of the employee
  - `employeeName` (string): Display name of the employee
  - `endDate` (string (date)): Last day (YYYY-MM-DD), inclusive
  - `endHalf` (boolean): The last day is only the morning
  - `id` (string): Empty for colleagues' absences
  - `startDate` (string (date)): First day (YYYY-MM-DD)
  - `startHalf` (boolean): The first day is only the afternoon
  - `status` (string): State of the absence
  - `typeId` (string): Empty when the viewer may not see the type
- `from` (string (date)): First day of the range (YYYY-MM-DD)
- `holidays` (array of Holiday): Holidays in the range
  - `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
- `to` (string (date)): Last day of the range (YYYY-MM-DD)

Example 200 answer:

```json
{
  "employees": [
    {
      "id": "c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06",
      "name": "Elias Gruber"
    },
    {
      "id": "d1f3b5c7-9e1a-4d3f-8b5c-7a9e1f3b5d08",
      "name": "Hannah Lehner"
    },
    {
      "id": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "name": "Sophie Huber"
    }
  ],
  "entries": [
    {
      "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "employeeName": "Sophie Huber",
      "endDate": "2026-12-18",
      "endHalf": false,
      "id": "3e5a7c9e-1a3c-4e5a-8c7e-9a1c3e5a7c31",
      "startDate": "2026-12-14",
      "startHalf": false,
      "status": "requested",
      "typeId": "8c0e2a4c-6e8a-4c0e-9a4c-6e8a0c2e4a13"
    },
    {
      "employeeId": "d1f3b5c7-9e1a-4d3f-8b5c-7a9e1f3b5d08",
      "employeeName": "Hannah Lehner",
      "endDate": "2026-12-04",
      "endHalf": false,
      "id": "",
      "startDate": "2026-12-04",
      "startHalf": false,
      "status": "approved",
      "typeId": ""
    }
  ],
  "from": "2026-12-14",
  "holidays": [
    {
      "custom": true,
      "date": "2026-12-24",
      "fraction": 0.5,
      "name": "Heiligabend (halber Tag)"
    },
    {
      "custom": false,
      "date": "2026-12-25",
      "fraction": 1,
      "name": "1. Weihnachtstag"
    },
    {
      "custom": false,
      "date": "2026-12-26",
      "fraction": 1,
      "name": "2. Weihnachtstag"
    }
  ],
  "to": "2026-12-27"
}
```

### Example request

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

## Who of the people is absent and until when (tenant:access)

`POST /api/hr/v1/presence/query`

Module: HR · operationId: `queryPresence` · Tag: Absences · Auth: access token (`Authorization: Bearer <accessToken>`)

Presence badges ("abwesend bis …"): `date` is the day asked for (default: today in the tenant's
time zone). Only approved absences count (also with a pending cancellation); absences that follow
each other directly or across a weekend form one stretch, `until` is its last day. Only absent
people are listed, never with type or status; unknown and inactive e-mails are left out. Follows
the team calendar: with `absencesVisibleToColleagues` off only the caller and the people the
caller decides absences for are answered. At most 500 e-mails (`400`).

### Request body

`application/json` (required)

- `emails` (array of string (email), required): E-mail addresses of the people asked for
- `date` (string (date)): Day asked for, default: today in the tenant's time zone

Example:

```json
{
  "date": "2026-11-19",
  "emails": [
    "julia.hagen@muster-it.example",
    "sophie.huber@muster-it.example",
    "jonas.bauer@muster-it.example"
  ]
}
```

### Responses

- **200** Absent people (`application/json`)
- **400** Error (`application/json`)

Fields of the 200 answer:

- `absent` (array of object): Only the absent people; never with type or status
  - `email` (string (email)): E-mail address of the absent person
  - `until` (string (date)): Last day of the absence stretch

Example 200 answer:

```json
{
  "absent": [
    {
      "email": "julia.hagen@muster-it.example",
      "until": "2026-11-20"
    }
  ]
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/presence/query' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"date":"2026-11-19","emails":["julia.hagen@muster-it.example","sophie.huber@muster-it.example","jonas.bauer@muster-it.example"]}'
```

## Working days, holidays and remaining vacation of a planned absence

`GET /api/hr/v1/absences/preview`

Module: HR · operationId: `previewAbsence` · Tag: Absences · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `employeeId` | query | string |  |  |
| `typeId` | query | string | yes |  |
| `startDate` | query | string (date) | yes |  |
| `endDate` | query | string (date) | yes |  |
| `startHalf` | query | boolean |  |  |
| `endHalf` | query | boolean |  |  |
| `except` | query | string |  | Absence being edited |

### Responses

- **200** Preview (`application/json`)
- **400** Error (`application/json`)

Fields of the 200 answer:

- `days` (number): Working days the absence would count (halves allowed)
- `holidays` (array of Holiday): Holidays inside the period (not counted)
  - `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
- `overlaps` (boolean): The period overlaps another absence of the employee
- `remaining` (number): Vacation left in the start year afterwards (vacation types only)

Example 200 answer:

```json
{
  "days": 5,
  "holidays": [],
  "overlaps": false,
  "remaining": 4
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/absences/preview?typeId=string&startDate=2026-03-02&endDate=2026-03-02' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## One absence (own, or any with hr:absence:approve)

`GET /api/hr/v1/absences/{id}`

Module: HR · operationId: `getAbsence` · Tag: Absences · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Absence (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `createdAt` (string (date-time)): When the absence was created
- `createdBy` (string): Who entered the absence (e-mail of the caller; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `days` (number): Working days (halves allowed)
- `decidedAt` (string (date-time)): When it was decided last
- `decidedBy` (string): Who decided last (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `decisionNote` (string): Note of the last decision (e.g. the reason of a rejection)
- `employeeId` (string): Id of the employee
- `employeeName` (string): Display name of the employee (in lists)
- `endDate` (string (date)): Last day (YYYY-MM-DD), inclusive
- `endHalf` (boolean): The last day is only the morning
- `id` (string): Id of the absence
- `note` (string): The employee's note
- `startDate` (string (date)): First day (YYYY-MM-DD)
- `startHalf` (boolean): The first day is only the afternoon
- `status` (string): State of the absence; types without approval start as approved (one of `requested`, `approved`, `rejected`, `cancelled`, `cancellation_requested`)
- `typeId` (string): Id of the absence type
- `updatedAt` (string (date-time)): When the absence was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "createdAt": "2026-11-16T08:12:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "days": 5,
  "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "employeeName": "Sophie Huber",
  "endDate": "2026-12-18",
  "endHalf": false,
  "id": "3e5a7c9e-1a3c-4e5a-8c7e-9a1c3e5a7c31",
  "note": "Städtereise Wien",
  "startDate": "2026-12-14",
  "startHalf": false,
  "status": "requested",
  "typeId": "8c0e2a4c-6e8a-4c0e-9a4c-6e8a0c2e4a13",
  "updatedAt": "2026-11-16T08:12:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/absences/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change period, type or note

`PATCH /api/hr/v1/absences/{id}`

Module: HR · operationId: `updateAbsence` · Tag: Absences · Auth: access token (`Authorization: Bearer <accessToken>`)

Owners change requests; approvers change requested and approved absences.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `endDate` (string (date), required): Last day (YYYY-MM-DD), inclusive
- `startDate` (string (date), required): First day (YYYY-MM-DD)
- `typeId` (string, required): Id of the absence type
- `employeeId` (string): Defaults to the caller
- `endHalf` (boolean): The last day is only the morning
- `note` (string): Note of the employee (max length 2000)
- `startHalf` (boolean): The first day is only the afternoon
- `version` (integer): Required for PATCH

Example:

```json
{
  "endDate": "2026-12-17",
  "note": "Städtereise Wien, Rückreise am Donnerstag",
  "startDate": "2026-12-14",
  "typeId": "8c0e2a4c-6e8a-4c0e-9a4c-6e8a0c2e4a13",
  "version": 1
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `createdAt` (string (date-time)): When the absence was created
- `createdBy` (string): Who entered the absence (e-mail of the caller; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `days` (number): Working days (halves allowed)
- `decidedAt` (string (date-time)): When it was decided last
- `decidedBy` (string): Who decided last (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `decisionNote` (string): Note of the last decision (e.g. the reason of a rejection)
- `employeeId` (string): Id of the employee
- `employeeName` (string): Display name of the employee (in lists)
- `endDate` (string (date)): Last day (YYYY-MM-DD), inclusive
- `endHalf` (boolean): The last day is only the morning
- `id` (string): Id of the absence
- `note` (string): The employee's note
- `startDate` (string (date)): First day (YYYY-MM-DD)
- `startHalf` (boolean): The first day is only the afternoon
- `status` (string): State of the absence; types without approval start as approved (one of `requested`, `approved`, `rejected`, `cancelled`, `cancellation_requested`)
- `typeId` (string): Id of the absence type
- `updatedAt` (string (date-time)): When the absence was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "createdAt": "2026-11-16T08:12:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "days": 5,
  "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "employeeName": "Sophie Huber",
  "endDate": "2026-12-18",
  "endHalf": false,
  "id": "3e5a7c9e-1a3c-4e5a-8c7e-9a1c3e5a7c31",
  "note": "Städtereise Wien",
  "startDate": "2026-12-14",
  "startHalf": false,
  "status": "requested",
  "typeId": "8c0e2a4c-6e8a-4c0e-9a4c-6e8a0c2e4a13",
  "updatedAt": "2026-11-16T08:12:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/hr/v1/absences/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"endDate":"2026-12-17","note":"Städtereise Wien, Rückreise am Donnerstag","startDate":"2026-12-14","typeId":"8c0e2a4c-6e8a-4c0e-9a4c-6e8a0c2e4a13","version":1}'
```

## Approve, reject or cancel an absence

`POST /api/hr/v1/absences/{id}/{action}`

Module: HR · operationId: `runAbsenceAction` · Tag: Absences · Auth: access token (`Authorization: Bearer <accessToken>`)

Approvers (hr:absence:approve) approve and reject requests and cancellation requests of
others (a reason is required to reject) and cancel any absence. Owners withdraw their
requests; cancelling an approved absence that needs approval and has not started becomes
`cancellation_requested`. Not allowed in the current status: `409 invalid_state`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `action` | path | string | yes | (one of `approve`, `reject`, `cancel`) |

### Request body

`application/json` (required)

- `version` (integer, required): Version of the absence the decision is based on
- `note` (string): Note of the decision (e.g. the reason of a rejection) (max length 2000)

Example:

```json
{
  "note": "Passt, die Vertretung übernimmt Elias.",
  "version": 1
}
```

### Responses

- **200** Decided (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `createdAt` (string (date-time)): When the absence was created
- `createdBy` (string): Who entered the absence (e-mail of the caller; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `days` (number): Working days (halves allowed)
- `decidedAt` (string (date-time)): When it was decided last
- `decidedBy` (string): Who decided last (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `decisionNote` (string): Note of the last decision (e.g. the reason of a rejection)
- `employeeId` (string): Id of the employee
- `employeeName` (string): Display name of the employee (in lists)
- `endDate` (string (date)): Last day (YYYY-MM-DD), inclusive
- `endHalf` (boolean): The last day is only the morning
- `id` (string): Id of the absence
- `note` (string): The employee's note
- `startDate` (string (date)): First day (YYYY-MM-DD)
- `startHalf` (boolean): The first day is only the afternoon
- `status` (string): State of the absence; types without approval start as approved (one of `requested`, `approved`, `rejected`, `cancelled`, `cancellation_requested`)
- `typeId` (string): Id of the absence type
- `updatedAt` (string (date-time)): When the absence was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "createdAt": "2026-11-16T08:12:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "days": 5,
  "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "employeeName": "Sophie Huber",
  "endDate": "2026-12-18",
  "endHalf": false,
  "id": "3e5a7c9e-1a3c-4e5a-8c7e-9a1c3e5a7c31",
  "note": "Städtereise Wien",
  "startDate": "2026-12-14",
  "startHalf": false,
  "status": "requested",
  "typeId": "8c0e2a4c-6e8a-4c0e-9a4c-6e8a0c2e4a13",
  "updatedAt": "2026-11-16T08:12:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/absences/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/approve' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"note":"Passt, die Vertretung übernimmt Elias.","version":1}'
```

## Vacation account of a year (own, or any with hr:absence:approve)

`GET /api/hr/v1/employees/{id}/vacation`

Module: HR · operationId: `getVacationAccount` · Tag: Absences · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `year` | query | integer |  |  |
| `id` | path | string | yes | Employee id or `me` |

### Responses

- **200** Account (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `adjustments` (number): Sum of the corrections in days
- `carryover` (number): Remaining days of the previous year
- `carryoverExpires` (string (date)): Day the carryover expires (YYYY-MM-DD)
- `carryoverForfeited` (number): Part of the carryover not used before it expired
- `employeeId` (string): Id of the employee
- `entitlement` (number): 1/12 of the yearly days per full month of employment, rounded up to half days
- `entries` (array of object): Corrections of the account
  - `createdAt` (string (date-time)): When it was entered
  - `createdBy` (string): Who entered it (e-mail)
  - `days` (number): Days added (negative: subtracted)
  - `id` (string): Id of the correction
  - `note` (string): Reason of the correction
  - `year` (integer): Year the correction counts for
- `planned` (number): Approved days (also with a pending cancellation) on dates after today
- `remaining` (number): Days left: entitlement + carryover − carryoverForfeited + adjustments − taken − planned − requested
- `requested` (number): Days of requests not decided yet (status requested)
- `taken` (number): Approved days (also with a pending cancellation) on dates up to and including today (tenant time zone); an absence spanning today counts its days up to today here
- `year` (integer): The year

Example 200 answer:

```json
{
  "adjustments": 1,
  "carryover": 2,
  "carryoverExpires": "2026-03-31",
  "carryoverForfeited": 0,
  "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "entitlement": 28,
  "entries": [
    {
      "createdAt": "2026-10-12T09:30:00Z",
      "createdBy": "martin.brandl@muster-it.example",
      "days": 1,
      "id": "7c9e1a3c-5e7a-4c9e-8a1c-5e7a9c1e3a33",
      "note": "Ausgleich für den Samstagseinsatz beim Rollout Donau Maschinenbau",
      "year": 2026
    }
  ],
  "planned": 0,
  "remaining": 5,
  "requested": 5,
  "taken": 21,
  "year": 2026
}
```

### Example request

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

## Correct a vacation account (hr:absence:approve, or the person's managers and deputies)

`POST /api/hr/v1/employees/{id}/vacation/adjustments`

Module: HR · operationId: `adjustVacation` · Tag: Absences · Auth: access token (`Authorization: Bearer <accessToken>`)

Managers and deputies in the chain of command correct their team's accounts, never their own (`403`); people outside their team answer `404`. This team path needs the person's own sign-in session – API key and assistant tokens without hr:absence:approve answer `403`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `days` (number, required): Half days, negative to deduct
- `note` (string, required): Reason of the correction
- `year` (integer, required): Year of the vacation account

Example:

```json
{
  "days": 1,
  "note": "Ausgleich für den Samstagseinsatz beim Rollout Donau Maschinenbau",
  "year": 2026
}
```

### Responses

- **201** The updated account (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 201 answer:

- `adjustments` (number): Sum of the corrections in days
- `carryover` (number): Remaining days of the previous year
- `carryoverExpires` (string (date)): Day the carryover expires (YYYY-MM-DD)
- `carryoverForfeited` (number): Part of the carryover not used before it expired
- `employeeId` (string): Id of the employee
- `entitlement` (number): 1/12 of the yearly days per full month of employment, rounded up to half days
- `entries` (array of object): Corrections of the account
  - `createdAt` (string (date-time)): When it was entered
  - `createdBy` (string): Who entered it (e-mail)
  - `days` (number): Days added (negative: subtracted)
  - `id` (string): Id of the correction
  - `note` (string): Reason of the correction
  - `year` (integer): Year the correction counts for
- `planned` (number): Approved days (also with a pending cancellation) on dates after today
- `remaining` (number): Days left: entitlement + carryover − carryoverForfeited + adjustments − taken − planned − requested
- `requested` (number): Days of requests not decided yet (status requested)
- `taken` (number): Approved days (also with a pending cancellation) on dates up to and including today (tenant time zone); an absence spanning today counts its days up to today here
- `year` (integer): The year

Example 201 answer:

```json
{
  "adjustments": 1,
  "carryover": 2,
  "carryoverExpires": "2026-03-31",
  "carryoverForfeited": 0,
  "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "entitlement": 28,
  "entries": [
    {
      "createdAt": "2026-10-12T09:30:00Z",
      "createdBy": "martin.brandl@muster-it.example",
      "days": 1,
      "id": "7c9e1a3c-5e7a-4c9e-8a1c-5e7a9c1e3a33",
      "note": "Ausgleich für den Samstagseinsatz beim Rollout Donau Maschinenbau",
      "year": 2026
    }
  ],
  "planned": 0,
  "remaining": 5,
  "requested": 5,
  "taken": 21,
  "year": 2026
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/employees/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/vacation/adjustments' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"days":1,"note":"Ausgleich für den Samstagseinsatz beim Rollout Donau Maschinenbau","year":2026}'
```

# Working time

## Working-time models of an employee, oldest first (hr:read, the person themself, or their managers and deputies)

`GET /api/hr/v1/employees/{id}/schedules`

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

Managers and deputies read the models of the people in their chain of command; people outside their scope answer `404`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Models (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of WorkSchedule, required): Working-time models, oldest first
  - `dayMinutes` (array of integer, required): Target minutes Monday … Sunday
  - `vacationDays` (number, required): Vacation days per year
  - `validFrom` (string (date), required): First day the model applies (YYYY-MM-DD)
  - `createdAt` (string (date-time), read-only): When the model was saved
  - `createdBy` (string, read-only): Who saved the model (e-mail)
  - `employeeId` (string, read-only): Id of the employee
  - `federalState` (string): Overrides the tenant's Bundesland
  - `id` (string, read-only): Id of the working-time model

Example 200 answer:

```json
{
  "items": [
    {
      "createdAt": "2025-10-20T11:00:00Z",
      "createdBy": "clara.becker@muster-it.example",
      "dayMinutes": [
        300,
        300,
        300,
        300,
        300,
        0,
        0
      ],
      "employeeId": "d1f3b5c7-9e1a-4d3f-8b5c-7a9e1f3b5d08",
      "federalState": "BY",
      "id": "9e1a3c5e-7a9c-4e1a-8c3e-7a9c1e3a5c34",
      "vacationDays": 28,
      "validFrom": "2025-11-03"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/employees/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/schedules' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Save the working-time model valid from a date (hr:write)

`POST /api/hr/v1/employees/{id}/schedules`

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

Without `id` a model starting on the same day is replaced; with `id` that model is changed and may move to another date (`409 duplicate` when another model already starts there).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `dayMinutes` (array of integer, required): Target minutes Monday … Sunday
- `vacationDays` (number, required): Vacation days per year
- `validFrom` (string (date), required): First day the model applies (YYYY-MM-DD)
- `createdAt` (string (date-time), read-only): When the model was saved
- `createdBy` (string, read-only): Who saved the model (e-mail)
- `employeeId` (string, read-only): Id of the employee
- `federalState` (string): Overrides the tenant's Bundesland
- `id` (string, read-only): Id of the working-time model

Example:

```json
{
  "createdAt": "2025-10-20T11:00:00Z",
  "createdBy": "clara.becker@muster-it.example",
  "dayMinutes": [
    300,
    300,
    300,
    300,
    300,
    0,
    0
  ],
  "employeeId": "d1f3b5c7-9e1a-4d3f-8b5c-7a9e1f3b5d08",
  "federalState": "BY",
  "id": "9e1a3c5e-7a9c-4e1a-8c3e-7a9c1e3a5c34",
  "vacationDays": 28,
  "validFrom": "2025-11-03"
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)

Fields of the 200 answer:

- `dayMinutes` (array of integer, required): Target minutes Monday … Sunday
- `vacationDays` (number, required): Vacation days per year
- `validFrom` (string (date), required): First day the model applies (YYYY-MM-DD)
- `createdAt` (string (date-time), read-only): When the model was saved
- `createdBy` (string, read-only): Who saved the model (e-mail)
- `employeeId` (string, read-only): Id of the employee
- `federalState` (string): Overrides the tenant's Bundesland
- `id` (string, read-only): Id of the working-time model

Example 200 answer:

```json
{
  "createdAt": "2025-10-20T11:00:00Z",
  "createdBy": "clara.becker@muster-it.example",
  "dayMinutes": [
    300,
    300,
    300,
    300,
    300,
    0,
    0
  ],
  "employeeId": "d1f3b5c7-9e1a-4d3f-8b5c-7a9e1f3b5d08",
  "federalState": "BY",
  "id": "9e1a3c5e-7a9c-4e1a-8c3e-7a9c1e3a5c34",
  "vacationDays": 28,
  "validFrom": "2025-11-03"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/employees/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/schedules' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"createdAt":"2025-10-20T11:00:00Z","createdBy":"clara.becker@muster-it.example","dayMinutes":[300,300,300,300,300,0,0],"employeeId":"d1f3b5c7-9e1a-4d3f-8b5c-7a9e1f3b5d08","federalState":"BY","id":"9e1a3c5e-7a9c-4e1a-8c3e-7a9c1e3a5c34","vacationDays":28,"validFrom":"2025-11-03"}'
```

## Remove a working-time model (hr:write)

`DELETE /api/hr/v1/employees/{id}/schedules/{scheduleId}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `scheduleId` | path | string | yes |  |

### Responses

- **204** Removed
- **404** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/hr/v1/employees/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/schedules/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Correct a time account, e.g. opening balance or payout (hr:time:manage, or the person's managers and deputies)

`POST /api/hr/v1/employees/{id}/time-adjustments`

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

Managers and deputies in the chain of command correct their team's accounts, never their own (`403`); people outside their team answer `404`. This team path needs the person's own sign-in session – API key and assistant tokens without hr:time:manage answer `403`. The payroll export stays with hr:time:manage.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `date` (string (date), required): Day the correction counts for (YYYY-MM-DD)
- `minutes` (integer, required): Minutes added to the time account (negative: subtracted)
- `note` (string, required): Reason of the correction

Example:

```json
{
  "date": "2026-10-31",
  "minutes": -600,
  "note": "Auszahlung von 10 Überstunden mit der Oktoberabrechnung"
}
```

### Responses

- **201** Booked (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `createdAt` (string (date-time)): When the correction was entered
- `createdBy` (string): Who entered the correction (e-mail)
- `date` (string (date)): Day the correction counts for (YYYY-MM-DD)
- `id` (string): Id of the correction
- `minutes` (integer): Minutes added to the time account (negative: subtracted)
- `note` (string): Reason of the correction

Example 201 answer:

```json
{
  "createdAt": "2026-11-03T09:10:00Z",
  "createdBy": "clara.becker@muster-it.example",
  "date": "2026-10-31",
  "id": "1c3e5a7c-9e1a-4c3e-8a5c-9e1a3c5e7a35",
  "minutes": -600,
  "note": "Auszahlung von 10 Überstunden mit der Oktoberabrechnung"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/employees/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/time-adjustments' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"date":"2026-10-31","minutes":-600,"note":"Auszahlung von 10 Überstunden mit der Oktoberabrechnung"}'
```

## Time entries of an employee (own, or any with hr:time:manage)

`GET /api/hr/v1/time-entries`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `employeeId` | query | string |  | Empty or `me` for the caller |
| `from` | query | string (date) | yes |  |
| `to` | query | string (date) | yes |  |

### Responses

- **200** Entries (`application/json`)
- **400** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of TimeEntry, required): Time entries of the range
  - `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)

Example 200 answer:

```json
{
  "items": [
    {
      "autoEnded": false,
      "breakMinutes": 30,
      "createdAt": "2026-11-18T06:28:00Z",
      "createdBy": "sophie.huber@muster-it.example",
      "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",
      "updatedAt": "2026-11-18T15:00:00Z",
      "updatedBy": "sophie.huber@muster-it.example",
      "version": 1
    },
    {
      "autoEnded": false,
      "breakMinutes": 0,
      "createdAt": "2026-11-19T06:31:00Z",
      "createdBy": "sophie.huber@muster-it.example",
      "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "endedForBreak": false,
      "id": "5c7e9a1c-3e5a-4c7e-8a9c-3e5a7c9e1a37",
      "source": "clock",
      "start": "2026-11-19T06:31:00Z",
      "updatedAt": "2026-11-19T06:31:00Z",
      "updatedBy": "sophie.huber@muster-it.example",
      "version": 1
    }
  ]
}
```

### Example request

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

## Book working time manually

`POST /api/hr/v1/time-entries`

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

A `reason` is required for other people's time and for own entries older than the
tenant's `selfEditDays`. Overlapping entries fail with `409 overlap`, closed months with
`409 period_closed`.

### Request body

`application/json` (required)

- `start` (string (date-time), required): Start of the segment
- `breakMinutes` (integer): Break inside the segment in minutes
- `employeeId` (string): Defaults to the caller
- `end` (string (date-time)): End of the segment; omitted for an open (running) one
- `endedForBreak` (boolean): The end is a break stamp („Pause“), not „Gehen“. Omitted on PATCH keeps the stored value; ignored without an end.
- `note` (string): Note on the entry
- `reason` (string): Reason of the change; required for other people's time and own entries older than the self-edit window
- `version` (integer): Required for PATCH

Example:

```json
{
  "breakMinutes": 30,
  "end": "2026-11-17T15:00:00Z",
  "note": "Kundentermin Kanzlei Hofmann",
  "reason": "Stempeln am Morgen vergessen",
  "start": "2026-11-17T06:30:00Z"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `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)

Example 201 answer:

```json
{
  "autoEnded": false,
  "breakMinutes": 30,
  "createdAt": "2026-11-18T06:28:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "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",
  "updatedAt": "2026-11-18T15:00:00Z",
  "updatedBy": "sophie.huber@muster-it.example",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/time-entries' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"breakMinutes":30,"end":"2026-11-17T15:00:00Z","note":"Kundentermin Kanzlei Hofmann","reason":"Stempeln am Morgen vergessen","start":"2026-11-17T06:30:00Z"}'
```

## Delete an entry (kept in the change history)

`DELETE /api/hr/v1/time-entries/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `version` | query | integer | yes |  |
| `reason` | query | string |  |  |
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/hr/v1/time-entries/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12?version=1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Correct an entry

`PATCH /api/hr/v1/time-entries/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `start` (string (date-time), required): Start of the segment
- `breakMinutes` (integer): Break inside the segment in minutes
- `employeeId` (string): Defaults to the caller
- `end` (string (date-time)): End of the segment; omitted for an open (running) one
- `endedForBreak` (boolean): The end is a break stamp („Pause“), not „Gehen“. Omitted on PATCH keeps the stored value; ignored without an end.
- `note` (string): Note on the entry
- `reason` (string): Reason of the change; required for other people's time and own entries older than the self-edit window
- `version` (integer): Required for PATCH

Example:

```json
{
  "breakMinutes": 45,
  "end": "2026-11-17T15:15:00Z",
  "reason": "Pause und Ende korrigiert",
  "start": "2026-11-17T06:30:00Z",
  "version": 2
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `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)

Example 200 answer:

```json
{
  "autoEnded": false,
  "breakMinutes": 30,
  "createdAt": "2026-11-18T06:28:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "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",
  "updatedAt": "2026-11-18T15:00:00Z",
  "updatedBy": "sophie.huber@muster-it.example",
  "version": 1
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/hr/v1/time-entries/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"breakMinutes":45,"end":"2026-11-17T15:15:00Z","reason":"Pause und Ende korrigiert","start":"2026-11-17T06:30:00Z","version":2}'
```

## Change history of an entry

`GET /api/hr/v1/time-entries/{id}/history`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Changes, oldest first (`application/json`)

Fields of the 200 answer:

- `items` (array of TimeEntryChange, required): Change records, oldest first
  - `action` (string): What was done (create, update, delete, the stamps, auto-out)
  - `actor` (string): Who did it (e-mail, or system; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
  - `after` (TimeEntry)
    - `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)
  - `at` (string (date-time)): When it happened
  - `before` (TimeEntry)
    - `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)
  - `entryId` (string): Id of the time entry
  - `id` (string): Id of the change record
  - `reason` (string): Reason given for the change

Example 200 answer:

```json
{
  "items": [
    {
      "action": "stamp-in",
      "actor": "sophie.huber@muster-it.example",
      "after": {
        "breakMinutes": 0,
        "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
        "id": "3a5c7e9a-1c3e-4a5c-9e7a-1c3e5a7c9e36",
        "source": "clock",
        "start": "2026-11-18T06:28:00Z",
        "version": 1
      },
      "at": "2026-11-18T06:28:00Z",
      "entryId": "3a5c7e9a-1c3e-4a5c-9e7a-1c3e5a7c9e36",
      "id": "7e9a1c3e-5a7c-4e9a-8c1e-5a7c9e1a3c38"
    },
    {
      "action": "update",
      "actor": "sophie.huber@muster-it.example",
      "after": {
        "breakMinutes": 30,
        "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
        "end": "2026-11-18T15:00:00Z",
        "id": "3a5c7e9a-1c3e-4a5c-9e7a-1c3e5a7c9e36",
        "source": "clock",
        "start": "2026-11-18T06:28:00Z",
        "version": 3
      },
      "at": "2026-11-18T15:04:00Z",
      "before": {
        "breakMinutes": 0,
        "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
        "end": "2026-11-18T15:00:00Z",
        "id": "3a5c7e9a-1c3e-4a5c-9e7a-1c3e5a7c9e36",
        "source": "clock",
        "start": "2026-11-18T06:28:00Z",
        "version": 2
      },
      "entryId": "3a5c7e9a-1c3e-4a5c-9e7a-1c3e5a7c9e36",
      "id": "9a1c3e5a-7c9e-4a1c-9e3a-7c9e1a3c5e39",
      "reason": "Mittagspause nachgetragen"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/time-entries/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/history' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Add one stamp (Kommen, Pause, Pause beenden, Gehen) to a day (own, or the team's with responsibility or hr:time:manage)

`POST /api/hr/v1/time-stamps`

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

HR fits the stamp into the recorded time: `in` and `break-end` open a segment, `break` and
`out` close the open segment (also one from the day before – night shift). `break` inside a
finished segment splits it, and a following `break-end` moves the rest of it; at the exact
end of a segment `break`/`out` switch it between Pause and Gehen. A stamp that does not fit
fails with `409` and the code `stamp_<reason>` (`stamp_already_open`, `stamp_inside_segment`,
`stamp_later_segment`, `stamp_no_break`, `stamp_no_open_segment`, `stamp_too_long`,
`stamp_unchanged`) and `field` (`time` or `kind`). Like manual entries, a `reason` is required
for other people's time and own days older than `selfEditDays`; closed months fail with
`409 period_closed`, overlaps with `409 overlap`, future times with `400`. Returns the
rebuilt day.

### Request body

`application/json` (required)

- `date` (string (date), required): Day of the stamp (YYYY-MM-DD)
- `kind` (string, required): in = Kommen, break = Pause, break-end = Pause beenden, out = Gehen (one of `in`, `break`, `break-end`, `out`)
- `time` (string, required): Local time HH:MM in the tenant's time zone
- `employeeId` (string): Empty or `me` for the caller
- `note` (string): Stored on the segment the stamp opens
- `reason` (string): Required for other people's time and for own days older than the tenant's `selfEditDays`

Example:

```json
{
  "date": "2026-11-17",
  "kind": "break",
  "reason": "Pause nachgetragen",
  "time": "12:00"
}
```

### Responses

- **200** The day after the stamp (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `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)

Example 200 answer:

```json
{
  "actual": 480,
  "break": 30,
  "counted": true,
  "credit": 0,
  "date": "2026-11-17",
  "delta": 0,
  "entries": [
    {
      "autoEnded": false,
      "breakMinutes": 0,
      "createdAt": "2026-11-18T07:02:00Z",
      "createdBy": "sophie.huber@muster-it.example",
      "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "end": "2026-11-17T11:00:00Z",
      "endedForBreak": true,
      "id": "1e3a5c7e-9a1c-4e3a-8c5e-9a1c3e5a7c40",
      "source": "manual",
      "start": "2026-11-17T06:30:00Z",
      "updatedAt": "2026-11-18T07:02:00Z",
      "updatedBy": "sophie.huber@muster-it.example",
      "version": 1
    },
    {
      "autoEnded": false,
      "breakMinutes": 0,
      "createdAt": "2026-11-18T07:03:00Z",
      "createdBy": "sophie.huber@muster-it.example",
      "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "end": "2026-11-17T15:00:00Z",
      "endedForBreak": false,
      "id": "3c5e7a9c-1e3a-4c5e-9a7c-1e3a5c7e9a41",
      "source": "manual",
      "start": "2026-11-17T11:30:00Z",
      "updatedAt": "2026-11-18T07:03:00Z",
      "updatedBy": "sophie.huber@muster-it.example",
      "version": 1
    }
  ],
  "running": false,
  "target": 480,
  "violations": []
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/time-stamps' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"date":"2026-11-17","kind":"break","reason":"Pause nachgetragen","time":"12:00"}'
```

## 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"
```

## Today's attendance of the signed-in user

`GET /api/hr/v1/attendance/status`

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

### Responses

- **200** Attendance (`application/json`)

Fields of the 200 answer:

- `breakMinutes` (integer): Break minutes today so far
- `employeeId` (string): Id of the employee (empty without an active employee record)
- `employeeName` (string): Display name of the employee
- `registered` (boolean): The caller has an active employee record (false: nothing else is filled)
- `since` (string (date-time)): When the current state began (clock-in or break start)
- `status` (string): Current attendance state (one of `CLOCKED_IN`, `ON_BREAK`, `CLOCKED_OUT`)
- `targetMinutes` (integer): Today's target minutes
- `workedMinutes` (integer): Minutes worked today so far

Example 200 answer:

```json
{
  "breakMinutes": 0,
  "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "employeeName": "Sophie Huber",
  "registered": true,
  "since": "2026-11-19T06:31:00Z",
  "status": "CLOCKED_IN",
  "targetMinutes": 480,
  "workedMinutes": 145
}
```

### Example request

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

## Clock in/out or start/end a break for the signed-in user

`POST /api/hr/v1/attendance/{action}`

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

Clock-in and break-end open a time entry; break-start and clock-out close it.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `action` | path | string | yes | (one of `clock-in`, `clock-out`, `break-start`, `break-end`) |

### Responses

- **200** Attendance (`application/json`)
- **400** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `breakMinutes` (integer): Break minutes today so far
- `employeeId` (string): Id of the employee (empty without an active employee record)
- `employeeName` (string): Display name of the employee
- `registered` (boolean): The caller has an active employee record (false: nothing else is filled)
- `since` (string (date-time)): When the current state began (clock-in or break start)
- `status` (string): Current attendance state (one of `CLOCKED_IN`, `ON_BREAK`, `CLOCKED_OUT`)
- `targetMinutes` (integer): Today's target minutes
- `workedMinutes` (integer): Minutes worked today so far

Example 200 answer:

```json
{
  "breakMinutes": 0,
  "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "employeeName": "Sophie Huber",
  "registered": true,
  "since": "2026-11-19T06:31:00Z",
  "status": "CLOCKED_IN",
  "targetMinutes": 480,
  "workedMinutes": 145
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/attendance/clock-in' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Monthly overview (hr:time:manage for everybody, managers for their team)

`GET /api/hr/v1/time-accounts`

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

Without hr:time:manage only the people the caller is responsible for; `403` when that is nobody.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `month` | query | string |  |  |
| `groupId` | query | string |  |  |
| `orgUnitId` | query | string |  | Only people of this org unit |
| `subUnits` | query | boolean |  | Include the unit's sub-units |
| `team` | query | string |  | `mine` = only the people the caller is responsible for (one of `mine`) |
| `limit` | query | integer |  | 1–200; another value is a 400 invalid. (default `50`; max 200) |
| `offset` | query | integer |  | (default `0`) |

### Responses

- **200** A page of employees, by name (`application/json`)

Fields of the 200 answer:

- `items` (array of TimeAccountRow): Employees of this page
  - `balance` (integer): Time account balance in minutes at the end of the month (up to yesterday for the current month)
  - `closed` (boolean): The month is closed for the employee
  - `employeeId` (string): Id of the employee
  - `employeeName` (string): Display name of the employee
  - `sickDays` (number): Sick days in 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)
  - `vacationDays` (number): Vacation days taken in the month
- `month` (string): The month (YYYY-MM)
- `total` (integer): Number of all matching employees

Example 200 answer:

```json
{
  "items": [
    {
      "balance": 310,
      "closed": false,
      "employeeId": "c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06",
      "employeeName": "Elias Gruber",
      "sickDays": 2,
      "totals": {
        "actual": 9720,
        "break": 600,
        "credit": 960,
        "delta": 120,
        "monthTarget": 10560,
        "target": 10560,
        "violations": 1
      },
      "vacationDays": 0
    },
    {
      "balance": 135,
      "closed": false,
      "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "employeeName": "Sophie Huber",
      "sickDays": 0,
      "totals": {
        "actual": 9255,
        "break": 570,
        "credit": 1440,
        "delta": 135,
        "monthTarget": 10560,
        "target": 10560,
        "violations": 0
      },
      "vacationDays": 3
    }
  ],
  "month": "2026-10",
  "total": 2
}
```

### Example request

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

## Close a past month (hr:time:manage, or managers for their team)

`POST /api/hr/v1/time-periods/close`

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

Freezes the month's figures; its entries and absences can no longer change. No `employeeIds` closes it for every active employee.

### Request body

`application/json` (required)

- `month` (string, required): YYYY-MM
- `employeeIds` (array of string): Employees to close or reopen the month for; empty: every active employee

Example:

```json
{
  "employeeIds": [
    "c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06",
    "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02"
  ],
  "month": "2026-10"
}
```

### Responses

- **200** Number of employees whose month was closed (`application/json`)
- **400** Error (`application/json`)

Fields of the 200 answer:

- `closed` (integer): Number of employees whose month was closed

Example 200 answer:

```json
{
  "closed": 2
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/time-periods/close' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"employeeIds":["c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06","e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02"],"month":"2026-10"}'
```

## Reopen a closed month of the given employees (hr:time:manage, or managers for their team)

`POST /api/hr/v1/time-periods/reopen`

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

### Request body

`application/json` (required)

- `month` (string, required): YYYY-MM
- `employeeIds` (array of string): Employees to close or reopen the month for; empty: every active employee

Example:

```json
{
  "employeeIds": [
    "c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06",
    "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02"
  ],
  "month": "2026-10"
}
```

### Responses

- **204** Reopened
- **404** Error (`application/json`)

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/time-periods/reopen' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"employeeIds":["c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06","e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02"],"month":"2026-10"}'
```

## Export a month as CSV for payroll (hr:time:manage)

`GET /api/hr/v1/time-export`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `month` | query | string |  |  |
| `kind` | query | string |  | (one of `summary`, `entries`; default `"summary"`) |

### Responses

- **200** Semicolon-separated CSV, UTF-8 with BOM (`text/csv`)
- **400** Error (`application/json`)

### Example request

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

# Travel expenses

## Travel rates and settings of the tenant (tenant:access)

`GET /api/hr/v1/travel-config`

Module: HR · operationId: `getTravelConfig` · Tag: Travel expenses · Auth: access token (`Authorization: Bearer <accessToken>`)

The allowance rates per country and validity (the German domestic rates are seeded as editable
tenant data) and the trade document type of released reports.

### Responses

- **200** Configuration (`application/json`)

Fields of the 200 answer:

- `rates` (array of TravelRate): Allowance rates per country and start date
  - `country` (string, required): ISO 3166-1 alpha-2 code of the country
  - `validFrom` (string (date), required): First day the rates apply (YYYY-MM-DD)
  - `breakfastPercent` (integer): Cut for breakfast in percent of the full-day rate (20)
  - `dinnerPercent` (integer): Cut for dinner (40)
  - `fullDayCents` (integer): 24-hour allowance
  - `id` (string, read-only): Id of the rate row
  - `lunchPercent` (integer): Cut for lunch (40)
  - `mileageCentsPerKm` (integer): Mileage allowance (used from the home country's rate)
  - `overnightCents` (integer): Lodging lump sum per night
  - `partialDayCents` (integer): Allowance of departure/return days and single days over 8 hours
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `settings` (TravelSettings)
  - `homeCountry` (string): Country whose mileage rate applies
  - `transactionType` (string): Trade document type code of released reports
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "rates": [
    {
      "breakfastPercent": 20,
      "country": "DE",
      "dinnerPercent": 40,
      "fullDayCents": 2800,
      "id": "4d6f8b0d-2f4b-4d6f-9b0d-2f4b6d8f0b43",
      "lunchPercent": 40,
      "mileageCentsPerKm": 30,
      "overnightCents": 2000,
      "partialDayCents": 1400,
      "validFrom": "2020-01-01",
      "version": 1
    },
    {
      "breakfastPercent": 20,
      "country": "AT",
      "dinnerPercent": 40,
      "fullDayCents": 5000,
      "id": "2b4d6f8b-0d2f-4b4d-8f6b-0d2f4b6d8f42",
      "lunchPercent": 40,
      "mileageCentsPerKm": 30,
      "overnightCents": 11700,
      "partialDayCents": 3300,
      "validFrom": "2026-01-01",
      "version": 1
    }
  ],
  "settings": {
    "homeCountry": "DE",
    "transactionType": "TRAVEL_EXPENSE",
    "version": 2
  }
}
```

### Example request

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

## Add allowance rates of a country from a date on (hr:travel:manage)

`POST /api/hr/v1/travel-rates`

Module: HR · operationId: `createTravelRate` · Tag: Travel expenses · Auth: access token (`Authorization: Bearer <accessToken>`)

### Request body

`application/json` (required)

- `country` (string, required): ISO 3166-1 alpha-2 code of the country
- `validFrom` (string (date), required): First day the rates apply (YYYY-MM-DD)
- `breakfastPercent` (integer): Cut for breakfast in percent of the full-day rate (20)
- `dinnerPercent` (integer): Cut for dinner (40)
- `fullDayCents` (integer): 24-hour allowance
- `id` (string, read-only): Id of the rate row
- `lunchPercent` (integer): Cut for lunch (40)
- `mileageCentsPerKm` (integer): Mileage allowance (used from the home country's rate)
- `overnightCents` (integer): Lodging lump sum per night
- `partialDayCents` (integer): Allowance of departure/return days and single days over 8 hours
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example:

```json
{
  "breakfastPercent": 20,
  "country": "AT",
  "dinnerPercent": 40,
  "fullDayCents": 5000,
  "id": "2b4d6f8b-0d2f-4b4d-8f6b-0d2f4b6d8f42",
  "lunchPercent": 40,
  "mileageCentsPerKm": 30,
  "overnightCents": 11700,
  "partialDayCents": 3300,
  "validFrom": "2026-01-01",
  "version": 1
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `country` (string, required): ISO 3166-1 alpha-2 code of the country
- `validFrom` (string (date), required): First day the rates apply (YYYY-MM-DD)
- `breakfastPercent` (integer): Cut for breakfast in percent of the full-day rate (20)
- `dinnerPercent` (integer): Cut for dinner (40)
- `fullDayCents` (integer): 24-hour allowance
- `id` (string, read-only): Id of the rate row
- `lunchPercent` (integer): Cut for lunch (40)
- `mileageCentsPerKm` (integer): Mileage allowance (used from the home country's rate)
- `overnightCents` (integer): Lodging lump sum per night
- `partialDayCents` (integer): Allowance of departure/return days and single days over 8 hours
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 201 answer:

```json
{
  "breakfastPercent": 20,
  "country": "AT",
  "dinnerPercent": 40,
  "fullDayCents": 5000,
  "id": "2b4d6f8b-0d2f-4b4d-8f6b-0d2f4b6d8f42",
  "lunchPercent": 40,
  "mileageCentsPerKm": 30,
  "overnightCents": 11700,
  "partialDayCents": 3300,
  "validFrom": "2026-01-01",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/travel-rates' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"breakfastPercent":20,"country":"AT","dinnerPercent":40,"fullDayCents":5000,"id":"2b4d6f8b-0d2f-4b4d-8f6b-0d2f4b6d8f42","lunchPercent":40,"mileageCentsPerKm":30,"overnightCents":11700,"partialDayCents":3300,"validFrom":"2026-01-01","version":1}'
```

## Change allowance rates (hr:travel:manage)

`PUT /api/hr/v1/travel-rates/{id}`

Module: HR · operationId: `updateTravelRate` · Tag: Travel expenses · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `country` (string, required): ISO 3166-1 alpha-2 code of the country
- `validFrom` (string (date), required): First day the rates apply (YYYY-MM-DD)
- `breakfastPercent` (integer): Cut for breakfast in percent of the full-day rate (20)
- `dinnerPercent` (integer): Cut for dinner (40)
- `fullDayCents` (integer): 24-hour allowance
- `id` (string, read-only): Id of the rate row
- `lunchPercent` (integer): Cut for lunch (40)
- `mileageCentsPerKm` (integer): Mileage allowance (used from the home country's rate)
- `overnightCents` (integer): Lodging lump sum per night
- `partialDayCents` (integer): Allowance of departure/return days and single days over 8 hours
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example:

```json
{
  "breakfastPercent": 20,
  "country": "AT",
  "dinnerPercent": 40,
  "fullDayCents": 5000,
  "id": "2b4d6f8b-0d2f-4b4d-8f6b-0d2f4b6d8f42",
  "lunchPercent": 40,
  "mileageCentsPerKm": 30,
  "overnightCents": 11700,
  "partialDayCents": 3300,
  "validFrom": "2026-01-01",
  "version": 1
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `country` (string, required): ISO 3166-1 alpha-2 code of the country
- `validFrom` (string (date), required): First day the rates apply (YYYY-MM-DD)
- `breakfastPercent` (integer): Cut for breakfast in percent of the full-day rate (20)
- `dinnerPercent` (integer): Cut for dinner (40)
- `fullDayCents` (integer): 24-hour allowance
- `id` (string, read-only): Id of the rate row
- `lunchPercent` (integer): Cut for lunch (40)
- `mileageCentsPerKm` (integer): Mileage allowance (used from the home country's rate)
- `overnightCents` (integer): Lodging lump sum per night
- `partialDayCents` (integer): Allowance of departure/return days and single days over 8 hours
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "breakfastPercent": 20,
  "country": "AT",
  "dinnerPercent": 40,
  "fullDayCents": 5000,
  "id": "2b4d6f8b-0d2f-4b4d-8f6b-0d2f4b6d8f42",
  "lunchPercent": 40,
  "mileageCentsPerKm": 30,
  "overnightCents": 11700,
  "partialDayCents": 3300,
  "validFrom": "2026-01-01",
  "version": 1
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/travel-rates/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"breakfastPercent":20,"country":"AT","dinnerPercent":40,"fullDayCents":5000,"id":"2b4d6f8b-0d2f-4b4d-8f6b-0d2f4b6d8f42","lunchPercent":40,"mileageCentsPerKm":30,"overnightCents":11700,"partialDayCents":3300,"validFrom":"2026-01-01","version":1}'
```

## Remove allowance rates (hr:travel:manage)

`DELETE /api/hr/v1/travel-rates/{id}`

Module: HR · operationId: `deleteTravelRate` · Tag: Travel expenses · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Removed
- **403** Error (`application/json`)
- **404** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/hr/v1/travel-rates/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change the travel settings (hr:travel:manage)

`PUT /api/hr/v1/travel-settings`

Module: HR · operationId: `saveTravelSettings` · Tag: Travel expenses · Auth: access token (`Authorization: Bearer <accessToken>`)

### Request body

`application/json` (required)

- `homeCountry` (string): Country whose mileage rate applies
- `transactionType` (string): Trade document type code of released reports
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example:

```json
{
  "homeCountry": "DE",
  "transactionType": "TRAVEL_EXPENSE",
  "version": 2
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `homeCountry` (string): Country whose mileage rate applies
- `transactionType` (string): Trade document type code of released reports
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "homeCountry": "DE",
  "transactionType": "TRAVEL_EXPENSE",
  "version": 2
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/travel-settings' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"homeCountry":"DE","transactionType":"TRAVEL_EXPENSE","version":2}'
```

## List travel expense reports

`GET /api/hr/v1/travel-reports`

Module: HR · operationId: `listTravelReports` · Tag: Travel expenses · Auth: access token (`Authorization: Bearer <accessToken>`)

`hr:travel:approve` and `hr:travel:manage` see every report, managers their own and those of
the people they are responsible for (chain of command and deputies), everyone else their own.
Items and receipts are only in `GET /travel-reports/{id}`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `employeeId` | query | string |  | Employee id or `me` for the caller's own reports |
| `team` | query | string |  | `mine` = only the people the caller is responsible for (one of `mine`) |
| `responsible` | query | string |  | `me` = reports where the caller should decide first (as for absences) (one of `me`) |
| `status` | query | string |  | Comma-separated statuses |
| `from` | query | string (date) |  | Trips ending on or after this date |
| `to` | query | string (date) |  | Trips starting on or before this date |
| `limit` | query | integer |  | 1–200; another value is a 400 invalid. (default `50`; max 200) |
| `offset` | query | integer |  | (default `0`) |

### Responses

- **200** A page of reports, latest trip first (`application/json`)
- **400** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of TravelReport): Reports of this page (without items and receipts)
  - `approvedAt` (string (date-time)): When it was approved
  - `approvedBy` (string): Who approved (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
  - `country` (string): ISO 3166-1 alpha-2 code of the destination; selects the allowance rates
  - `createdAt` (string (date-time)): When the report was created
  - `createdBy` (string): Who created the report (e-mail)
  - `days` (array of TravelDay): What was provided per day (meals, lodging lump sum)
    - `breakfast` (boolean): Breakfast provided (cuts the allowance by breakfastPercent of the full-day rate)
    - `date` (string (date)): Day of the trip (YYYY-MM-DD)
    - `dinner` (boolean): Dinner was provided (reduces the meal allowance)
    - `lodgingLumpSum` (boolean): The night after this day without a hotel receipt (lodging lump sum)
    - `lunch` (boolean): Lunch was provided (reduces the meal allowance)
  - `decisionNote` (string): Reason of the last rejection
  - `destination` (string): Destination of the trip
  - `employeeId` (string): Id of the employee
  - `employeeName` (string): Display name of the employee (in lists)
  - `endAt` (string): Local return time (YYYY-MM-DDTHH:MM)
  - `id` (string): Id of the report
  - `items` (array of TravelItem): Expenses (single reads)
    - `date` (string (date), required): Date of the expense (YYYY-MM-DD)
    - `kind` (string, required): Kind of expense; mileage items carry km and are priced with the tenant rate (one of `mileage`, `transport`, `lodging`, `other`)
    - `amountCents` (integer): Gross amount in cents; computed for mileage (km × rate)
    - `description` (string): What was paid for (max length 200)
    - `id` (string, read-only): Id of the expense
    - `km` (number): Kilometres of a mileage item
    - `merchant` (string): Issuer of the receipt (max length 200)
    - `receiptId` (string): A receipt of the same report
    - `vatCents` (integer): VAT contained in the amount, always computed from amountCents and vatRate (a sent value is ignored; record a receipt with several rates as one item per rate)
    - `vatRate` (number): VAT rate in percent
  - `note` (string): Note of the employee
  - `overnight` (boolean): The trip includes overnight stays
  - `purpose` (string): Purpose of the trip
  - `receipts` (array of TravelReceipt): Receipt files (single reads)
    - `contentType` (string): Media type of the file
    - `createdAt` (string (date-time)): When the receipt was uploaded
    - `createdBy` (string): Who uploaded the receipt (e-mail)
    - `documentId` (string): DMS document (owner module hr)
    - `fileName` (string): File name
    - `id` (string): Id of the receipt
    - `scanStatus` (string): Malware scan of the DMS (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
    - `sizeBytes` (integer): Size in bytes
  - `rejectedAt` (string (date-time)): When it was rejected last
  - `rejectedBy` (string): Who rejected it last (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
  - `releasedAt` (string (date-time)): When it was released
  - `releasedBy` (string): Who released it for payment (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
  - `startAt` (string): Local departure time (YYYY-MM-DDTHH:MM)
  - `status` (string): State of the report (one of `draft`, `submitted`, `approved`, `rejected`, `released`, `transferred`)
  - `submittedAt` (string (date-time)): When the report was submitted
  - `totalCents` (integer): Reimbursement in cents
  - `totals` (object): Drafts and rejected reports: computed with the current rates; from `submitted` on: frozen at submit.
  - `tradeDocumentNo` (string): Number of the trade document
  - `tradeTransactionId` (string): Id of the trade document created for the report
  - `transferError` (string): The last failed transfer (empty after a success)
  - `transferredAt` (string (date-time)): When it was transferred to trade
  - `updatedAt` (string (date-time)): When the report was last changed
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `total` (integer): Number of all matching reports

Example 200 answer:

```json
{
  "items": [
    {
      "approvedAt": "2026-11-07T08:15:00Z",
      "approvedBy": "tobias.hartl@muster-it.example",
      "country": "DE",
      "createdAt": "2026-11-06T07:40:00Z",
      "createdBy": "jonas.bauer@muster-it.example",
      "destination": "Alpenhotel Seeblick, Schönau am Königssee",
      "employeeId": "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c",
      "employeeName": "Jonas Bauer",
      "endAt": "2026-11-05T18:30",
      "id": "0d2f4b6d-8f0b-4d2f-8b6d-8f0b2d4f6b46",
      "overnight": true,
      "purpose": "WLAN-Ausleuchtung und Access-Point-Montage",
      "startAt": "2026-11-04T06:45",
      "status": "approved",
      "submittedAt": "2026-11-06T07:52:00Z",
      "totalCents": 23440,
      "updatedAt": "2026-11-07T08:15:00Z",
      "version": 3
    },
    {
      "country": "DE",
      "createdAt": "2026-11-14T09:05:00Z",
      "createdBy": "lena.vogel@muster-it.example",
      "destination": "Messe Nürnberg",
      "employeeId": "a4c6e8f0-2b4d-4e6f-9a1c-3e5f7b9d1c0a",
      "employeeName": "Lena Vogel",
      "endAt": "2026-11-13T19:30",
      "id": "6d8f0b2d-4f6b-4d8f-9b2d-4f6b8d0f2b49",
      "overnight": false,
      "purpose": "Messebesuch it-sa",
      "startAt": "2026-11-13T07:00",
      "status": "submitted",
      "submittedAt": "2026-11-14T09:20:00Z",
      "totalCents": 10880,
      "updatedAt": "2026-11-14T09:20:00Z",
      "version": 2
    }
  ],
  "total": 2
}
```

### Example request

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

## Start a travel expense report of the caller (tenant:access)

`POST /api/hr/v1/travel-reports`

Module: HR · operationId: `createTravelReport` · Tag: Travel expenses · Auth: access token (`Authorization: Bearer <accessToken>`)

Creates a `draft` of the signed-in employee; nobody records trips for others. The totals are
computed with the tenant's rates of each travel day (`400` on field `country` when a rate is missing).

### Request body

`application/json` (required)

- `destination` (string, required): Destination of the trip (max length 200)
- `endAt` (string, required): Local return time (YYYY-MM-DDTHH:MM)
- `purpose` (string, required): Purpose of the trip (max length 200)
- `startAt` (string, required): Local departure time (YYYY-MM-DDTHH:MM)
- `country` (string): ISO 3166-1 alpha-2 code of the destination (default DE); selects the rates
- `days` (array of TravelDay): What was provided per day (meals, lodging lump sum)
  - `breakfast` (boolean): Breakfast provided (cuts the allowance by breakfastPercent of the full-day rate)
  - `date` (string (date)): Day of the trip (YYYY-MM-DD)
  - `dinner` (boolean): Dinner was provided (reduces the meal allowance)
  - `lodgingLumpSum` (boolean): The night after this day without a hotel receipt (lodging lump sum)
  - `lunch` (boolean): Lunch was provided (reduces the meal allowance)
- `items` (array of TravelItem): Expenses; they replace the report's items
  - `date` (string (date), required): Date of the expense (YYYY-MM-DD)
  - `kind` (string, required): Kind of expense; mileage items carry km and are priced with the tenant rate (one of `mileage`, `transport`, `lodging`, `other`)
  - `amountCents` (integer): Gross amount in cents; computed for mileage (km × rate)
  - `description` (string): What was paid for (max length 200)
  - `id` (string, read-only): Id of the expense
  - `km` (number): Kilometres of a mileage item
  - `merchant` (string): Issuer of the receipt (max length 200)
  - `receiptId` (string): A receipt of the same report
  - `vatCents` (integer): VAT contained in the amount, always computed from amountCents and vatRate (a sent value is ignored; record a receipt with several rates as one item per rate)
  - `vatRate` (number): VAT rate in percent
- `note` (string): Note of the employee (max length 2000)
- `overnight` (boolean): The trip includes overnight stays (required for more than two calendar days)
- `version` (integer): Required for PATCH

Example:

```json
{
  "country": "DE",
  "days": [
    {
      "breakfast": true,
      "date": "2026-11-05"
    }
  ],
  "destination": "Alpenhotel Seeblick, Schönau am Königssee",
  "endAt": "2026-11-05T18:30",
  "items": [
    {
      "date": "2026-11-04",
      "description": "Regensburg – Schönau am Königssee und zurück",
      "kind": "mileage",
      "km": 380
    },
    {
      "amountCents": 9800,
      "date": "2026-11-05",
      "description": "Übernachtung mit Frühstück",
      "kind": "lodging",
      "merchant": "Alpenhotel Seeblick",
      "receiptId": "6f8b0d2f-4b6d-4f8b-8d2f-4b6d8f0b2d44",
      "vatRate": 7
    }
  ],
  "overnight": true,
  "purpose": "WLAN-Ausleuchtung und Access-Point-Montage",
  "startAt": "2026-11-04T06:45"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)

Fields of the 201 answer:

- `approvedAt` (string (date-time)): When it was approved
- `approvedBy` (string): Who approved (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `country` (string): ISO 3166-1 alpha-2 code of the destination; selects the allowance rates
- `createdAt` (string (date-time)): When the report was created
- `createdBy` (string): Who created the report (e-mail)
- `days` (array of TravelDay): What was provided per day (meals, lodging lump sum)
  - `breakfast` (boolean): Breakfast provided (cuts the allowance by breakfastPercent of the full-day rate)
  - `date` (string (date)): Day of the trip (YYYY-MM-DD)
  - `dinner` (boolean): Dinner was provided (reduces the meal allowance)
  - `lodgingLumpSum` (boolean): The night after this day without a hotel receipt (lodging lump sum)
  - `lunch` (boolean): Lunch was provided (reduces the meal allowance)
- `decisionNote` (string): Reason of the last rejection
- `destination` (string): Destination of the trip
- `employeeId` (string): Id of the employee
- `employeeName` (string): Display name of the employee (in lists)
- `endAt` (string): Local return time (YYYY-MM-DDTHH:MM)
- `id` (string): Id of the report
- `items` (array of TravelItem): Expenses (single reads)
  - `date` (string (date), required): Date of the expense (YYYY-MM-DD)
  - `kind` (string, required): Kind of expense; mileage items carry km and are priced with the tenant rate (one of `mileage`, `transport`, `lodging`, `other`)
  - `amountCents` (integer): Gross amount in cents; computed for mileage (km × rate)
  - `description` (string): What was paid for (max length 200)
  - `id` (string, read-only): Id of the expense
  - `km` (number): Kilometres of a mileage item
  - `merchant` (string): Issuer of the receipt (max length 200)
  - `receiptId` (string): A receipt of the same report
  - `vatCents` (integer): VAT contained in the amount, always computed from amountCents and vatRate (a sent value is ignored; record a receipt with several rates as one item per rate)
  - `vatRate` (number): VAT rate in percent
- `note` (string): Note of the employee
- `overnight` (boolean): The trip includes overnight stays
- `purpose` (string): Purpose of the trip
- `receipts` (array of TravelReceipt): Receipt files (single reads)
  - `contentType` (string): Media type of the file
  - `createdAt` (string (date-time)): When the receipt was uploaded
  - `createdBy` (string): Who uploaded the receipt (e-mail)
  - `documentId` (string): DMS document (owner module hr)
  - `fileName` (string): File name
  - `id` (string): Id of the receipt
  - `scanStatus` (string): Malware scan of the DMS (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
  - `sizeBytes` (integer): Size in bytes
- `rejectedAt` (string (date-time)): When it was rejected last
- `rejectedBy` (string): Who rejected it last (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `releasedAt` (string (date-time)): When it was released
- `releasedBy` (string): Who released it for payment (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `startAt` (string): Local departure time (YYYY-MM-DDTHH:MM)
- `status` (string): State of the report (one of `draft`, `submitted`, `approved`, `rejected`, `released`, `transferred`)
- `submittedAt` (string (date-time)): When the report was submitted
- `totalCents` (integer): Reimbursement in cents
- `totals` (object): Drafts and rejected reports: computed with the current rates; from `submitted` on: frozen at submit.
- `tradeDocumentNo` (string): Number of the trade document
- `tradeTransactionId` (string): Id of the trade document created for the report
- `transferError` (string): The last failed transfer (empty after a success)
- `transferredAt` (string (date-time)): When it was transferred to trade
- `updatedAt` (string (date-time)): When the report was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 201 answer:

```json
{
  "approvedAt": "2026-11-07T08:15:00Z",
  "approvedBy": "tobias.hartl@muster-it.example",
  "country": "DE",
  "createdAt": "2026-11-06T07:40:00Z",
  "createdBy": "jonas.bauer@muster-it.example",
  "days": [
    {
      "breakfast": true,
      "date": "2026-11-05"
    }
  ],
  "destination": "Alpenhotel Seeblick, Schönau am Königssee",
  "employeeId": "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c",
  "employeeName": "Jonas Bauer",
  "endAt": "2026-11-05T18:30",
  "id": "0d2f4b6d-8f0b-4d2f-8b6d-8f0b2d4f6b46",
  "items": [
    {
      "amountCents": 11400,
      "date": "2026-11-04",
      "description": "Regensburg – Schönau am Königssee und zurück",
      "id": "2f4b6d8f-0b2d-4f4b-9d8f-0b2d4f6b8d47",
      "kind": "mileage",
      "km": 380,
      "vatCents": 0,
      "vatRate": 0
    },
    {
      "amountCents": 9800,
      "date": "2026-11-05",
      "description": "Übernachtung mit Frühstück",
      "id": "4b6d8f0b-2d4f-4b6d-8f0b-2d4f6b8d0f48",
      "kind": "lodging",
      "merchant": "Alpenhotel Seeblick",
      "receiptId": "6f8b0d2f-4b6d-4f8b-8d2f-4b6d8f0b2d44",
      "vatCents": 641,
      "vatRate": 7
    }
  ],
  "note": "Hotelrechnung als PDF angehängt.",
  "overnight": true,
  "purpose": "WLAN-Ausleuchtung und Access-Point-Montage",
  "receipts": [
    {
      "contentType": "application/pdf",
      "createdAt": "2026-11-06T07:48:00Z",
      "createdBy": "jonas.bauer@muster-it.example",
      "documentId": "8b0d2f4b-6d8f-4b0d-9f4b-6d8f0b2d4f45",
      "fileName": "rechnung-alpenhotel-seeblick.pdf",
      "id": "6f8b0d2f-4b6d-4f8b-8d2f-4b6d8f0b2d44",
      "scanStatus": "CLEAN",
      "sizeBytes": 184320
    }
  ],
  "startAt": "2026-11-04T06:45",
  "status": "approved",
  "submittedAt": "2026-11-06T07:52:00Z",
  "totalCents": 23440,
  "totals": {
    "days": [
      {
        "allowanceCents": 1400,
        "country": "DE",
        "date": "2026-11-04",
        "deductionCents": 0,
        "hours": 17.25,
        "kind": "partial",
        "lodgingCents": 0,
        "rateCents": 1400
      },
      {
        "allowanceCents": 840,
        "country": "DE",
        "date": "2026-11-05",
        "deductionCents": 560,
        "hours": 18.5,
        "kind": "partial",
        "lodgingCents": 0,
        "rateCents": 1400
      }
    ],
    "expensesCents": 9800,
    "lodgingLumpSumCents": 0,
    "mealAllowanceCents": 2240,
    "mileageCents": 11400,
    "totalCents": 23440,
    "warnings": []
  },
  "updatedAt": "2026-11-07T08:15:00Z",
  "version": 3
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/travel-reports' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"country":"DE","days":[{"breakfast":true,"date":"2026-11-05"}],"destination":"Alpenhotel Seeblick, Schönau am Königssee","endAt":"2026-11-05T18:30","items":[{"date":"2026-11-04","description":"Regensburg – Schönau am Königssee und zurück","kind":"mileage","km":380},{"amountCents":9800,"date":"2026-11-05","description":"Übernachtung mit Frühstück","kind":"lodging","merchant":"Alpenhotel Seeblick","receiptId":"6f8b0d2f-4b6d-4f8b-8d2f-4b6d8f0b2d44","vatRate":7}],"overnight":true,"purpose":"WLAN-Ausleuchtung und Access-Point-Montage","startAt":"2026-11-04T06:45"}'
```

## Compute the reimbursement of an unsaved report (tenant:access)

`POST /api/hr/v1/travel-reports/calculate`

Module: HR · operationId: `calculateTravelReport` · Tag: Travel expenses · Auth: access token (`Authorization: Bearer <accessToken>`)

Dry run for the form; nothing is saved.

### Request body

`application/json` (required)

- `destination` (string, required): Destination of the trip (max length 200)
- `endAt` (string, required): Local return time (YYYY-MM-DDTHH:MM)
- `purpose` (string, required): Purpose of the trip (max length 200)
- `startAt` (string, required): Local departure time (YYYY-MM-DDTHH:MM)
- `country` (string): ISO 3166-1 alpha-2 code of the destination (default DE); selects the rates
- `days` (array of TravelDay): What was provided per day (meals, lodging lump sum)
  - `breakfast` (boolean): Breakfast provided (cuts the allowance by breakfastPercent of the full-day rate)
  - `date` (string (date)): Day of the trip (YYYY-MM-DD)
  - `dinner` (boolean): Dinner was provided (reduces the meal allowance)
  - `lodgingLumpSum` (boolean): The night after this day without a hotel receipt (lodging lump sum)
  - `lunch` (boolean): Lunch was provided (reduces the meal allowance)
- `items` (array of TravelItem): Expenses; they replace the report's items
  - `date` (string (date), required): Date of the expense (YYYY-MM-DD)
  - `kind` (string, required): Kind of expense; mileage items carry km and are priced with the tenant rate (one of `mileage`, `transport`, `lodging`, `other`)
  - `amountCents` (integer): Gross amount in cents; computed for mileage (km × rate)
  - `description` (string): What was paid for (max length 200)
  - `id` (string, read-only): Id of the expense
  - `km` (number): Kilometres of a mileage item
  - `merchant` (string): Issuer of the receipt (max length 200)
  - `receiptId` (string): A receipt of the same report
  - `vatCents` (integer): VAT contained in the amount, always computed from amountCents and vatRate (a sent value is ignored; record a receipt with several rates as one item per rate)
  - `vatRate` (number): VAT rate in percent
- `note` (string): Note of the employee (max length 2000)
- `overnight` (boolean): The trip includes overnight stays (required for more than two calendar days)
- `version` (integer): Required for PATCH

Example:

```json
{
  "country": "DE",
  "days": [
    {
      "breakfast": true,
      "date": "2026-11-05"
    }
  ],
  "destination": "Alpenhotel Seeblick, Schönau am Königssee",
  "endAt": "2026-11-05T18:30",
  "items": [
    {
      "date": "2026-11-04",
      "description": "Regensburg – Schönau am Königssee und zurück",
      "kind": "mileage",
      "km": 380
    },
    {
      "amountCents": 9800,
      "date": "2026-11-05",
      "description": "Übernachtung mit Frühstück",
      "kind": "lodging",
      "merchant": "Alpenhotel Seeblick",
      "receiptId": "6f8b0d2f-4b6d-4f8b-8d2f-4b6d8f0b2d44",
      "vatRate": 7
    }
  ],
  "overnight": true,
  "purpose": "WLAN-Ausleuchtung und Access-Point-Montage",
  "startAt": "2026-11-04T06:45"
}
```

### Responses

- **200** Totals (`application/json`)
- **400** Error (`application/json`)

Fields of the 200 answer:

- `days` (array of object): Allowance per day
  - `allowanceCents` (integer): Meal allowance of the day in cents
  - `country` (string): Country whose rates apply (ISO 3166-1 alpha-2)
  - `date` (string (date)): The day (YYYY-MM-DD)
  - `deductionCents` (integer): Deduction for provided meals in cents
  - `hours` (number): Hours away on the day
  - `kind` (string): full (24 h), partial (arrival or departure day, or more than 8 h) or none (one of `full`, `partial`, `none`)
  - `lodgingCents` (integer): Lodging lump sum of the night after the day in cents
  - `rateCents` (integer): Allowance rate of the day in cents
- `expensesCents` (integer): Receipted expenses in cents
- `lodgingLumpSumCents` (integer): Lodging lump sums in cents
- `mealAllowanceCents` (integer): Meal allowance in cents (after deductions for provided meals)
- `mileageCents` (integer): Mileage allowance in cents
- `totalCents` (integer): Total reimbursement in cents
- `warnings` (array of string): Hints that never block (missing receipts, lump sum next to a hotel receipt)

Example 200 answer:

```json
{
  "days": [
    {
      "allowanceCents": 1400,
      "country": "DE",
      "date": "2026-11-04",
      "deductionCents": 0,
      "hours": 17.25,
      "kind": "partial",
      "lodgingCents": 0,
      "rateCents": 1400
    },
    {
      "allowanceCents": 840,
      "country": "DE",
      "date": "2026-11-05",
      "deductionCents": 560,
      "hours": 18.5,
      "kind": "partial",
      "lodgingCents": 0,
      "rateCents": 1400
    }
  ],
  "expensesCents": 9800,
  "lodgingLumpSumCents": 0,
  "mealAllowanceCents": 2240,
  "mileageCents": 11400,
  "totalCents": 23440,
  "warnings": []
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/travel-reports/calculate' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"country":"DE","days":[{"breakfast":true,"date":"2026-11-05"}],"destination":"Alpenhotel Seeblick, Schönau am Königssee","endAt":"2026-11-05T18:30","items":[{"date":"2026-11-04","description":"Regensburg – Schönau am Königssee und zurück","kind":"mileage","km":380},{"amountCents":9800,"date":"2026-11-05","description":"Übernachtung mit Frühstück","kind":"lodging","merchant":"Alpenhotel Seeblick","receiptId":"6f8b0d2f-4b6d-4f8b-8d2f-4b6d8f0b2d44","vatRate":7}],"overnight":true,"purpose":"WLAN-Ausleuchtung und Access-Point-Montage","startAt":"2026-11-04T06:45"}'
```

## One travel expense report with items, receipts and totals

`GET /api/hr/v1/travel-reports/{id}`

Module: HR · operationId: `getTravelReport` · Tag: Travel expenses · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Report (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `approvedAt` (string (date-time)): When it was approved
- `approvedBy` (string): Who approved (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `country` (string): ISO 3166-1 alpha-2 code of the destination; selects the allowance rates
- `createdAt` (string (date-time)): When the report was created
- `createdBy` (string): Who created the report (e-mail)
- `days` (array of TravelDay): What was provided per day (meals, lodging lump sum)
  - `breakfast` (boolean): Breakfast provided (cuts the allowance by breakfastPercent of the full-day rate)
  - `date` (string (date)): Day of the trip (YYYY-MM-DD)
  - `dinner` (boolean): Dinner was provided (reduces the meal allowance)
  - `lodgingLumpSum` (boolean): The night after this day without a hotel receipt (lodging lump sum)
  - `lunch` (boolean): Lunch was provided (reduces the meal allowance)
- `decisionNote` (string): Reason of the last rejection
- `destination` (string): Destination of the trip
- `employeeId` (string): Id of the employee
- `employeeName` (string): Display name of the employee (in lists)
- `endAt` (string): Local return time (YYYY-MM-DDTHH:MM)
- `id` (string): Id of the report
- `items` (array of TravelItem): Expenses (single reads)
  - `date` (string (date), required): Date of the expense (YYYY-MM-DD)
  - `kind` (string, required): Kind of expense; mileage items carry km and are priced with the tenant rate (one of `mileage`, `transport`, `lodging`, `other`)
  - `amountCents` (integer): Gross amount in cents; computed for mileage (km × rate)
  - `description` (string): What was paid for (max length 200)
  - `id` (string, read-only): Id of the expense
  - `km` (number): Kilometres of a mileage item
  - `merchant` (string): Issuer of the receipt (max length 200)
  - `receiptId` (string): A receipt of the same report
  - `vatCents` (integer): VAT contained in the amount, always computed from amountCents and vatRate (a sent value is ignored; record a receipt with several rates as one item per rate)
  - `vatRate` (number): VAT rate in percent
- `note` (string): Note of the employee
- `overnight` (boolean): The trip includes overnight stays
- `purpose` (string): Purpose of the trip
- `receipts` (array of TravelReceipt): Receipt files (single reads)
  - `contentType` (string): Media type of the file
  - `createdAt` (string (date-time)): When the receipt was uploaded
  - `createdBy` (string): Who uploaded the receipt (e-mail)
  - `documentId` (string): DMS document (owner module hr)
  - `fileName` (string): File name
  - `id` (string): Id of the receipt
  - `scanStatus` (string): Malware scan of the DMS (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
  - `sizeBytes` (integer): Size in bytes
- `rejectedAt` (string (date-time)): When it was rejected last
- `rejectedBy` (string): Who rejected it last (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `releasedAt` (string (date-time)): When it was released
- `releasedBy` (string): Who released it for payment (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `startAt` (string): Local departure time (YYYY-MM-DDTHH:MM)
- `status` (string): State of the report (one of `draft`, `submitted`, `approved`, `rejected`, `released`, `transferred`)
- `submittedAt` (string (date-time)): When the report was submitted
- `totalCents` (integer): Reimbursement in cents
- `totals` (object): Drafts and rejected reports: computed with the current rates; from `submitted` on: frozen at submit.
- `tradeDocumentNo` (string): Number of the trade document
- `tradeTransactionId` (string): Id of the trade document created for the report
- `transferError` (string): The last failed transfer (empty after a success)
- `transferredAt` (string (date-time)): When it was transferred to trade
- `updatedAt` (string (date-time)): When the report was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "approvedAt": "2026-11-07T08:15:00Z",
  "approvedBy": "tobias.hartl@muster-it.example",
  "country": "DE",
  "createdAt": "2026-11-06T07:40:00Z",
  "createdBy": "jonas.bauer@muster-it.example",
  "days": [
    {
      "breakfast": true,
      "date": "2026-11-05"
    }
  ],
  "destination": "Alpenhotel Seeblick, Schönau am Königssee",
  "employeeId": "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c",
  "employeeName": "Jonas Bauer",
  "endAt": "2026-11-05T18:30",
  "id": "0d2f4b6d-8f0b-4d2f-8b6d-8f0b2d4f6b46",
  "items": [
    {
      "amountCents": 11400,
      "date": "2026-11-04",
      "description": "Regensburg – Schönau am Königssee und zurück",
      "id": "2f4b6d8f-0b2d-4f4b-9d8f-0b2d4f6b8d47",
      "kind": "mileage",
      "km": 380,
      "vatCents": 0,
      "vatRate": 0
    },
    {
      "amountCents": 9800,
      "date": "2026-11-05",
      "description": "Übernachtung mit Frühstück",
      "id": "4b6d8f0b-2d4f-4b6d-8f0b-2d4f6b8d0f48",
      "kind": "lodging",
      "merchant": "Alpenhotel Seeblick",
      "receiptId": "6f8b0d2f-4b6d-4f8b-8d2f-4b6d8f0b2d44",
      "vatCents": 641,
      "vatRate": 7
    }
  ],
  "note": "Hotelrechnung als PDF angehängt.",
  "overnight": true,
  "purpose": "WLAN-Ausleuchtung und Access-Point-Montage",
  "receipts": [
    {
      "contentType": "application/pdf",
      "createdAt": "2026-11-06T07:48:00Z",
      "createdBy": "jonas.bauer@muster-it.example",
      "documentId": "8b0d2f4b-6d8f-4b0d-9f4b-6d8f0b2d4f45",
      "fileName": "rechnung-alpenhotel-seeblick.pdf",
      "id": "6f8b0d2f-4b6d-4f8b-8d2f-4b6d8f0b2d44",
      "scanStatus": "CLEAN",
      "sizeBytes": 184320
    }
  ],
  "startAt": "2026-11-04T06:45",
  "status": "approved",
  "submittedAt": "2026-11-06T07:52:00Z",
  "totalCents": 23440,
  "totals": {
    "days": [
      {
        "allowanceCents": 1400,
        "country": "DE",
        "date": "2026-11-04",
        "deductionCents": 0,
        "hours": 17.25,
        "kind": "partial",
        "lodgingCents": 0,
        "rateCents": 1400
      },
      {
        "allowanceCents": 840,
        "country": "DE",
        "date": "2026-11-05",
        "deductionCents": 560,
        "hours": 18.5,
        "kind": "partial",
        "lodgingCents": 0,
        "rateCents": 1400
      }
    ],
    "expensesCents": 9800,
    "lodgingLumpSumCents": 0,
    "mealAllowanceCents": 2240,
    "mileageCents": 11400,
    "totalCents": 23440,
    "warnings": []
  },
  "updatedAt": "2026-11-07T08:15:00Z",
  "version": 3
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/travel-reports/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Delete a draft of the caller

`DELETE /api/hr/v1/travel-reports/{id}`

Module: HR · operationId: `deleteTravelReport` · Tag: Travel expenses · Auth: access token (`Authorization: Bearer <accessToken>`)

The receipts stay in the DMS (owner module hr) under its retention rules.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/hr/v1/travel-reports/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change a draft or rejected report of the caller

`PATCH /api/hr/v1/travel-reports/{id}`

Module: HR · operationId: `updateTravelReport` · Tag: Travel expenses · Auth: access token (`Authorization: Bearer <accessToken>`)

Replaces the header, the days and the items; send the `version` you read.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `destination` (string, required): Destination of the trip (max length 200)
- `endAt` (string, required): Local return time (YYYY-MM-DDTHH:MM)
- `purpose` (string, required): Purpose of the trip (max length 200)
- `startAt` (string, required): Local departure time (YYYY-MM-DDTHH:MM)
- `country` (string): ISO 3166-1 alpha-2 code of the destination (default DE); selects the rates
- `days` (array of TravelDay): What was provided per day (meals, lodging lump sum)
  - `breakfast` (boolean): Breakfast provided (cuts the allowance by breakfastPercent of the full-day rate)
  - `date` (string (date)): Day of the trip (YYYY-MM-DD)
  - `dinner` (boolean): Dinner was provided (reduces the meal allowance)
  - `lodgingLumpSum` (boolean): The night after this day without a hotel receipt (lodging lump sum)
  - `lunch` (boolean): Lunch was provided (reduces the meal allowance)
- `items` (array of TravelItem): Expenses; they replace the report's items
  - `date` (string (date), required): Date of the expense (YYYY-MM-DD)
  - `kind` (string, required): Kind of expense; mileage items carry km and are priced with the tenant rate (one of `mileage`, `transport`, `lodging`, `other`)
  - `amountCents` (integer): Gross amount in cents; computed for mileage (km × rate)
  - `description` (string): What was paid for (max length 200)
  - `id` (string, read-only): Id of the expense
  - `km` (number): Kilometres of a mileage item
  - `merchant` (string): Issuer of the receipt (max length 200)
  - `receiptId` (string): A receipt of the same report
  - `vatCents` (integer): VAT contained in the amount, always computed from amountCents and vatRate (a sent value is ignored; record a receipt with several rates as one item per rate)
  - `vatRate` (number): VAT rate in percent
- `note` (string): Note of the employee (max length 2000)
- `overnight` (boolean): The trip includes overnight stays (required for more than two calendar days)
- `version` (integer): Required for PATCH

Example:

```json
{
  "country": "DE",
  "days": [
    {
      "breakfast": true,
      "date": "2026-11-05"
    }
  ],
  "destination": "Alpenhotel Seeblick, Schönau am Königssee",
  "endAt": "2026-11-05T18:30",
  "items": [
    {
      "date": "2026-11-04",
      "description": "Regensburg – Schönau am Königssee und zurück",
      "kind": "mileage",
      "km": 380
    },
    {
      "amountCents": 9800,
      "date": "2026-11-05",
      "description": "Übernachtung mit Frühstück",
      "kind": "lodging",
      "merchant": "Alpenhotel Seeblick",
      "receiptId": "6f8b0d2f-4b6d-4f8b-8d2f-4b6d8f0b2d44",
      "vatRate": 7
    }
  ],
  "note": "Hotelrechnung als PDF angehängt.",
  "overnight": true,
  "purpose": "WLAN-Ausleuchtung und Access-Point-Montage",
  "startAt": "2026-11-04T06:45",
  "version": 1
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `approvedAt` (string (date-time)): When it was approved
- `approvedBy` (string): Who approved (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `country` (string): ISO 3166-1 alpha-2 code of the destination; selects the allowance rates
- `createdAt` (string (date-time)): When the report was created
- `createdBy` (string): Who created the report (e-mail)
- `days` (array of TravelDay): What was provided per day (meals, lodging lump sum)
  - `breakfast` (boolean): Breakfast provided (cuts the allowance by breakfastPercent of the full-day rate)
  - `date` (string (date)): Day of the trip (YYYY-MM-DD)
  - `dinner` (boolean): Dinner was provided (reduces the meal allowance)
  - `lodgingLumpSum` (boolean): The night after this day without a hotel receipt (lodging lump sum)
  - `lunch` (boolean): Lunch was provided (reduces the meal allowance)
- `decisionNote` (string): Reason of the last rejection
- `destination` (string): Destination of the trip
- `employeeId` (string): Id of the employee
- `employeeName` (string): Display name of the employee (in lists)
- `endAt` (string): Local return time (YYYY-MM-DDTHH:MM)
- `id` (string): Id of the report
- `items` (array of TravelItem): Expenses (single reads)
  - `date` (string (date), required): Date of the expense (YYYY-MM-DD)
  - `kind` (string, required): Kind of expense; mileage items carry km and are priced with the tenant rate (one of `mileage`, `transport`, `lodging`, `other`)
  - `amountCents` (integer): Gross amount in cents; computed for mileage (km × rate)
  - `description` (string): What was paid for (max length 200)
  - `id` (string, read-only): Id of the expense
  - `km` (number): Kilometres of a mileage item
  - `merchant` (string): Issuer of the receipt (max length 200)
  - `receiptId` (string): A receipt of the same report
  - `vatCents` (integer): VAT contained in the amount, always computed from amountCents and vatRate (a sent value is ignored; record a receipt with several rates as one item per rate)
  - `vatRate` (number): VAT rate in percent
- `note` (string): Note of the employee
- `overnight` (boolean): The trip includes overnight stays
- `purpose` (string): Purpose of the trip
- `receipts` (array of TravelReceipt): Receipt files (single reads)
  - `contentType` (string): Media type of the file
  - `createdAt` (string (date-time)): When the receipt was uploaded
  - `createdBy` (string): Who uploaded the receipt (e-mail)
  - `documentId` (string): DMS document (owner module hr)
  - `fileName` (string): File name
  - `id` (string): Id of the receipt
  - `scanStatus` (string): Malware scan of the DMS (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
  - `sizeBytes` (integer): Size in bytes
- `rejectedAt` (string (date-time)): When it was rejected last
- `rejectedBy` (string): Who rejected it last (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `releasedAt` (string (date-time)): When it was released
- `releasedBy` (string): Who released it for payment (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `startAt` (string): Local departure time (YYYY-MM-DDTHH:MM)
- `status` (string): State of the report (one of `draft`, `submitted`, `approved`, `rejected`, `released`, `transferred`)
- `submittedAt` (string (date-time)): When the report was submitted
- `totalCents` (integer): Reimbursement in cents
- `totals` (object): Drafts and rejected reports: computed with the current rates; from `submitted` on: frozen at submit.
- `tradeDocumentNo` (string): Number of the trade document
- `tradeTransactionId` (string): Id of the trade document created for the report
- `transferError` (string): The last failed transfer (empty after a success)
- `transferredAt` (string (date-time)): When it was transferred to trade
- `updatedAt` (string (date-time)): When the report was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "approvedAt": "2026-11-07T08:15:00Z",
  "approvedBy": "tobias.hartl@muster-it.example",
  "country": "DE",
  "createdAt": "2026-11-06T07:40:00Z",
  "createdBy": "jonas.bauer@muster-it.example",
  "days": [
    {
      "breakfast": true,
      "date": "2026-11-05"
    }
  ],
  "destination": "Alpenhotel Seeblick, Schönau am Königssee",
  "employeeId": "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c",
  "employeeName": "Jonas Bauer",
  "endAt": "2026-11-05T18:30",
  "id": "0d2f4b6d-8f0b-4d2f-8b6d-8f0b2d4f6b46",
  "items": [
    {
      "amountCents": 11400,
      "date": "2026-11-04",
      "description": "Regensburg – Schönau am Königssee und zurück",
      "id": "2f4b6d8f-0b2d-4f4b-9d8f-0b2d4f6b8d47",
      "kind": "mileage",
      "km": 380,
      "vatCents": 0,
      "vatRate": 0
    },
    {
      "amountCents": 9800,
      "date": "2026-11-05",
      "description": "Übernachtung mit Frühstück",
      "id": "4b6d8f0b-2d4f-4b6d-8f0b-2d4f6b8d0f48",
      "kind": "lodging",
      "merchant": "Alpenhotel Seeblick",
      "receiptId": "6f8b0d2f-4b6d-4f8b-8d2f-4b6d8f0b2d44",
      "vatCents": 641,
      "vatRate": 7
    }
  ],
  "note": "Hotelrechnung als PDF angehängt.",
  "overnight": true,
  "purpose": "WLAN-Ausleuchtung und Access-Point-Montage",
  "receipts": [
    {
      "contentType": "application/pdf",
      "createdAt": "2026-11-06T07:48:00Z",
      "createdBy": "jonas.bauer@muster-it.example",
      "documentId": "8b0d2f4b-6d8f-4b0d-9f4b-6d8f0b2d4f45",
      "fileName": "rechnung-alpenhotel-seeblick.pdf",
      "id": "6f8b0d2f-4b6d-4f8b-8d2f-4b6d8f0b2d44",
      "scanStatus": "CLEAN",
      "sizeBytes": 184320
    }
  ],
  "startAt": "2026-11-04T06:45",
  "status": "approved",
  "submittedAt": "2026-11-06T07:52:00Z",
  "totalCents": 23440,
  "totals": {
    "days": [
      {
        "allowanceCents": 1400,
        "country": "DE",
        "date": "2026-11-04",
        "deductionCents": 0,
        "hours": 17.25,
        "kind": "partial",
        "lodgingCents": 0,
        "rateCents": 1400
      },
      {
        "allowanceCents": 840,
        "country": "DE",
        "date": "2026-11-05",
        "deductionCents": 560,
        "hours": 18.5,
        "kind": "partial",
        "lodgingCents": 0,
        "rateCents": 1400
      }
    ],
    "expensesCents": 9800,
    "lodgingLumpSumCents": 0,
    "mealAllowanceCents": 2240,
    "mileageCents": 11400,
    "totalCents": 23440,
    "warnings": []
  },
  "updatedAt": "2026-11-07T08:15:00Z",
  "version": 3
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/hr/v1/travel-reports/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"country":"DE","days":[{"breakfast":true,"date":"2026-11-05"}],"destination":"Alpenhotel Seeblick, Schönau am Königssee","endAt":"2026-11-05T18:30","items":[{"date":"2026-11-04","description":"Regensburg – Schönau am Königssee und zurück","kind":"mileage","km":380},{"amountCents":9800,"date":"2026-11-05","description":"Übernachtung mit Frühstück","kind":"lodging","merchant":"Alpenhotel Seeblick","receiptId":"6f8b0d2f-4b6d-4f8b-8d2f-4b6d8f0b2d44","vatRate":7}],"note":"Hotelrechnung als PDF angehängt.","overnight":true,"purpose":"WLAN-Ausleuchtung und Access-Point-Montage","startAt":"2026-11-04T06:45","version":1}'
```

## Submit, recall, approve, reject, release or transfer a report

`POST /api/hr/v1/travel-reports/{id}/{action}`

Module: HR · operationId: `runTravelReportAction` · Tag: Travel expenses · Auth: access token (`Authorization: Bearer <accessToken>`)

- `submit` (owner, `draft`/`rejected` → `submitted`): recomputes the totals and freezes them – approval,
  `totals` and the transfer use them, whatever the rates say later; `422 infected` while a
  receipt the malware scan flagged is attached, `422 scan_failed` while one could not be checked. `recall` (owner, `submitted` → `draft`).
- `approve` / `reject` (`submitted`): the responsible managers and `hr:travel:approve`; a reason
  (`note`) is required to reject. Accounting (`hr:travel:manage`) may also reject `approved` reports.
- `release` (`approved` → `released`) and `transfer` (`released` → `transferred`): `hr:travel:manage`.
  The transfer creates a trade document (`transactionType`, default `TRAVEL_EXPENSE`) for the
  employee's masterdata address (`400` on field `addressId` while it does not exist yet), one line per
  allowance and expense (the frozen totals; net unit price with 4 decimals, so net × VAT rate is the
  reimbursed amount). Trade derives the document from the reference `hr-travel:<id>`, so a repeated
  transfer never creates a second one. A failure answers `502 transfer_failed`, is kept in
  `transferError` and can be retried.

Nobody approves, releases or transfers their own report (`403`); not allowed in the current
status: `409 invalid_state`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `action` | path | string | yes | (one of `submit`, `recall`, `approve`, `reject`, `release`, `transfer`) |

### Request body

`application/json` (required)

- `version` (integer, required): Version of the report the action is based on
- `note` (string): Reason of a rejection (max length 2000)

Example:

```json
{
  "note": "Bitte den Parkbeleg nachreichen, dann gebe ich die Abrechnung frei.",
  "version": 2
}
```

### Responses

- **200** Done (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)
- **502** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 200 answer:

- `approvedAt` (string (date-time)): When it was approved
- `approvedBy` (string): Who approved (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `country` (string): ISO 3166-1 alpha-2 code of the destination; selects the allowance rates
- `createdAt` (string (date-time)): When the report was created
- `createdBy` (string): Who created the report (e-mail)
- `days` (array of TravelDay): What was provided per day (meals, lodging lump sum)
  - `breakfast` (boolean): Breakfast provided (cuts the allowance by breakfastPercent of the full-day rate)
  - `date` (string (date)): Day of the trip (YYYY-MM-DD)
  - `dinner` (boolean): Dinner was provided (reduces the meal allowance)
  - `lodgingLumpSum` (boolean): The night after this day without a hotel receipt (lodging lump sum)
  - `lunch` (boolean): Lunch was provided (reduces the meal allowance)
- `decisionNote` (string): Reason of the last rejection
- `destination` (string): Destination of the trip
- `employeeId` (string): Id of the employee
- `employeeName` (string): Display name of the employee (in lists)
- `endAt` (string): Local return time (YYYY-MM-DDTHH:MM)
- `id` (string): Id of the report
- `items` (array of TravelItem): Expenses (single reads)
  - `date` (string (date), required): Date of the expense (YYYY-MM-DD)
  - `kind` (string, required): Kind of expense; mileage items carry km and are priced with the tenant rate (one of `mileage`, `transport`, `lodging`, `other`)
  - `amountCents` (integer): Gross amount in cents; computed for mileage (km × rate)
  - `description` (string): What was paid for (max length 200)
  - `id` (string, read-only): Id of the expense
  - `km` (number): Kilometres of a mileage item
  - `merchant` (string): Issuer of the receipt (max length 200)
  - `receiptId` (string): A receipt of the same report
  - `vatCents` (integer): VAT contained in the amount, always computed from amountCents and vatRate (a sent value is ignored; record a receipt with several rates as one item per rate)
  - `vatRate` (number): VAT rate in percent
- `note` (string): Note of the employee
- `overnight` (boolean): The trip includes overnight stays
- `purpose` (string): Purpose of the trip
- `receipts` (array of TravelReceipt): Receipt files (single reads)
  - `contentType` (string): Media type of the file
  - `createdAt` (string (date-time)): When the receipt was uploaded
  - `createdBy` (string): Who uploaded the receipt (e-mail)
  - `documentId` (string): DMS document (owner module hr)
  - `fileName` (string): File name
  - `id` (string): Id of the receipt
  - `scanStatus` (string): Malware scan of the DMS (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
  - `sizeBytes` (integer): Size in bytes
- `rejectedAt` (string (date-time)): When it was rejected last
- `rejectedBy` (string): Who rejected it last (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `releasedAt` (string (date-time)): When it was released
- `releasedBy` (string): Who released it for payment (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `startAt` (string): Local departure time (YYYY-MM-DDTHH:MM)
- `status` (string): State of the report (one of `draft`, `submitted`, `approved`, `rejected`, `released`, `transferred`)
- `submittedAt` (string (date-time)): When the report was submitted
- `totalCents` (integer): Reimbursement in cents
- `totals` (object): Drafts and rejected reports: computed with the current rates; from `submitted` on: frozen at submit.
- `tradeDocumentNo` (string): Number of the trade document
- `tradeTransactionId` (string): Id of the trade document created for the report
- `transferError` (string): The last failed transfer (empty after a success)
- `transferredAt` (string (date-time)): When it was transferred to trade
- `updatedAt` (string (date-time)): When the report was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "approvedAt": "2026-11-07T08:15:00Z",
  "approvedBy": "tobias.hartl@muster-it.example",
  "country": "DE",
  "createdAt": "2026-11-06T07:40:00Z",
  "createdBy": "jonas.bauer@muster-it.example",
  "days": [
    {
      "breakfast": true,
      "date": "2026-11-05"
    }
  ],
  "destination": "Alpenhotel Seeblick, Schönau am Königssee",
  "employeeId": "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c",
  "employeeName": "Jonas Bauer",
  "endAt": "2026-11-05T18:30",
  "id": "0d2f4b6d-8f0b-4d2f-8b6d-8f0b2d4f6b46",
  "items": [
    {
      "amountCents": 11400,
      "date": "2026-11-04",
      "description": "Regensburg – Schönau am Königssee und zurück",
      "id": "2f4b6d8f-0b2d-4f4b-9d8f-0b2d4f6b8d47",
      "kind": "mileage",
      "km": 380,
      "vatCents": 0,
      "vatRate": 0
    },
    {
      "amountCents": 9800,
      "date": "2026-11-05",
      "description": "Übernachtung mit Frühstück",
      "id": "4b6d8f0b-2d4f-4b6d-8f0b-2d4f6b8d0f48",
      "kind": "lodging",
      "merchant": "Alpenhotel Seeblick",
      "receiptId": "6f8b0d2f-4b6d-4f8b-8d2f-4b6d8f0b2d44",
      "vatCents": 641,
      "vatRate": 7
    }
  ],
  "note": "Hotelrechnung als PDF angehängt.",
  "overnight": true,
  "purpose": "WLAN-Ausleuchtung und Access-Point-Montage",
  "receipts": [
    {
      "contentType": "application/pdf",
      "createdAt": "2026-11-06T07:48:00Z",
      "createdBy": "jonas.bauer@muster-it.example",
      "documentId": "8b0d2f4b-6d8f-4b0d-9f4b-6d8f0b2d4f45",
      "fileName": "rechnung-alpenhotel-seeblick.pdf",
      "id": "6f8b0d2f-4b6d-4f8b-8d2f-4b6d8f0b2d44",
      "scanStatus": "CLEAN",
      "sizeBytes": 184320
    }
  ],
  "startAt": "2026-11-04T06:45",
  "status": "approved",
  "submittedAt": "2026-11-06T07:52:00Z",
  "totalCents": 23440,
  "totals": {
    "days": [
      {
        "allowanceCents": 1400,
        "country": "DE",
        "date": "2026-11-04",
        "deductionCents": 0,
        "hours": 17.25,
        "kind": "partial",
        "lodgingCents": 0,
        "rateCents": 1400
      },
      {
        "allowanceCents": 840,
        "country": "DE",
        "date": "2026-11-05",
        "deductionCents": 560,
        "hours": 18.5,
        "kind": "partial",
        "lodgingCents": 0,
        "rateCents": 1400
      }
    ],
    "expensesCents": 9800,
    "lodgingLumpSumCents": 0,
    "mealAllowanceCents": 2240,
    "mileageCents": 11400,
    "totalCents": 23440,
    "warnings": []
  },
  "updatedAt": "2026-11-07T08:15:00Z",
  "version": 3
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/travel-reports/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/submit' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"note":"Bitte den Parkbeleg nachreichen, dann gebe ich die Abrechnung frei.","version":2}'
```

## Attach a receipt to a draft or rejected report of the caller

`POST /api/hr/v1/travel-reports/{id}/receipts`

Module: HR · operationId: `uploadTravelReceipt` · Tag: Travel expenses · Auth: access token (`Authorization: Bearer <accessToken>`)

A photo (JPEG, PNG, WebP, HEIC) or PDF of at most 15 MB as multipart field `file`. The file is
stored in the DMS, which scans it for malware: until the scan is `CLEAN` it is neither served nor
read; an `INFECTED` receipt is refused (`422 infected`). When the DMS cannot take the file while a scan has
not finished, nothing is stored and the answer is `503 scan_pending` with `Retry-After` (seconds): send the
same upload again after it.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`multipart/form-data` (required)

- `file` (string (binary), required): The receipt (photo or PDF)

### Responses

- **201** Stored (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **413** Error (`application/json`)
- **422** Error (`application/json`)
- **503** The DMS is unavailable, or cannot take the file while a malware scan runs (`scan_pending`) – retry (`application/json`)

Fields of the 201 answer:

- `contentType` (string): Media type of the file
- `createdAt` (string (date-time)): When the receipt was uploaded
- `createdBy` (string): Who uploaded the receipt (e-mail)
- `documentId` (string): DMS document (owner module hr)
- `fileName` (string): File name
- `id` (string): Id of the receipt
- `scanStatus` (string): Malware scan of the DMS (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
- `sizeBytes` (integer): Size in bytes

Example 201 answer:

```json
{
  "contentType": "application/pdf",
  "createdAt": "2026-11-06T07:48:00Z",
  "createdBy": "jonas.bauer@muster-it.example",
  "documentId": "8b0d2f4b-6d8f-4b0d-9f4b-6d8f0b2d4f45",
  "fileName": "rechnung-alpenhotel-seeblick.pdf",
  "id": "6f8b0d2f-4b6d-4f8b-8d2f-4b6d8f0b2d44",
  "scanStatus": "CLEAN",
  "sizeBytes": 184320
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/travel-reports/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/receipts' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@document.pdf'
```

## Remove a receipt from a draft or rejected report of the caller

`DELETE /api/hr/v1/travel-reports/{id}/receipts/{receiptId}`

Module: HR · operationId: `deleteTravelReceipt` · Tag: Travel expenses · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `receiptId` | path | string (uuid) | yes |  |

### Responses

- **204** Removed
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/hr/v1/travel-reports/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/receipts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## The file of a receipt

`GET /api/hr/v1/travel-reports/{id}/receipts/{receiptId}/content`

Module: HR · operationId: `getTravelReceiptContent` · Tag: Travel expenses · Auth: access token (`Authorization: Bearer <accessToken>`)

Only receipts the malware scan cleared: `409 scan_pending`, `422 infected`, `422 scan_failed` otherwise (also when the scan was skipped – unscanned files are never served).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `receiptId` | path | string (uuid) | yes |  |

### Responses

- **200** The file (`application/pdf`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)
- **503** Error (`application/json`)

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/travel-reports/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/receipts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/content' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Read a receipt (photo or PDF) with AI into a draft expense

`POST /api/hr/v1/travel-reports/{id}/receipts/{receiptId}/extract`

Module: HR · operationId: `extractTravelReceipt` · Tag: Travel expenses · Auth: access token (`Authorization: Bearer <accessToken>`)

Extraction of date, merchant, amount and VAT of a clean receipt: a photo is read with OCR, a PDF
through the text the DMS extracted from it. The answer is a draft only – nothing is saved; the
person checks it and saves the report. `409 receipt_reading` while the DMS is still reading the
PDF (retry shortly), `422 receipt_no_text` when the PDF has no readable text (encrypted, failed
or empty – enter the expense by hand), `503 unavailable` when AI is not configured or fails.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `receiptId` | path | string (uuid) | yes |  |

### Responses

- **200** Draft (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 200 answer:

- `amountCents` (integer): Gross amount in cents
- `date` (string (date)): Date of the receipt (YYYY-MM-DD)
- `description` (string): What was paid for
- `kind` (string): Kind of expense (one of `transport`, `lodging`, `other`)
- `merchant` (string): Issuer of the receipt
- `vatCents` (integer): VAT contained in the amount, in cents
- `vatRate` (number): VAT rate in percent

Example 200 answer:

```json
{
  "amountCents": 9800,
  "date": "2026-11-05",
  "description": "Übernachtung mit Frühstück",
  "kind": "lodging",
  "merchant": "Alpenhotel Seeblick",
  "vatCents": 641,
  "vatRate": 7
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/travel-reports/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/receipts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/extract' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Work entries

## Work entries of an employee (tenant:access – own; a team member's as line manager or deputy; anyone's with hr:work:manage)

`GET /api/hr/v1/work-entries`

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

`employeeId` empty or `me` is the caller (`403 no_employee` without an active employee record); another
person the caller does not decide for answers `404`. The period defaults to today (`to` = `from`), at most a
year. With `subject` the entries on that subject are listed whatever their day (`from`/`to` are ignored),
newest first – the list at a ticket, item or activity. Labels of subjects are the snapshots taken at booking
time: listing never asks another module. Entries are ordered by work date, then by start (entries with a start
first), then by creation.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `employeeId` | query | string |  | Empty or `me` for the caller |
| `subject` | query | string |  | Only the entries on this subject (e.g. `desk:item:<id>`), every day, newest first (max length 200) |
| `from` | query | string (date) |  | First work day (default today) |
| `to` | query | string (date) |  | Last work day (default from) |
| `state` | query | string |  | (one of `suggested`, `confirmed`, `approved`, `billed`) |
| `limit` | query | integer |  | 1–200; another value is a 400 invalid. (default `50`; max 200) |
| `offset` | query | integer |  | (default `0`) |

### Responses

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

Fields of the 200 answer:

- `items` (array of WorkEntry, required): Entries of this page
  - `approvedAt` (string (date-time), nullable): When the entry was approved
  - `approvedBy` (string): Who approved the entry (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
  - `article` (WorkArticleRef | null): Masterdata article a flat-rate entry is billed as
  - `batchId` (string (uuid), nullable): Billing batch the entry is billed in
  - `billableMinutes` (integer): Minutes billed
  - `billedRate` (number, nullable): Hourly rate (or article price) the entry was billed at
  - `billing` (string): Key of a billing type
  - `contract` (WorkContractRef | null): Trade contract that decides billing
  - `correctionOf` (string (uuid), nullable): The approved or billed entry this one corrects; its minutes are the difference (may be negative)
  - `createdAt` (string (date-time)): When the work entry was created
  - `createdBy` (string): Who booked the entry (e-mail)
  - `customer` (WorkCustomerRef | null): Customer the work is billed to
  - `description` (string): What was done
  - `durationSeconds` (integer): The exact length in seconds (the stopwatch's seconds, else `minutes` × 60)
  - `employeeId` (string (uuid)): Id of the employee
  - `employeeName` (string): Display name of the employee – only in `listApprovableWorkEntries`
  - `endedAt` (string (date-time), nullable): `null` for the running stopwatch and for an entry without a span
  - `id` (string (uuid)): Id of the work entry
  - `kind` (string): Key of a work kind (`getWorkEntrySettings`)
  - `km` (number): Kilometres travelled (kinds that allow travel)
  - `minutes` (integer): The length in minutes that sums and billing use (a correction's difference, may be negative; 0 for a stopwatch run that rounded to nothing)
  - `origin` (string): The call or appointment the time comes from: `comms:interaction:<id>` or `comms:calendar:<id>`; omitted for other work. Booked at most once per tenant (`409 already_booked`)
  - `project` (WorkProjectRef | null): Project the work counts for
  - `running` (boolean): The running stopwatch entry (start, no end)
  - `source` (string): How the entry was booked (one of `manual`, `stopwatch`, `interaction`, `calendar`, `correction`)
  - `startedAt` (string (date-time), nullable): `null` for an entry booked as a length only
  - `state` (string): suggested → confirmed → approved → billed (one of `suggested`, `confirmed`, `approved`, `billed`)
  - `subject` (string): What was worked on: `desk:item:<id>`, `forge:item:<id>`, `crm:activity:<id>`, a project `desk:project:<id>` / `forge:project:<id>`; empty for work on the customer only or internal work
  - `subjectLabel` (string): The subject's name at booking time (the origin's without a subject)
  - `travelMinutes` (integer): Travel time in minutes (kinds that allow travel)
  - `updatedAt` (string (date-time)): When the work entry was last changed
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
  - `workDate` (string (date)): The day the work counts for (the person's choice; with a start its day in the tenant's time zone)
- `total` (integer): Number of all matching entries

Example 200 answer:

```json
{
  "items": [
    {
      "approvedAt": "2026-11-17T08:05:00Z",
      "approvedBy": "martin.brandl@muster-it.example",
      "billableMinutes": 15,
      "billing": "quota",
      "contract": {
        "id": "7a9c1e3a-5c7e-4a9c-8e3a-5c7e9a1c3e52",
        "number": "WV-2026-0007",
        "quota": true,
        "title": "Wartungsvertrag Netzwerk und WLAN"
      },
      "createdAt": "2026-11-16T09:30:00Z",
      "createdBy": "sophie.huber@muster-it.example",
      "customer": {
        "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
        "name": "Alpenhotel Seeblick GmbH"
      },
      "description": "Access Point im Restaurant neu gestartet, Kanal gewechselt, Rückruf bei Frau Stadler.",
      "durationSeconds": 900,
      "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "endedAt": "2026-11-16T09:27:00Z",
      "id": "5e7a9c1e-3a5c-4e7a-9c1e-3a5c7e9a1c51",
      "kind": "remote",
      "minutes": 15,
      "origin": "comms:interaction:4f6a8c0e-2b4d-4f6a-8c0e-2b4d6f8a0c2e",
      "running": false,
      "source": "interaction",
      "startedAt": "2026-11-16T09:12:00Z",
      "state": "approved",
      "subject": "desk:item:6a8c0e2a-4b6d-4f8a-9c1e-3b5d7f9a1c3e",
      "subjectLabel": "#214 WLAN im Restaurant fällt aus",
      "updatedAt": "2026-11-17T08:05:00Z",
      "version": 2,
      "workDate": "2026-11-16"
    },
    {
      "billableMinutes": 0,
      "billing": "none",
      "createdAt": "2026-11-16T15:10:00Z",
      "createdBy": "sophie.huber@muster-it.example",
      "description": "Teambesprechung Service Desk",
      "durationSeconds": 2700,
      "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "endedAt": null,
      "id": "7a9c1e3a-5c7e-4a9c-9e3a-5c7e9a1c3e53",
      "kind": "internal",
      "minutes": 45,
      "running": false,
      "source": "manual",
      "startedAt": null,
      "state": "confirmed",
      "subject": "",
      "updatedAt": "2026-11-16T15:10:00Z",
      "version": 1,
      "workDate": "2026-11-16"
    }
  ],
  "total": 2
}
```

### Example request

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

## Book own work (tenant:access and an active employee record)

`POST /api/hr/v1/work-entries`

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

Always for the caller. A `subject` is checked with its module (`400` unknown or of another customer than the
`customer` sent, `422 subject_not_bookable`,
`503 subject_access_unavailable` when the module cannot answer – nothing is booked); customer and project
follow from it when the request names none. An `origin` (the call or appointment the time comes from,
`comms:interaction:<id>` or `comms:calendar:<id>`) must be the caller's own (`400` field `origin`); its entry
has source `interaction` or `calendar`; the `subject` is then the target (a ticket, item, CRM record or project)
or empty for internal work, a comms reference as `subject` is `400` (use `origin`); with an origin and no
subject the customer sent wins over comms' suggestion. A call or appointment is booked once (`409 already_booked`); an
overlap of two spans (start and end) is `409 overlap`; entries without a span never overlap. An entry is a work
day and a length: send `minutes` (1–1440) with an optional `workDate` (default today in the tenant's time
zone, never in the future: `400 workDate`), or a span `startedAt` + `endedAt` (`minutes` follow from it and a
sent value is ignored; a `workDate` must be the start's day), or a `startedAt` with `minutes` and no end. An
`endedAt` without `startedAt` is `400 startedAt`; a start alone without `minutes` is `400 minutes`. When the customer is not sent, it follows from the subject (a
forge project's `workCustomer`, a desk item's customer). There is no break: it is not deducted any more.
A flat-rate billing type needs an article (`422 article_required`).
On a quota contract the consumed hours are posted to trade with the entry.

### Request body

`application/json` (required)

- `article` (WorkArticleRef): The masterdata article a flat-rate entry is billed as (requests send only `id`).
  - `articleNumber` (string): Article number
  - `id` (string): Id of the masterdata article
  - `name` (string): Name of the article
  - `unit` (string): Unit of the article
- `billableMinutes` (integer, nullable): Default the net time (0 for flat-rate and non-billable work)
- `billing` (string): Default: non-billable for internal kinds, quota on a quota contract, else the default
- `contract` (WorkContractRef): A trade contract; quota contracts consume their contingent.
  - `id` (string): Id of the trade contract
  - `number` (string): Number of the contract
  - `quota` (boolean): A quota contract (work on it consumes its contingent)
  - `title` (string): Title of the contract
- `customer` (WorkCustomerRef): The customer (masterdata address) the work is for.
  - `id` (string): Id of the customer (masterdata address)
  - `name` (string): Name of the customer
- `description` (string): What was done
- `endedAt` (string (date-time), nullable): Needs `startedAt`; after it, at most 24 hours later
- `kind` (string): Default the tenant's default kind
- `km` (number): Kilometres travelled (kinds that allow travel)
- `minutes` (integer): The length; required without an end. With start and end it follows from them and a sent value is ignored (max 1440)
- `origin` (string): See `WorkEntry.origin`; the caller's own call or appointment, checked with comms (`400` field `origin`). Set on create, kept on update: an update may omit it or repeat it, a different one is `400` field `origin`
- `project` (WorkProjectRef)
  - `number` (string): Number of the project at booking time
  - `ref` (string): Reference of the project in its module (desk:project:<id>, forge:project:<id>)
  - `title` (string): Title of the project at booking time
- `startedAt` (string (date-time), nullable): Optional; at most 5 minutes in the future
- `state` (string): suggested (draft) or confirmed (default) (one of `suggested`, `confirmed`; default `"confirmed"`)
- `subject` (string): See `WorkEntry.subject`; checked with its module
- `travelMinutes` (integer): Travel time in minutes (kinds that allow travel)
- `version` (integer): Required on change
- `workDate` (string (date)): The day the work counts for (default today in the tenant's time zone); with a start it must be the start's day (or, across midnight, the end's); never in the future (`400 workDate`)

Example:

```json
{
  "billing": "quota",
  "contract": {
    "id": "7a9c1e3a-5c7e-4a9c-8e3a-5c7e9a1c3e52"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e"
  },
  "description": "Access Point im Restaurant neu gestartet, Kanal gewechselt, Rückruf bei Frau Stadler.",
  "endedAt": "2026-11-16T09:27:00Z",
  "kind": "remote",
  "origin": "comms:interaction:4f6a8c0e-2b4d-4f6a-8c0e-2b4d6f8a0c2e",
  "startedAt": "2026-11-16T09:12:00Z",
  "state": "confirmed",
  "subject": "desk:item:6a8c0e2a-4b6d-4f8a-9c1e-3b5d7f9a1c3e",
  "workDate": "2026-11-16"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 201 answer:

- `approvedAt` (string (date-time), nullable): When the entry was approved
- `approvedBy` (string): Who approved the entry (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `article` (WorkArticleRef | null): Masterdata article a flat-rate entry is billed as
- `batchId` (string (uuid), nullable): Billing batch the entry is billed in
- `billableMinutes` (integer): Minutes billed
- `billedRate` (number, nullable): Hourly rate (or article price) the entry was billed at
- `billing` (string): Key of a billing type
- `contract` (WorkContractRef | null): Trade contract that decides billing
- `correctionOf` (string (uuid), nullable): The approved or billed entry this one corrects; its minutes are the difference (may be negative)
- `createdAt` (string (date-time)): When the work entry was created
- `createdBy` (string): Who booked the entry (e-mail)
- `customer` (WorkCustomerRef | null): Customer the work is billed to
- `description` (string): What was done
- `durationSeconds` (integer): The exact length in seconds (the stopwatch's seconds, else `minutes` × 60)
- `employeeId` (string (uuid)): Id of the employee
- `employeeName` (string): Display name of the employee – only in `listApprovableWorkEntries`
- `endedAt` (string (date-time), nullable): `null` for the running stopwatch and for an entry without a span
- `id` (string (uuid)): Id of the work entry
- `kind` (string): Key of a work kind (`getWorkEntrySettings`)
- `km` (number): Kilometres travelled (kinds that allow travel)
- `minutes` (integer): The length in minutes that sums and billing use (a correction's difference, may be negative; 0 for a stopwatch run that rounded to nothing)
- `origin` (string): The call or appointment the time comes from: `comms:interaction:<id>` or `comms:calendar:<id>`; omitted for other work. Booked at most once per tenant (`409 already_booked`)
- `project` (WorkProjectRef | null): Project the work counts for
- `running` (boolean): The running stopwatch entry (start, no end)
- `source` (string): How the entry was booked (one of `manual`, `stopwatch`, `interaction`, `calendar`, `correction`)
- `startedAt` (string (date-time), nullable): `null` for an entry booked as a length only
- `state` (string): suggested → confirmed → approved → billed (one of `suggested`, `confirmed`, `approved`, `billed`)
- `subject` (string): What was worked on: `desk:item:<id>`, `forge:item:<id>`, `crm:activity:<id>`, a project `desk:project:<id>` / `forge:project:<id>`; empty for work on the customer only or internal work
- `subjectLabel` (string): The subject's name at booking time (the origin's without a subject)
- `travelMinutes` (integer): Travel time in minutes (kinds that allow travel)
- `updatedAt` (string (date-time)): When the work entry was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `workDate` (string (date)): The day the work counts for (the person's choice; with a start its day in the tenant's time zone)

Example 201 answer:

```json
{
  "approvedAt": "2026-11-17T08:05:00Z",
  "approvedBy": "martin.brandl@muster-it.example",
  "batchId": null,
  "billableMinutes": 15,
  "billedRate": null,
  "billing": "quota",
  "contract": {
    "id": "7a9c1e3a-5c7e-4a9c-8e3a-5c7e9a1c3e52",
    "number": "WV-2026-0007",
    "quota": true,
    "title": "Wartungsvertrag Netzwerk und WLAN"
  },
  "correctionOf": null,
  "createdAt": "2026-11-16T09:30:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
    "name": "Alpenhotel Seeblick GmbH"
  },
  "description": "Access Point im Restaurant neu gestartet, Kanal gewechselt, Rückruf bei Frau Stadler.",
  "durationSeconds": 900,
  "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "endedAt": "2026-11-16T09:27:00Z",
  "id": "5e7a9c1e-3a5c-4e7a-9c1e-3a5c7e9a1c51",
  "kind": "remote",
  "km": 0,
  "minutes": 15,
  "origin": "comms:interaction:4f6a8c0e-2b4d-4f6a-8c0e-2b4d6f8a0c2e",
  "running": false,
  "source": "interaction",
  "startedAt": "2026-11-16T09:12:00Z",
  "state": "approved",
  "subject": "desk:item:6a8c0e2a-4b6d-4f8a-9c1e-3b5d7f9a1c3e",
  "subjectLabel": "#214 WLAN im Restaurant fällt aus",
  "travelMinutes": 0,
  "updatedAt": "2026-11-17T08:05:00Z",
  "version": 2,
  "workDate": "2026-11-16"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/work-entries' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"billing":"quota","contract":{"id":"7a9c1e3a-5c7e-4a9c-8e3a-5c7e9a1c3e52"},"customer":{"id":"3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e"},"description":"Access Point im Restaurant neu gestartet, Kanal gewechselt, Rückruf bei Frau Stadler.","endedAt":"2026-11-16T09:27:00Z","kind":"remote","origin":"comms:interaction:4f6a8c0e-2b4d-4f6a-8c0e-2b4d6f8a0c2e","startedAt":"2026-11-16T09:12:00Z","state":"confirmed","subject":"desk:item:6a8c0e2a-4b6d-4f8a-9c1e-3b5d7f9a1c3e","workDate":"2026-11-16"}'
```

## One work entry (tenant:access – own; a team member's as line manager or deputy; anyone's with hr:work:manage)

`GET /api/hr/v1/work-entries/{id}`

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

The owner reads their entry; a line manager or deputy reads the entries of the people they decide for, and
`hr:work:manage` everyone's – the rule of `listWorkEntries` and `listApprovableWorkEntries`. Anyone else, an
unknown id and another tenant's entry answer `404` alike.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

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

Fields of the 200 answer:

- `approvedAt` (string (date-time), nullable): When the entry was approved
- `approvedBy` (string): Who approved the entry (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `article` (WorkArticleRef | null): Masterdata article a flat-rate entry is billed as
- `batchId` (string (uuid), nullable): Billing batch the entry is billed in
- `billableMinutes` (integer): Minutes billed
- `billedRate` (number, nullable): Hourly rate (or article price) the entry was billed at
- `billing` (string): Key of a billing type
- `contract` (WorkContractRef | null): Trade contract that decides billing
- `correctionOf` (string (uuid), nullable): The approved or billed entry this one corrects; its minutes are the difference (may be negative)
- `createdAt` (string (date-time)): When the work entry was created
- `createdBy` (string): Who booked the entry (e-mail)
- `customer` (WorkCustomerRef | null): Customer the work is billed to
- `description` (string): What was done
- `durationSeconds` (integer): The exact length in seconds (the stopwatch's seconds, else `minutes` × 60)
- `employeeId` (string (uuid)): Id of the employee
- `employeeName` (string): Display name of the employee – only in `listApprovableWorkEntries`
- `endedAt` (string (date-time), nullable): `null` for the running stopwatch and for an entry without a span
- `id` (string (uuid)): Id of the work entry
- `kind` (string): Key of a work kind (`getWorkEntrySettings`)
- `km` (number): Kilometres travelled (kinds that allow travel)
- `minutes` (integer): The length in minutes that sums and billing use (a correction's difference, may be negative; 0 for a stopwatch run that rounded to nothing)
- `origin` (string): The call or appointment the time comes from: `comms:interaction:<id>` or `comms:calendar:<id>`; omitted for other work. Booked at most once per tenant (`409 already_booked`)
- `project` (WorkProjectRef | null): Project the work counts for
- `running` (boolean): The running stopwatch entry (start, no end)
- `source` (string): How the entry was booked (one of `manual`, `stopwatch`, `interaction`, `calendar`, `correction`)
- `startedAt` (string (date-time), nullable): `null` for an entry booked as a length only
- `state` (string): suggested → confirmed → approved → billed (one of `suggested`, `confirmed`, `approved`, `billed`)
- `subject` (string): What was worked on: `desk:item:<id>`, `forge:item:<id>`, `crm:activity:<id>`, a project `desk:project:<id>` / `forge:project:<id>`; empty for work on the customer only or internal work
- `subjectLabel` (string): The subject's name at booking time (the origin's without a subject)
- `travelMinutes` (integer): Travel time in minutes (kinds that allow travel)
- `updatedAt` (string (date-time)): When the work entry was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `workDate` (string (date)): The day the work counts for (the person's choice; with a start its day in the tenant's time zone)

Example 200 answer:

```json
{
  "approvedAt": "2026-11-17T08:05:00Z",
  "approvedBy": "martin.brandl@muster-it.example",
  "batchId": null,
  "billableMinutes": 15,
  "billedRate": null,
  "billing": "quota",
  "contract": {
    "id": "7a9c1e3a-5c7e-4a9c-8e3a-5c7e9a1c3e52",
    "number": "WV-2026-0007",
    "quota": true,
    "title": "Wartungsvertrag Netzwerk und WLAN"
  },
  "correctionOf": null,
  "createdAt": "2026-11-16T09:30:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
    "name": "Alpenhotel Seeblick GmbH"
  },
  "description": "Access Point im Restaurant neu gestartet, Kanal gewechselt, Rückruf bei Frau Stadler.",
  "durationSeconds": 900,
  "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "endedAt": "2026-11-16T09:27:00Z",
  "id": "5e7a9c1e-3a5c-4e7a-9c1e-3a5c7e9a1c51",
  "kind": "remote",
  "km": 0,
  "minutes": 15,
  "origin": "comms:interaction:4f6a8c0e-2b4d-4f6a-8c0e-2b4d6f8a0c2e",
  "running": false,
  "source": "interaction",
  "startedAt": "2026-11-16T09:12:00Z",
  "state": "approved",
  "subject": "desk:item:6a8c0e2a-4b6d-4f8a-9c1e-3b5d7f9a1c3e",
  "subjectLabel": "#214 WLAN im Restaurant fällt aus",
  "travelMinutes": 0,
  "updatedAt": "2026-11-17T08:05:00Z",
  "version": 2,
  "workDate": "2026-11-16"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/work-entries/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change an own entry (tenant:access)

`PUT /api/hr/v1/work-entries/{id}`

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

Only the owner changes an entry (others: `403 not_own_entry` or `404`), with its `version` (missing: `400`).
Approved and billed entries are `409 locked` – they are corrected instead; the running stopwatch entry is
`409 stopwatch_running` (stop it first). The same rules as booking apply; manual changes are never rounded.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `article` (WorkArticleRef): The masterdata article a flat-rate entry is billed as (requests send only `id`).
  - `articleNumber` (string): Article number
  - `id` (string): Id of the masterdata article
  - `name` (string): Name of the article
  - `unit` (string): Unit of the article
- `billableMinutes` (integer, nullable): Default the net time (0 for flat-rate and non-billable work)
- `billing` (string): Default: non-billable for internal kinds, quota on a quota contract, else the default
- `contract` (WorkContractRef): A trade contract; quota contracts consume their contingent.
  - `id` (string): Id of the trade contract
  - `number` (string): Number of the contract
  - `quota` (boolean): A quota contract (work on it consumes its contingent)
  - `title` (string): Title of the contract
- `customer` (WorkCustomerRef): The customer (masterdata address) the work is for.
  - `id` (string): Id of the customer (masterdata address)
  - `name` (string): Name of the customer
- `description` (string): What was done
- `endedAt` (string (date-time), nullable): Needs `startedAt`; after it, at most 24 hours later
- `kind` (string): Default the tenant's default kind
- `km` (number): Kilometres travelled (kinds that allow travel)
- `minutes` (integer): The length; required without an end. With start and end it follows from them and a sent value is ignored (max 1440)
- `origin` (string): See `WorkEntry.origin`; the caller's own call or appointment, checked with comms (`400` field `origin`). Set on create, kept on update: an update may omit it or repeat it, a different one is `400` field `origin`
- `project` (WorkProjectRef)
  - `number` (string): Number of the project at booking time
  - `ref` (string): Reference of the project in its module (desk:project:<id>, forge:project:<id>)
  - `title` (string): Title of the project at booking time
- `startedAt` (string (date-time), nullable): Optional; at most 5 minutes in the future
- `state` (string): suggested (draft) or confirmed (default) (one of `suggested`, `confirmed`; default `"confirmed"`)
- `subject` (string): See `WorkEntry.subject`; checked with its module
- `travelMinutes` (integer): Travel time in minutes (kinds that allow travel)
- `version` (integer): Required on change
- `workDate` (string (date)): The day the work counts for (default today in the tenant's time zone); with a start it must be the start's day (or, across midnight, the end's); never in the future (`400 workDate`)

Example:

```json
{
  "billing": "quota",
  "contract": {
    "id": "7a9c1e3a-5c7e-4a9c-8e3a-5c7e9a1c3e52"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e"
  },
  "description": "Access Point im Restaurant neu gestartet, Kanal gewechselt, Rückruf und Test mit Frau Stadler.",
  "endedAt": "2026-11-16T09:32:00Z",
  "kind": "remote",
  "startedAt": "2026-11-16T09:12:00Z",
  "subject": "desk:item:6a8c0e2a-4b6d-4f8a-9c1e-3b5d7f9a1c3e",
  "version": 1,
  "workDate": "2026-11-16"
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 200 answer:

- `approvedAt` (string (date-time), nullable): When the entry was approved
- `approvedBy` (string): Who approved the entry (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `article` (WorkArticleRef | null): Masterdata article a flat-rate entry is billed as
- `batchId` (string (uuid), nullable): Billing batch the entry is billed in
- `billableMinutes` (integer): Minutes billed
- `billedRate` (number, nullable): Hourly rate (or article price) the entry was billed at
- `billing` (string): Key of a billing type
- `contract` (WorkContractRef | null): Trade contract that decides billing
- `correctionOf` (string (uuid), nullable): The approved or billed entry this one corrects; its minutes are the difference (may be negative)
- `createdAt` (string (date-time)): When the work entry was created
- `createdBy` (string): Who booked the entry (e-mail)
- `customer` (WorkCustomerRef | null): Customer the work is billed to
- `description` (string): What was done
- `durationSeconds` (integer): The exact length in seconds (the stopwatch's seconds, else `minutes` × 60)
- `employeeId` (string (uuid)): Id of the employee
- `employeeName` (string): Display name of the employee – only in `listApprovableWorkEntries`
- `endedAt` (string (date-time), nullable): `null` for the running stopwatch and for an entry without a span
- `id` (string (uuid)): Id of the work entry
- `kind` (string): Key of a work kind (`getWorkEntrySettings`)
- `km` (number): Kilometres travelled (kinds that allow travel)
- `minutes` (integer): The length in minutes that sums and billing use (a correction's difference, may be negative; 0 for a stopwatch run that rounded to nothing)
- `origin` (string): The call or appointment the time comes from: `comms:interaction:<id>` or `comms:calendar:<id>`; omitted for other work. Booked at most once per tenant (`409 already_booked`)
- `project` (WorkProjectRef | null): Project the work counts for
- `running` (boolean): The running stopwatch entry (start, no end)
- `source` (string): How the entry was booked (one of `manual`, `stopwatch`, `interaction`, `calendar`, `correction`)
- `startedAt` (string (date-time), nullable): `null` for an entry booked as a length only
- `state` (string): suggested → confirmed → approved → billed (one of `suggested`, `confirmed`, `approved`, `billed`)
- `subject` (string): What was worked on: `desk:item:<id>`, `forge:item:<id>`, `crm:activity:<id>`, a project `desk:project:<id>` / `forge:project:<id>`; empty for work on the customer only or internal work
- `subjectLabel` (string): The subject's name at booking time (the origin's without a subject)
- `travelMinutes` (integer): Travel time in minutes (kinds that allow travel)
- `updatedAt` (string (date-time)): When the work entry was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `workDate` (string (date)): The day the work counts for (the person's choice; with a start its day in the tenant's time zone)

Example 200 answer:

```json
{
  "approvedAt": "2026-11-17T08:05:00Z",
  "approvedBy": "martin.brandl@muster-it.example",
  "batchId": null,
  "billableMinutes": 15,
  "billedRate": null,
  "billing": "quota",
  "contract": {
    "id": "7a9c1e3a-5c7e-4a9c-8e3a-5c7e9a1c3e52",
    "number": "WV-2026-0007",
    "quota": true,
    "title": "Wartungsvertrag Netzwerk und WLAN"
  },
  "correctionOf": null,
  "createdAt": "2026-11-16T09:30:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
    "name": "Alpenhotel Seeblick GmbH"
  },
  "description": "Access Point im Restaurant neu gestartet, Kanal gewechselt, Rückruf bei Frau Stadler.",
  "durationSeconds": 900,
  "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "endedAt": "2026-11-16T09:27:00Z",
  "id": "5e7a9c1e-3a5c-4e7a-9c1e-3a5c7e9a1c51",
  "kind": "remote",
  "km": 0,
  "minutes": 15,
  "origin": "comms:interaction:4f6a8c0e-2b4d-4f6a-8c0e-2b4d6f8a0c2e",
  "running": false,
  "source": "interaction",
  "startedAt": "2026-11-16T09:12:00Z",
  "state": "approved",
  "subject": "desk:item:6a8c0e2a-4b6d-4f8a-9c1e-3b5d7f9a1c3e",
  "subjectLabel": "#214 WLAN im Restaurant fällt aus",
  "travelMinutes": 0,
  "updatedAt": "2026-11-17T08:05:00Z",
  "version": 2,
  "workDate": "2026-11-16"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/work-entries/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"billing":"quota","contract":{"id":"7a9c1e3a-5c7e-4a9c-8e3a-5c7e9a1c3e52"},"customer":{"id":"3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e"},"description":"Access Point im Restaurant neu gestartet, Kanal gewechselt, Rückruf und Test mit Frau Stadler.","endedAt":"2026-11-16T09:32:00Z","kind":"remote","startedAt":"2026-11-16T09:12:00Z","subject":"desk:item:6a8c0e2a-4b6d-4f8a-9c1e-3b5d7f9a1c3e","version":1,"workDate":"2026-11-16"}'
```

## Delete an own entry (tenant:access)

`DELETE /api/hr/v1/work-entries/{id}`

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

Approved and billed entries are `409 locked`. A correction that is not approved yet is deleted by the person who
booked it or an approver of the employee (`403 not_correction_creator` for anyone else).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `version` | query | integer | yes | The entry's version |
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/hr/v1/work-entries/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12?version=1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## The caller's booked, billable and internal minutes of a day (tenant:access)

`GET /api/hr/v1/work-entries/summary`

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

Confirmed, approved and billed entries of the work day and their corrections (with their sign) – the same sums
as `getMyDay`; suggestions and the running stopwatch do not count.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `date` | query | string (date) |  | Work day (default today in the tenant's time zone) |

### Responses

- **200** Sums (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `billableMinutes` (integer): Billable minutes
- `bookedMinutes` (integer): Booked minutes (corrections with their sign; no suggestions, no running stopwatch)
- `date` (string (date)): The work day (YYYY-MM-DD)
- `internalMinutes` (integer): Booked on non-billable billing types

Example 200 answer:

```json
{
  "billableMinutes": 330,
  "bookedMinutes": 420,
  "date": "2026-11-18",
  "internalMinutes": 90
}
```

### Example request

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

## Entries the caller may approve (line managers and deputies for their team, hr:work:manage for everyone)

`GET /api/hr/v1/work-entries/approvals`

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

Finished entries of every employee the caller decides for: with `hr:work:manage` everyone's, otherwise the
team's of a line manager or deputy (nobody else: an empty page). The caller's own entries only with
`hr:work:manage` and the tenant's `selfApproval`. `state=approved` lists approvals to take back. The period
defaults to the 31 days before `to` (default today), at most a year. Each entry carries the person's
`employeeName`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `state` | query | string |  | (one of `confirmed`, `approved`; default `"confirmed"`) |
| `from` | query | string (date) |  |  |
| `to` | query | string (date) |  |  |
| `limit` | query | integer |  | 1–200; another value is a 400 invalid. (default `50`; max 200) |
| `offset` | query | integer |  | (default `0`) |

### Responses

- **200** Entries by work day (`application/json`)
- **400** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of WorkEntry, required): Entries of this page
  - `approvedAt` (string (date-time), nullable): When the entry was approved
  - `approvedBy` (string): Who approved the entry (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
  - `article` (WorkArticleRef | null): Masterdata article a flat-rate entry is billed as
  - `batchId` (string (uuid), nullable): Billing batch the entry is billed in
  - `billableMinutes` (integer): Minutes billed
  - `billedRate` (number, nullable): Hourly rate (or article price) the entry was billed at
  - `billing` (string): Key of a billing type
  - `contract` (WorkContractRef | null): Trade contract that decides billing
  - `correctionOf` (string (uuid), nullable): The approved or billed entry this one corrects; its minutes are the difference (may be negative)
  - `createdAt` (string (date-time)): When the work entry was created
  - `createdBy` (string): Who booked the entry (e-mail)
  - `customer` (WorkCustomerRef | null): Customer the work is billed to
  - `description` (string): What was done
  - `durationSeconds` (integer): The exact length in seconds (the stopwatch's seconds, else `minutes` × 60)
  - `employeeId` (string (uuid)): Id of the employee
  - `employeeName` (string): Display name of the employee – only in `listApprovableWorkEntries`
  - `endedAt` (string (date-time), nullable): `null` for the running stopwatch and for an entry without a span
  - `id` (string (uuid)): Id of the work entry
  - `kind` (string): Key of a work kind (`getWorkEntrySettings`)
  - `km` (number): Kilometres travelled (kinds that allow travel)
  - `minutes` (integer): The length in minutes that sums and billing use (a correction's difference, may be negative; 0 for a stopwatch run that rounded to nothing)
  - `origin` (string): The call or appointment the time comes from: `comms:interaction:<id>` or `comms:calendar:<id>`; omitted for other work. Booked at most once per tenant (`409 already_booked`)
  - `project` (WorkProjectRef | null): Project the work counts for
  - `running` (boolean): The running stopwatch entry (start, no end)
  - `source` (string): How the entry was booked (one of `manual`, `stopwatch`, `interaction`, `calendar`, `correction`)
  - `startedAt` (string (date-time), nullable): `null` for an entry booked as a length only
  - `state` (string): suggested → confirmed → approved → billed (one of `suggested`, `confirmed`, `approved`, `billed`)
  - `subject` (string): What was worked on: `desk:item:<id>`, `forge:item:<id>`, `crm:activity:<id>`, a project `desk:project:<id>` / `forge:project:<id>`; empty for work on the customer only or internal work
  - `subjectLabel` (string): The subject's name at booking time (the origin's without a subject)
  - `travelMinutes` (integer): Travel time in minutes (kinds that allow travel)
  - `updatedAt` (string (date-time)): When the work entry was last changed
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
  - `workDate` (string (date)): The day the work counts for (the person's choice; with a start its day in the tenant's time zone)
- `total` (integer): Number of all matching entries

Example 200 answer:

```json
{
  "items": [
    {
      "approvedAt": "2026-11-17T08:05:00Z",
      "approvedBy": "martin.brandl@muster-it.example",
      "billableMinutes": 15,
      "billing": "quota",
      "contract": {
        "id": "7a9c1e3a-5c7e-4a9c-8e3a-5c7e9a1c3e52",
        "number": "WV-2026-0007",
        "quota": true,
        "title": "Wartungsvertrag Netzwerk und WLAN"
      },
      "createdAt": "2026-11-16T09:30:00Z",
      "createdBy": "sophie.huber@muster-it.example",
      "customer": {
        "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
        "name": "Alpenhotel Seeblick GmbH"
      },
      "description": "Access Point im Restaurant neu gestartet, Kanal gewechselt, Rückruf bei Frau Stadler.",
      "durationSeconds": 900,
      "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "endedAt": "2026-11-16T09:27:00Z",
      "id": "5e7a9c1e-3a5c-4e7a-9c1e-3a5c7e9a1c51",
      "kind": "remote",
      "minutes": 15,
      "origin": "comms:interaction:4f6a8c0e-2b4d-4f6a-8c0e-2b4d6f8a0c2e",
      "running": false,
      "source": "interaction",
      "startedAt": "2026-11-16T09:12:00Z",
      "state": "approved",
      "subject": "desk:item:6a8c0e2a-4b6d-4f8a-9c1e-3b5d7f9a1c3e",
      "subjectLabel": "#214 WLAN im Restaurant fällt aus",
      "updatedAt": "2026-11-17T08:05:00Z",
      "version": 2,
      "workDate": "2026-11-16"
    },
    {
      "billableMinutes": 0,
      "billing": "none",
      "createdAt": "2026-11-16T15:10:00Z",
      "createdBy": "sophie.huber@muster-it.example",
      "description": "Teambesprechung Service Desk",
      "durationSeconds": 2700,
      "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "endedAt": null,
      "id": "7a9c1e3a-5c7e-4a9c-9e3a-5c7e9a1c3e53",
      "kind": "internal",
      "minutes": 45,
      "running": false,
      "source": "manual",
      "startedAt": null,
      "state": "confirmed",
      "subject": "",
      "updatedAt": "2026-11-16T15:10:00Z",
      "version": 1,
      "workDate": "2026-11-16"
    }
  ],
  "total": 2
}
```

### Example request

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

## The caller's running stopwatch (tenant:access)

`GET /api/hr/v1/work-entries/stopwatch`

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

### Responses

- **200** The running entry, `null` when none runs (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `running` (WorkEntry | null, required): The caller's running stopwatch entry, null when none runs

Example 200 answer:

```json
{
  "running": {
    "billableMinutes": 0,
    "billing": "hourly",
    "createdAt": "2026-11-19T08:40:00Z",
    "createdBy": "sophie.huber@muster-it.example",
    "customer": {
      "id": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
      "name": "Kanzlei Hofmann \u0026 Partner"
    },
    "description": "Drucker im Empfang einrichten",
    "durationSeconds": 0,
    "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
    "endedAt": null,
    "id": "9c1e3a5c-7e9a-4c1e-8a5c-7e9a1c3e5a54",
    "kind": "remote",
    "minutes": 0,
    "running": true,
    "source": "stopwatch",
    "startedAt": "2026-11-19T08:40:00Z",
    "state": "confirmed",
    "subject": "desk:item:8c0e2a4c-6e8a-4c0e-9a2c-4e6a8c0e2a55",
    "subjectLabel": "#231 Neuer Drucker am Empfang",
    "updatedAt": "2026-11-19T08:40:00Z",
    "version": 1,
    "workDate": "2026-11-19"
  }
}
```

### Example request

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

## Start the caller's stopwatch (tenant:access)

`POST /api/hr/v1/work-entries/stopwatch`

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

A stopwatch already running is stopped at the same instant and kept as an entry (also a run under a minute: it
becomes a 0-minute entry with its exact seconds); one longer than 24 hours is `422 stopwatch_too_long` – stop
it with an explicit end first; a `startedAt` not after its start is `409 overlap`. The body is optional.

### Request body

`application/json`

- `article` (WorkArticleRef): The masterdata article a flat-rate entry is billed as (requests send only `id`).
  - `articleNumber` (string): Article number
  - `id` (string): Id of the masterdata article
  - `name` (string): Name of the article
  - `unit` (string): Unit of the article
- `billing` (string): Key of the billing type (empty: the default)
- `contract` (WorkContractRef): A trade contract; quota contracts consume their contingent.
  - `id` (string): Id of the trade contract
  - `number` (string): Number of the contract
  - `quota` (boolean): A quota contract (work on it consumes its contingent)
  - `title` (string): Title of the contract
- `customer` (WorkCustomerRef): The customer (masterdata address) the work is for.
  - `id` (string): Id of the customer (masterdata address)
  - `name` (string): Name of the customer
- `description` (string): What is worked on
- `kind` (string): Key of the work kind (empty: the default)
- `project` (WorkProjectRef)
  - `number` (string): Number of the project at booking time
  - `ref` (string): Reference of the project in its module (desk:project:<id>, forge:project:<id>)
  - `title` (string): Title of the project at booking time
- `startedAt` (string (date-time)): Default now
- `subject` (string): Reference of the thing worked on (desk:item:<id>, forge:item:<id>, crm:activity:<id>, projects)

Example:

```json
{
  "billing": "hourly",
  "customer": {
    "id": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50"
  },
  "description": "Drucker im Empfang einrichten",
  "kind": "remote",
  "subject": "desk:item:8c0e2a4c-6e8a-4c0e-9a2c-4e6a8c0e2a55"
}
```

### Responses

- **201** Started (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 201 answer:

- `approvedAt` (string (date-time), nullable): When the entry was approved
- `approvedBy` (string): Who approved the entry (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `article` (WorkArticleRef | null): Masterdata article a flat-rate entry is billed as
- `batchId` (string (uuid), nullable): Billing batch the entry is billed in
- `billableMinutes` (integer): Minutes billed
- `billedRate` (number, nullable): Hourly rate (or article price) the entry was billed at
- `billing` (string): Key of a billing type
- `contract` (WorkContractRef | null): Trade contract that decides billing
- `correctionOf` (string (uuid), nullable): The approved or billed entry this one corrects; its minutes are the difference (may be negative)
- `createdAt` (string (date-time)): When the work entry was created
- `createdBy` (string): Who booked the entry (e-mail)
- `customer` (WorkCustomerRef | null): Customer the work is billed to
- `description` (string): What was done
- `durationSeconds` (integer): The exact length in seconds (the stopwatch's seconds, else `minutes` × 60)
- `employeeId` (string (uuid)): Id of the employee
- `employeeName` (string): Display name of the employee – only in `listApprovableWorkEntries`
- `endedAt` (string (date-time), nullable): `null` for the running stopwatch and for an entry without a span
- `id` (string (uuid)): Id of the work entry
- `kind` (string): Key of a work kind (`getWorkEntrySettings`)
- `km` (number): Kilometres travelled (kinds that allow travel)
- `minutes` (integer): The length in minutes that sums and billing use (a correction's difference, may be negative; 0 for a stopwatch run that rounded to nothing)
- `origin` (string): The call or appointment the time comes from: `comms:interaction:<id>` or `comms:calendar:<id>`; omitted for other work. Booked at most once per tenant (`409 already_booked`)
- `project` (WorkProjectRef | null): Project the work counts for
- `running` (boolean): The running stopwatch entry (start, no end)
- `source` (string): How the entry was booked (one of `manual`, `stopwatch`, `interaction`, `calendar`, `correction`)
- `startedAt` (string (date-time), nullable): `null` for an entry booked as a length only
- `state` (string): suggested → confirmed → approved → billed (one of `suggested`, `confirmed`, `approved`, `billed`)
- `subject` (string): What was worked on: `desk:item:<id>`, `forge:item:<id>`, `crm:activity:<id>`, a project `desk:project:<id>` / `forge:project:<id>`; empty for work on the customer only or internal work
- `subjectLabel` (string): The subject's name at booking time (the origin's without a subject)
- `travelMinutes` (integer): Travel time in minutes (kinds that allow travel)
- `updatedAt` (string (date-time)): When the work entry was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `workDate` (string (date)): The day the work counts for (the person's choice; with a start its day in the tenant's time zone)

Example 201 answer:

```json
{
  "approvedAt": "2026-11-17T08:05:00Z",
  "approvedBy": "martin.brandl@muster-it.example",
  "batchId": null,
  "billableMinutes": 15,
  "billedRate": null,
  "billing": "quota",
  "contract": {
    "id": "7a9c1e3a-5c7e-4a9c-8e3a-5c7e9a1c3e52",
    "number": "WV-2026-0007",
    "quota": true,
    "title": "Wartungsvertrag Netzwerk und WLAN"
  },
  "correctionOf": null,
  "createdAt": "2026-11-16T09:30:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
    "name": "Alpenhotel Seeblick GmbH"
  },
  "description": "Access Point im Restaurant neu gestartet, Kanal gewechselt, Rückruf bei Frau Stadler.",
  "durationSeconds": 900,
  "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "endedAt": "2026-11-16T09:27:00Z",
  "id": "5e7a9c1e-3a5c-4e7a-9c1e-3a5c7e9a1c51",
  "kind": "remote",
  "km": 0,
  "minutes": 15,
  "origin": "comms:interaction:4f6a8c0e-2b4d-4f6a-8c0e-2b4d6f8a0c2e",
  "running": false,
  "source": "interaction",
  "startedAt": "2026-11-16T09:12:00Z",
  "state": "approved",
  "subject": "desk:item:6a8c0e2a-4b6d-4f8a-9c1e-3b5d7f9a1c3e",
  "subjectLabel": "#214 WLAN im Restaurant fällt aus",
  "travelMinutes": 0,
  "updatedAt": "2026-11-17T08:05:00Z",
  "version": 2,
  "workDate": "2026-11-16"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/work-entries/stopwatch' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"billing":"hourly","customer":{"id":"1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50"},"description":"Drucker im Empfang einrichten","kind":"remote","subject":"desk:item:8c0e2a4c-6e8a-4c0e-9a2c-4e6a8c0e2a55"}'
```

## Stop or discard the caller's stopwatch (tenant:access)

`DELETE /api/hr/v1/work-entries/stopwatch`

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

Ends the running entry at `endedAt` (default now). The exact seconds are kept in `durationSeconds`; `minutes`
are the length rounded once, now, by the tenant's stopwatch `rounding` (`getWorkEntrySettings`; an explicit
`endedAt` is not rounded). A run that rounds to 0 stays as a 0-minute entry. The 24-hour limit is checked on
the raw seconds: a stopwatch left running longer stops only with an explicit `endedAt`
(`422 stopwatch_too_long`) – or is discarded (`discard: true`, the entry is deleted). Overlap is `409`.
Nothing running: `404 no_stopwatch`.

### Request body

`application/json`

- `description` (string): Replaces the description of the entry, when given
- `discard` (boolean): Delete the running entry instead of stopping it
- `endedAt` (string (date-time)): Default now; an explicit end is not rounded

Example:

```json
{
  "description": "Drucker im Empfang eingerichtet, Scan-to-Mail getestet",
  "discard": false
}
```

### Responses

- **200** The stopped (or discarded) entry (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)

Fields of the 200 answer:

- `approvedAt` (string (date-time), nullable): When the entry was approved
- `approvedBy` (string): Who approved the entry (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `article` (WorkArticleRef | null): Masterdata article a flat-rate entry is billed as
- `batchId` (string (uuid), nullable): Billing batch the entry is billed in
- `billableMinutes` (integer): Minutes billed
- `billedRate` (number, nullable): Hourly rate (or article price) the entry was billed at
- `billing` (string): Key of a billing type
- `contract` (WorkContractRef | null): Trade contract that decides billing
- `correctionOf` (string (uuid), nullable): The approved or billed entry this one corrects; its minutes are the difference (may be negative)
- `createdAt` (string (date-time)): When the work entry was created
- `createdBy` (string): Who booked the entry (e-mail)
- `customer` (WorkCustomerRef | null): Customer the work is billed to
- `description` (string): What was done
- `durationSeconds` (integer): The exact length in seconds (the stopwatch's seconds, else `minutes` × 60)
- `employeeId` (string (uuid)): Id of the employee
- `employeeName` (string): Display name of the employee – only in `listApprovableWorkEntries`
- `endedAt` (string (date-time), nullable): `null` for the running stopwatch and for an entry without a span
- `id` (string (uuid)): Id of the work entry
- `kind` (string): Key of a work kind (`getWorkEntrySettings`)
- `km` (number): Kilometres travelled (kinds that allow travel)
- `minutes` (integer): The length in minutes that sums and billing use (a correction's difference, may be negative; 0 for a stopwatch run that rounded to nothing)
- `origin` (string): The call or appointment the time comes from: `comms:interaction:<id>` or `comms:calendar:<id>`; omitted for other work. Booked at most once per tenant (`409 already_booked`)
- `project` (WorkProjectRef | null): Project the work counts for
- `running` (boolean): The running stopwatch entry (start, no end)
- `source` (string): How the entry was booked (one of `manual`, `stopwatch`, `interaction`, `calendar`, `correction`)
- `startedAt` (string (date-time), nullable): `null` for an entry booked as a length only
- `state` (string): suggested → confirmed → approved → billed (one of `suggested`, `confirmed`, `approved`, `billed`)
- `subject` (string): What was worked on: `desk:item:<id>`, `forge:item:<id>`, `crm:activity:<id>`, a project `desk:project:<id>` / `forge:project:<id>`; empty for work on the customer only or internal work
- `subjectLabel` (string): The subject's name at booking time (the origin's without a subject)
- `travelMinutes` (integer): Travel time in minutes (kinds that allow travel)
- `updatedAt` (string (date-time)): When the work entry was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `workDate` (string (date)): The day the work counts for (the person's choice; with a start its day in the tenant's time zone)

Example 200 answer:

```json
{
  "approvedAt": "2026-11-17T08:05:00Z",
  "approvedBy": "martin.brandl@muster-it.example",
  "batchId": null,
  "billableMinutes": 15,
  "billedRate": null,
  "billing": "quota",
  "contract": {
    "id": "7a9c1e3a-5c7e-4a9c-8e3a-5c7e9a1c3e52",
    "number": "WV-2026-0007",
    "quota": true,
    "title": "Wartungsvertrag Netzwerk und WLAN"
  },
  "correctionOf": null,
  "createdAt": "2026-11-16T09:30:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
    "name": "Alpenhotel Seeblick GmbH"
  },
  "description": "Access Point im Restaurant neu gestartet, Kanal gewechselt, Rückruf bei Frau Stadler.",
  "durationSeconds": 900,
  "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "endedAt": "2026-11-16T09:27:00Z",
  "id": "5e7a9c1e-3a5c-4e7a-9c1e-3a5c7e9a1c51",
  "kind": "remote",
  "km": 0,
  "minutes": 15,
  "origin": "comms:interaction:4f6a8c0e-2b4d-4f6a-8c0e-2b4d6f8a0c2e",
  "running": false,
  "source": "interaction",
  "startedAt": "2026-11-16T09:12:00Z",
  "state": "approved",
  "subject": "desk:item:6a8c0e2a-4b6d-4f8a-9c1e-3b5d7f9a1c3e",
  "subjectLabel": "#214 WLAN im Restaurant fällt aus",
  "travelMinutes": 0,
  "updatedAt": "2026-11-17T08:05:00Z",
  "version": 2,
  "workDate": "2026-11-16"
}
```

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/hr/v1/work-entries/stopwatch' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"description":"Drucker im Empfang eingerichtet, Scan-to-Mail getestet","discard":false}'
```

## Approve confirmed entries (line managers and deputies for their team, hr:work:manage for everyone)

`POST /api/hr/v1/work-entries/approve`

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

All or none, each at its `version`. Own entries only with the tenant's `selfApproval` (`403 self_approval`;
line managers never approve their own). Entries of people the caller does not decide for answer `404`; an
entry that is not confirmed or still running `409 work_state`. Approved entries are locked.

### Request body

`application/json` (required)

- `entries` (array of object, required): Entries at the versions the caller saw; all or none
  - `id` (string (uuid), required): Id of the work entry
  - `version` (integer, required): Version of the entry the caller saw

Example:

```json
{
  "entries": [
    {
      "id": "5e7a9c1e-3a5c-4e7a-9c1e-3a5c7e9a1c51",
      "version": 1
    },
    {
      "id": "7a9c1e3a-5c7e-4a9c-9e3a-5c7e9a1c3e53",
      "version": 1
    }
  ]
}
```

### Responses

- **200** Approved (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of WorkEntry, required): The changed entries
  - `approvedAt` (string (date-time), nullable): When the entry was approved
  - `approvedBy` (string): Who approved the entry (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
  - `article` (WorkArticleRef | null): Masterdata article a flat-rate entry is billed as
  - `batchId` (string (uuid), nullable): Billing batch the entry is billed in
  - `billableMinutes` (integer): Minutes billed
  - `billedRate` (number, nullable): Hourly rate (or article price) the entry was billed at
  - `billing` (string): Key of a billing type
  - `contract` (WorkContractRef | null): Trade contract that decides billing
  - `correctionOf` (string (uuid), nullable): The approved or billed entry this one corrects; its minutes are the difference (may be negative)
  - `createdAt` (string (date-time)): When the work entry was created
  - `createdBy` (string): Who booked the entry (e-mail)
  - `customer` (WorkCustomerRef | null): Customer the work is billed to
  - `description` (string): What was done
  - `durationSeconds` (integer): The exact length in seconds (the stopwatch's seconds, else `minutes` × 60)
  - `employeeId` (string (uuid)): Id of the employee
  - `employeeName` (string): Display name of the employee – only in `listApprovableWorkEntries`
  - `endedAt` (string (date-time), nullable): `null` for the running stopwatch and for an entry without a span
  - `id` (string (uuid)): Id of the work entry
  - `kind` (string): Key of a work kind (`getWorkEntrySettings`)
  - `km` (number): Kilometres travelled (kinds that allow travel)
  - `minutes` (integer): The length in minutes that sums and billing use (a correction's difference, may be negative; 0 for a stopwatch run that rounded to nothing)
  - `origin` (string): The call or appointment the time comes from: `comms:interaction:<id>` or `comms:calendar:<id>`; omitted for other work. Booked at most once per tenant (`409 already_booked`)
  - `project` (WorkProjectRef | null): Project the work counts for
  - `running` (boolean): The running stopwatch entry (start, no end)
  - `source` (string): How the entry was booked (one of `manual`, `stopwatch`, `interaction`, `calendar`, `correction`)
  - `startedAt` (string (date-time), nullable): `null` for an entry booked as a length only
  - `state` (string): suggested → confirmed → approved → billed (one of `suggested`, `confirmed`, `approved`, `billed`)
  - `subject` (string): What was worked on: `desk:item:<id>`, `forge:item:<id>`, `crm:activity:<id>`, a project `desk:project:<id>` / `forge:project:<id>`; empty for work on the customer only or internal work
  - `subjectLabel` (string): The subject's name at booking time (the origin's without a subject)
  - `travelMinutes` (integer): Travel time in minutes (kinds that allow travel)
  - `updatedAt` (string (date-time)): When the work entry was last changed
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
  - `workDate` (string (date)): The day the work counts for (the person's choice; with a start its day in the tenant's time zone)

Example 200 answer:

```json
{
  "items": [
    {
      "approvedAt": "2026-11-17T08:05:00Z",
      "approvedBy": "martin.brandl@muster-it.example",
      "billableMinutes": 15,
      "billing": "quota",
      "createdAt": "2026-11-16T09:30:00Z",
      "createdBy": "sophie.huber@muster-it.example",
      "durationSeconds": 900,
      "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "endedAt": "2026-11-16T09:27:00Z",
      "id": "5e7a9c1e-3a5c-4e7a-9c1e-3a5c7e9a1c51",
      "kind": "remote",
      "minutes": 15,
      "running": false,
      "source": "interaction",
      "startedAt": "2026-11-16T09:12:00Z",
      "state": "approved",
      "subject": "desk:item:6a8c0e2a-4b6d-4f8a-9c1e-3b5d7f9a1c3e",
      "subjectLabel": "#214 WLAN im Restaurant fällt aus",
      "updatedAt": "2026-11-17T08:05:00Z",
      "version": 2,
      "workDate": "2026-11-16"
    }
  ]
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/work-entries/approve' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"entries":[{"id":"5e7a9c1e-3a5c-4e7a-9c1e-3a5c7e9a1c51","version":1},{"id":"7a9c1e3a-5c7e-4a9c-9e3a-5c7e9a1c3e53","version":1}]}'
```

## Take approvals back (line managers and deputies for their team, hr:work:manage for everyone)

`POST /api/hr/v1/work-entries/unapprove`

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

All or none; only approved entries no billing batch holds and nobody corrected (`409 work_state`).

### Request body

`application/json` (required)

- `entries` (array of object, required): Entries at the versions the caller saw; all or none
  - `id` (string (uuid), required): Id of the work entry
  - `version` (integer, required): Version of the entry the caller saw

Example:

```json
{
  "entries": [
    {
      "id": "5e7a9c1e-3a5c-4e7a-9c1e-3a5c7e9a1c51",
      "version": 1
    },
    {
      "id": "7a9c1e3a-5c7e-4a9c-9e3a-5c7e9a1c3e53",
      "version": 1
    }
  ]
}
```

### Responses

- **200** Confirmed again (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of WorkEntry, required): The changed entries
  - `approvedAt` (string (date-time), nullable): When the entry was approved
  - `approvedBy` (string): Who approved the entry (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
  - `article` (WorkArticleRef | null): Masterdata article a flat-rate entry is billed as
  - `batchId` (string (uuid), nullable): Billing batch the entry is billed in
  - `billableMinutes` (integer): Minutes billed
  - `billedRate` (number, nullable): Hourly rate (or article price) the entry was billed at
  - `billing` (string): Key of a billing type
  - `contract` (WorkContractRef | null): Trade contract that decides billing
  - `correctionOf` (string (uuid), nullable): The approved or billed entry this one corrects; its minutes are the difference (may be negative)
  - `createdAt` (string (date-time)): When the work entry was created
  - `createdBy` (string): Who booked the entry (e-mail)
  - `customer` (WorkCustomerRef | null): Customer the work is billed to
  - `description` (string): What was done
  - `durationSeconds` (integer): The exact length in seconds (the stopwatch's seconds, else `minutes` × 60)
  - `employeeId` (string (uuid)): Id of the employee
  - `employeeName` (string): Display name of the employee – only in `listApprovableWorkEntries`
  - `endedAt` (string (date-time), nullable): `null` for the running stopwatch and for an entry without a span
  - `id` (string (uuid)): Id of the work entry
  - `kind` (string): Key of a work kind (`getWorkEntrySettings`)
  - `km` (number): Kilometres travelled (kinds that allow travel)
  - `minutes` (integer): The length in minutes that sums and billing use (a correction's difference, may be negative; 0 for a stopwatch run that rounded to nothing)
  - `origin` (string): The call or appointment the time comes from: `comms:interaction:<id>` or `comms:calendar:<id>`; omitted for other work. Booked at most once per tenant (`409 already_booked`)
  - `project` (WorkProjectRef | null): Project the work counts for
  - `running` (boolean): The running stopwatch entry (start, no end)
  - `source` (string): How the entry was booked (one of `manual`, `stopwatch`, `interaction`, `calendar`, `correction`)
  - `startedAt` (string (date-time), nullable): `null` for an entry booked as a length only
  - `state` (string): suggested → confirmed → approved → billed (one of `suggested`, `confirmed`, `approved`, `billed`)
  - `subject` (string): What was worked on: `desk:item:<id>`, `forge:item:<id>`, `crm:activity:<id>`, a project `desk:project:<id>` / `forge:project:<id>`; empty for work on the customer only or internal work
  - `subjectLabel` (string): The subject's name at booking time (the origin's without a subject)
  - `travelMinutes` (integer): Travel time in minutes (kinds that allow travel)
  - `updatedAt` (string (date-time)): When the work entry was last changed
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
  - `workDate` (string (date)): The day the work counts for (the person's choice; with a start its day in the tenant's time zone)

Example 200 answer:

```json
{
  "items": [
    {
      "approvedAt": null,
      "approvedBy": "",
      "billableMinutes": 15,
      "billing": "quota",
      "createdAt": "2026-11-16T09:30:00Z",
      "createdBy": "sophie.huber@muster-it.example",
      "durationSeconds": 900,
      "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "endedAt": "2026-11-16T09:27:00Z",
      "id": "5e7a9c1e-3a5c-4e7a-9c1e-3a5c7e9a1c51",
      "kind": "remote",
      "minutes": 15,
      "running": false,
      "source": "interaction",
      "startedAt": "2026-11-16T09:12:00Z",
      "state": "confirmed",
      "subject": "desk:item:6a8c0e2a-4b6d-4f8a-9c1e-3b5d7f9a1c3e",
      "subjectLabel": "#214 WLAN im Restaurant fällt aus",
      "updatedAt": "2026-11-17T10:20:00Z",
      "version": 3,
      "workDate": "2026-11-16"
    }
  ]
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/work-entries/unapprove' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"entries":[{"id":"5e7a9c1e-3a5c-4e7a-9c1e-3a5c7e9a1c51","version":1},{"id":"7a9c1e3a-5c7e-4a9c-9e3a-5c7e9a1c3e53","version":1}]}'
```

## Correct an approved or billed entry (its owner, line manager or deputy, or hr:work:manage)

`POST /api/hr/v1/work-entries/{id}/corrections`

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

Books a new confirmed entry (`source: correction`, `correctionOf`) whose minutes are the difference to the
effective values asked for, dated today. An entry that is not approved or billed is `409 work_state`. A
correction that brings the effective minutes to zero releases what the entry booked, like a delete: its
`origin` (cleared on the entry and its corrections) and the activities combined into it can be booked again.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `billableMinutes` (integer, required): Effective billable minutes
- `description` (string, required): The reason (max. 2000 characters)
- `minutes` (integer, nullable): Effective worked minutes (null keeps them)

Example:

```json
{
  "billableMinutes": 10,
  "description": "Rückruf war Teil der Gewährleistung, 5 Minuten nicht aus dem Kontingent buchen.",
  "minutes": 15
}
```

### Responses

- **201** The correction (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `approvedAt` (string (date-time), nullable): When the entry was approved
- `approvedBy` (string): Who approved the entry (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `article` (WorkArticleRef | null): Masterdata article a flat-rate entry is billed as
- `batchId` (string (uuid), nullable): Billing batch the entry is billed in
- `billableMinutes` (integer): Minutes billed
- `billedRate` (number, nullable): Hourly rate (or article price) the entry was billed at
- `billing` (string): Key of a billing type
- `contract` (WorkContractRef | null): Trade contract that decides billing
- `correctionOf` (string (uuid), nullable): The approved or billed entry this one corrects; its minutes are the difference (may be negative)
- `createdAt` (string (date-time)): When the work entry was created
- `createdBy` (string): Who booked the entry (e-mail)
- `customer` (WorkCustomerRef | null): Customer the work is billed to
- `description` (string): What was done
- `durationSeconds` (integer): The exact length in seconds (the stopwatch's seconds, else `minutes` × 60)
- `employeeId` (string (uuid)): Id of the employee
- `employeeName` (string): Display name of the employee – only in `listApprovableWorkEntries`
- `endedAt` (string (date-time), nullable): `null` for the running stopwatch and for an entry without a span
- `id` (string (uuid)): Id of the work entry
- `kind` (string): Key of a work kind (`getWorkEntrySettings`)
- `km` (number): Kilometres travelled (kinds that allow travel)
- `minutes` (integer): The length in minutes that sums and billing use (a correction's difference, may be negative; 0 for a stopwatch run that rounded to nothing)
- `origin` (string): The call or appointment the time comes from: `comms:interaction:<id>` or `comms:calendar:<id>`; omitted for other work. Booked at most once per tenant (`409 already_booked`)
- `project` (WorkProjectRef | null): Project the work counts for
- `running` (boolean): The running stopwatch entry (start, no end)
- `source` (string): How the entry was booked (one of `manual`, `stopwatch`, `interaction`, `calendar`, `correction`)
- `startedAt` (string (date-time), nullable): `null` for an entry booked as a length only
- `state` (string): suggested → confirmed → approved → billed (one of `suggested`, `confirmed`, `approved`, `billed`)
- `subject` (string): What was worked on: `desk:item:<id>`, `forge:item:<id>`, `crm:activity:<id>`, a project `desk:project:<id>` / `forge:project:<id>`; empty for work on the customer only or internal work
- `subjectLabel` (string): The subject's name at booking time (the origin's without a subject)
- `travelMinutes` (integer): Travel time in minutes (kinds that allow travel)
- `updatedAt` (string (date-time)): When the work entry was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `workDate` (string (date)): The day the work counts for (the person's choice; with a start its day in the tenant's time zone)

Example 201 answer:

```json
{
  "approvedAt": "2026-11-17T08:05:00Z",
  "approvedBy": "martin.brandl@muster-it.example",
  "batchId": null,
  "billableMinutes": 15,
  "billedRate": null,
  "billing": "quota",
  "contract": {
    "id": "7a9c1e3a-5c7e-4a9c-8e3a-5c7e9a1c3e52",
    "number": "WV-2026-0007",
    "quota": true,
    "title": "Wartungsvertrag Netzwerk und WLAN"
  },
  "correctionOf": null,
  "createdAt": "2026-11-16T09:30:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
    "name": "Alpenhotel Seeblick GmbH"
  },
  "description": "Access Point im Restaurant neu gestartet, Kanal gewechselt, Rückruf bei Frau Stadler.",
  "durationSeconds": 900,
  "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "endedAt": "2026-11-16T09:27:00Z",
  "id": "5e7a9c1e-3a5c-4e7a-9c1e-3a5c7e9a1c51",
  "kind": "remote",
  "km": 0,
  "minutes": 15,
  "origin": "comms:interaction:4f6a8c0e-2b4d-4f6a-8c0e-2b4d6f8a0c2e",
  "running": false,
  "source": "interaction",
  "startedAt": "2026-11-16T09:12:00Z",
  "state": "approved",
  "subject": "desk:item:6a8c0e2a-4b6d-4f8a-9c1e-3b5d7f9a1c3e",
  "subjectLabel": "#214 WLAN im Restaurant fällt aus",
  "travelMinutes": 0,
  "updatedAt": "2026-11-17T08:05:00Z",
  "version": 2,
  "workDate": "2026-11-16"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/work-entries/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/corrections' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"billableMinutes":10,"description":"Rückruf war Teil der Gewährleistung, 5 Minuten nicht aus dem Kontingent buchen.","minutes":15}'
```

## Work entries of a team member (line managers and deputies, hr:work:manage)

`GET /api/hr/v1/employees/{id}/work-entries`

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

Like `listWorkEntries` for the employee in the path; people the caller does not decide for answer `404`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `subject` | query | string |  | Only the entries on this subject, every day, newest first (max length 200) |
| `from` | query | string (date) |  |  |
| `to` | query | string (date) |  |  |
| `state` | query | string |  | (one of `suggested`, `confirmed`, `approved`, `billed`) |
| `limit` | query | integer |  | 1–200; another value is a 400 invalid. (default `50`; max 200) |
| `offset` | query | integer |  | (default `0`) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Entries (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of WorkEntry, required): Entries of this page
  - `approvedAt` (string (date-time), nullable): When the entry was approved
  - `approvedBy` (string): Who approved the entry (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
  - `article` (WorkArticleRef | null): Masterdata article a flat-rate entry is billed as
  - `batchId` (string (uuid), nullable): Billing batch the entry is billed in
  - `billableMinutes` (integer): Minutes billed
  - `billedRate` (number, nullable): Hourly rate (or article price) the entry was billed at
  - `billing` (string): Key of a billing type
  - `contract` (WorkContractRef | null): Trade contract that decides billing
  - `correctionOf` (string (uuid), nullable): The approved or billed entry this one corrects; its minutes are the difference (may be negative)
  - `createdAt` (string (date-time)): When the work entry was created
  - `createdBy` (string): Who booked the entry (e-mail)
  - `customer` (WorkCustomerRef | null): Customer the work is billed to
  - `description` (string): What was done
  - `durationSeconds` (integer): The exact length in seconds (the stopwatch's seconds, else `minutes` × 60)
  - `employeeId` (string (uuid)): Id of the employee
  - `employeeName` (string): Display name of the employee – only in `listApprovableWorkEntries`
  - `endedAt` (string (date-time), nullable): `null` for the running stopwatch and for an entry without a span
  - `id` (string (uuid)): Id of the work entry
  - `kind` (string): Key of a work kind (`getWorkEntrySettings`)
  - `km` (number): Kilometres travelled (kinds that allow travel)
  - `minutes` (integer): The length in minutes that sums and billing use (a correction's difference, may be negative; 0 for a stopwatch run that rounded to nothing)
  - `origin` (string): The call or appointment the time comes from: `comms:interaction:<id>` or `comms:calendar:<id>`; omitted for other work. Booked at most once per tenant (`409 already_booked`)
  - `project` (WorkProjectRef | null): Project the work counts for
  - `running` (boolean): The running stopwatch entry (start, no end)
  - `source` (string): How the entry was booked (one of `manual`, `stopwatch`, `interaction`, `calendar`, `correction`)
  - `startedAt` (string (date-time), nullable): `null` for an entry booked as a length only
  - `state` (string): suggested → confirmed → approved → billed (one of `suggested`, `confirmed`, `approved`, `billed`)
  - `subject` (string): What was worked on: `desk:item:<id>`, `forge:item:<id>`, `crm:activity:<id>`, a project `desk:project:<id>` / `forge:project:<id>`; empty for work on the customer only or internal work
  - `subjectLabel` (string): The subject's name at booking time (the origin's without a subject)
  - `travelMinutes` (integer): Travel time in minutes (kinds that allow travel)
  - `updatedAt` (string (date-time)): When the work entry was last changed
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
  - `workDate` (string (date)): The day the work counts for (the person's choice; with a start its day in the tenant's time zone)
- `total` (integer): Number of all matching entries

Example 200 answer:

```json
{
  "items": [
    {
      "approvedAt": "2026-11-17T08:05:00Z",
      "approvedBy": "martin.brandl@muster-it.example",
      "billableMinutes": 15,
      "billing": "quota",
      "contract": {
        "id": "7a9c1e3a-5c7e-4a9c-8e3a-5c7e9a1c3e52",
        "number": "WV-2026-0007",
        "quota": true,
        "title": "Wartungsvertrag Netzwerk und WLAN"
      },
      "createdAt": "2026-11-16T09:30:00Z",
      "createdBy": "sophie.huber@muster-it.example",
      "customer": {
        "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
        "name": "Alpenhotel Seeblick GmbH"
      },
      "description": "Access Point im Restaurant neu gestartet, Kanal gewechselt, Rückruf bei Frau Stadler.",
      "durationSeconds": 900,
      "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "endedAt": "2026-11-16T09:27:00Z",
      "id": "5e7a9c1e-3a5c-4e7a-9c1e-3a5c7e9a1c51",
      "kind": "remote",
      "minutes": 15,
      "origin": "comms:interaction:4f6a8c0e-2b4d-4f6a-8c0e-2b4d6f8a0c2e",
      "running": false,
      "source": "interaction",
      "startedAt": "2026-11-16T09:12:00Z",
      "state": "approved",
      "subject": "desk:item:6a8c0e2a-4b6d-4f8a-9c1e-3b5d7f9a1c3e",
      "subjectLabel": "#214 WLAN im Restaurant fällt aus",
      "updatedAt": "2026-11-17T08:05:00Z",
      "version": 2,
      "workDate": "2026-11-16"
    },
    {
      "billableMinutes": 0,
      "billing": "none",
      "createdAt": "2026-11-16T15:10:00Z",
      "createdBy": "sophie.huber@muster-it.example",
      "description": "Teambesprechung Service Desk",
      "durationSeconds": 2700,
      "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "endedAt": null,
      "id": "7a9c1e3a-5c7e-4a9c-9e3a-5c7e9a1c3e53",
      "kind": "internal",
      "minutes": 45,
      "running": false,
      "source": "manual",
      "startedAt": null,
      "state": "confirmed",
      "subject": "",
      "updatedAt": "2026-11-16T15:10:00Z",
      "version": 1,
      "workDate": "2026-11-16"
    }
  ],
  "total": 2
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/employees/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/work-entries' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## The caller's day – attendance, work entries, totals and what is not booked yet (tenant:access)

`GET /api/hr/v1/my-day`

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

„Mein Tag“: the attendance day of the timesheet, the finished work entries of the work day (corrections
included) and the running stopwatch, the totals (attended = the attendance's actual time, booked,
billable, internal, gap = max(0, attended − booked); suggestions do not count) and the open items – the
caller's calls, meetings and remote sessions (not internal) and Microsoft 365 appointments (not all-day) that
are not booked yet, oldest first; private appointments without a label. comms is asked with the e-mail of the
caller's employee record. comms failing never fails the page: `openUnavailable` is set and `open` keeps what
arrived; `openTruncated` when comms listed only part of the day. Without an employee record `403 no_employee`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `date` | query | string (date) |  | Day (default today in the tenant's time zone) |

### Responses

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

Fields of the 200 answer:

- `attendance` (TimesheetDay, required): One day of a timesheet (minutes)
  - `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)
- `attendanceHidden` (boolean, required): The caller sees the work but not the attendance of this person (`hr:work:manage` alone): `attendance` is empty, attended and gap minutes are 0
- `date` (string (date), required): The day (YYYY-MM-DD)
- `employeeId` (string (uuid), required): Id of the employee
- `entries` (array of WorkEntry, required): Finished entries of the work day, corrections included
  - `approvedAt` (string (date-time), nullable): When the entry was approved
  - `approvedBy` (string): Who approved the entry (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
  - `article` (WorkArticleRef | null): Masterdata article a flat-rate entry is billed as
  - `batchId` (string (uuid), nullable): Billing batch the entry is billed in
  - `billableMinutes` (integer): Minutes billed
  - `billedRate` (number, nullable): Hourly rate (or article price) the entry was billed at
  - `billing` (string): Key of a billing type
  - `contract` (WorkContractRef | null): Trade contract that decides billing
  - `correctionOf` (string (uuid), nullable): The approved or billed entry this one corrects; its minutes are the difference (may be negative)
  - `createdAt` (string (date-time)): When the work entry was created
  - `createdBy` (string): Who booked the entry (e-mail)
  - `customer` (WorkCustomerRef | null): Customer the work is billed to
  - `description` (string): What was done
  - `durationSeconds` (integer): The exact length in seconds (the stopwatch's seconds, else `minutes` × 60)
  - `employeeId` (string (uuid)): Id of the employee
  - `employeeName` (string): Display name of the employee – only in `listApprovableWorkEntries`
  - `endedAt` (string (date-time), nullable): `null` for the running stopwatch and for an entry without a span
  - `id` (string (uuid)): Id of the work entry
  - `kind` (string): Key of a work kind (`getWorkEntrySettings`)
  - `km` (number): Kilometres travelled (kinds that allow travel)
  - `minutes` (integer): The length in minutes that sums and billing use (a correction's difference, may be negative; 0 for a stopwatch run that rounded to nothing)
  - `origin` (string): The call or appointment the time comes from: `comms:interaction:<id>` or `comms:calendar:<id>`; omitted for other work. Booked at most once per tenant (`409 already_booked`)
  - `project` (WorkProjectRef | null): Project the work counts for
  - `running` (boolean): The running stopwatch entry (start, no end)
  - `source` (string): How the entry was booked (one of `manual`, `stopwatch`, `interaction`, `calendar`, `correction`)
  - `startedAt` (string (date-time), nullable): `null` for an entry booked as a length only
  - `state` (string): suggested → confirmed → approved → billed (one of `suggested`, `confirmed`, `approved`, `billed`)
  - `subject` (string): What was worked on: `desk:item:<id>`, `forge:item:<id>`, `crm:activity:<id>`, a project `desk:project:<id>` / `forge:project:<id>`; empty for work on the customer only or internal work
  - `subjectLabel` (string): The subject's name at booking time (the origin's without a subject)
  - `travelMinutes` (integer): Travel time in minutes (kinds that allow travel)
  - `updatedAt` (string (date-time)): When the work entry was last changed
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
  - `workDate` (string (date)): The day the work counts for (the person's choice; with a start its day in the tenant's time zone)
- `open` (array of OpenItem, required): Not booked yet (own day only)
  - `customer` (WorkCustomerRef | null, required): The customer comms suggests
  - `end` (string (date-time), required): End
  - `kind` (string, required): Kind of the item (one of `call`, `meeting`, `remote_session`, `calendar`)
  - `label` (string, required): Subject or other side; empty for a private appointment (busy time)
  - `private` (boolean, required): A private appointment (no label)
  - `start` (string (date-time), required): Start
  - `subject` (string, required): `comms:interaction:<id>` or `comms:calendar:<id>`
- `openTruncated` (boolean, required): comms listed only part of the day
- `openUnavailable` (boolean, required): comms could not be asked; `open` holds what arrived
- `running` (WorkEntry | null, required): The running stopwatch entry, whatever day it started
- `totals` (MyDayTotals, required)
  - `attendedMinutes` (integer, required): The attendance's actual time
  - `billableMinutes` (integer, required): Billable minutes of the finished entries
  - `bookedMinutes` (integer, required): Finished entries, corrections with their sign (as `getWorkSummary`)
  - `gapMinutes` (integer, required): max(0, attended − booked)
  - `internalMinutes` (integer, required): Booked on non-billable billing types

Example 200 answer:

```json
{
  "attendance": {
    "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": []
  },
  "attendanceHidden": false,
  "date": "2026-11-19",
  "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "entries": [
    {
      "billableMinutes": 0,
      "billing": "none",
      "createdAt": "2026-11-19T07:21:00Z",
      "createdBy": "sophie.huber@muster-it.example",
      "description": "Ticket-Queue gesichtet und verteilt",
      "durationSeconds": 2700,
      "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "endedAt": "2026-11-19T07:20:00Z",
      "id": "0f2b4d6f-8b0d-4f2b-9d6f-8b0d2f4b6d57",
      "kind": "internal",
      "minutes": 45,
      "running": false,
      "source": "manual",
      "startedAt": "2026-11-19T06:35:00Z",
      "state": "confirmed",
      "subject": "",
      "updatedAt": "2026-11-19T07:21:00Z",
      "version": 1,
      "workDate": "2026-11-19"
    }
  ],
  "open": [
    {
      "customer": {
        "id": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
        "name": "Kanzlei Hofmann \u0026 Partner"
      },
      "end": "2026-11-19T08:13:00Z",
      "kind": "call",
      "label": "Florian Pichler",
      "private": false,
      "start": "2026-11-19T08:05:00Z",
      "subject": "comms:interaction:2d4f6b8d-0f2b-4d4f-8b8d-0f2b4d6f8b56"
    }
  ],
  "openTruncated": false,
  "openUnavailable": false,
  "running": {
    "billableMinutes": 0,
    "billing": "hourly",
    "createdAt": "2026-11-19T08:40:00Z",
    "createdBy": "sophie.huber@muster-it.example",
    "customer": {
      "id": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
      "name": "Kanzlei Hofmann \u0026 Partner"
    },
    "description": "Drucker im Empfang einrichten",
    "durationSeconds": 0,
    "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
    "endedAt": null,
    "id": "9c1e3a5c-7e9a-4c1e-8a5c-7e9a1c3e5a54",
    "kind": "remote",
    "minutes": 0,
    "running": true,
    "source": "stopwatch",
    "startedAt": "2026-11-19T08:40:00Z",
    "state": "confirmed",
    "subject": "desk:item:8c0e2a4c-6e8a-4c0e-9a2c-4e6a8c0e2a55",
    "subjectLabel": "#231 Neuer Drucker am Empfang",
    "updatedAt": "2026-11-19T08:40:00Z",
    "version": 1,
    "workDate": "2026-11-19"
  },
  "totals": {
    "attendedMinutes": 145,
    "billableMinutes": 0,
    "bookedMinutes": 45,
    "gapMinutes": 100,
    "internalMinutes": 45
  }
}
```

### Example request

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

## 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"
```

## Whom I share my calendar with and who shares theirs with me (tenant:access)

`GET /api/hr/v1/calendar/shares`

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

`sharedWith` are the colleagues the caller lets see their calendar, `sharedWithMe` the colleagues who share
theirs with the caller; oldest share first. A share only opens the calendar: what the viewer sees of each item
is decided per item. Without an employee record `403 no_employee`.

### Responses

- **200** The shares (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `sharedWith` (array of PersonRef, required): The colleagues the caller shares their calendar with
  - `displayName` (string): Display name of the employee
  - `email` (string): E-mail address of the employee
  - `id` (string): Id of the employee
- `sharedWithMe` (array of PersonRef, required): The colleagues who share their calendar with the caller
  - `displayName` (string): Display name of the employee
  - `email` (string): E-mail address of the employee
  - `id` (string): Id of the employee

Example 200 answer:

```json
{
  "sharedWith": [
    {
      "displayName": "Elias Gruber",
      "email": "elias.gruber@muster-it.example",
      "id": "c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06"
    },
    {
      "displayName": "Martin Brandl",
      "email": "martin.brandl@muster-it.example",
      "id": "b2d4f6a8-0c1e-4a3b-9d5f-7e9a1c3b5d04"
    }
  ],
  "sharedWithMe": []
}
```

### Example request

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

## Search colleagues to share my calendar with (tenant:access)

`GET /api/hr/v1/calendar/shares/candidates`

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

Active employees of the tenant whose name matches `q` (case-insensitive, part of the name; never matched on the e-mail address), the caller excluded,
sorted by name, at most 20. Only `id` and `name` are returned. Needs no `hr:read`. `q` has at least 2 characters
(else `400`); without an employee record `403 no_employee`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `q` | query | string | yes | Part of the name, at least 2 characters |

### Responses

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

Fields of the 200 answer:

- `items` (array of CalendarShareCandidate, required): Matching colleagues, sorted by name (at most 20)
  - `id` (string (uuid), required): Id of the employee
  - `name` (string, required): Display name of the employee

Example 200 answer:

```json
{
  "items": [
    {
      "id": "c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06",
      "name": "Elias Gruber"
    },
    {
      "id": "2c4e6a8c-0e2a-4c4e-9a6c-0e2a4c6e8a60",
      "name": "Emma Maier"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/calendar/shares/candidates?q=string' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Share my calendar with a colleague (tenant:access)

`PUT /api/hr/v1/calendar/shares/{employeeId}`

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

Idempotent: sharing again changes nothing. Sharing with oneself is `400`, a person who is not an employee of the
tenant `404`; without an employee record `403 no_employee`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `employeeId` | path | string (uuid) | yes | The colleague |

### Responses

- **204** Shared
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/calendar/shares/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Stop sharing my calendar with a colleague (tenant:access)

`DELETE /api/hr/v1/calendar/shares/{employeeId}`

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

Idempotent: ending a share that does not exist is no error. Only the owner revokes; without an employee record
`403 no_employee`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `employeeId` | path | string (uuid) | yes | The colleague |

### Responses

- **204** Not shared (any more)
- **403** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/hr/v1/calendar/shares/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## A team member's day (line managers and deputies, hr:work:manage)

`GET /api/hr/v1/employees/{id}/my-day`

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

Like `getMyDay` for the employee in the path. For another person `open` is empty (people book only for
themselves) and the attendance is shown only to who sees it under the attendance rules (`hr:time:manage`, line
managers and deputies); with `hr:work:manage` alone `attendanceHidden` is set, `attendance` empty and
`attendedMinutes`/`gapMinutes` are 0. The caller's own id answers like `getMyDay`, open items included. People
the caller does not decide for answer `404`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `date` | query | string (date) |  | Day (default today in the tenant's time zone) |
| `id` | path | string (uuid) | yes |  |

### Responses

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

Fields of the 200 answer:

- `attendance` (TimesheetDay, required): One day of a timesheet (minutes)
  - `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)
- `attendanceHidden` (boolean, required): The caller sees the work but not the attendance of this person (`hr:work:manage` alone): `attendance` is empty, attended and gap minutes are 0
- `date` (string (date), required): The day (YYYY-MM-DD)
- `employeeId` (string (uuid), required): Id of the employee
- `entries` (array of WorkEntry, required): Finished entries of the work day, corrections included
  - `approvedAt` (string (date-time), nullable): When the entry was approved
  - `approvedBy` (string): Who approved the entry (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
  - `article` (WorkArticleRef | null): Masterdata article a flat-rate entry is billed as
  - `batchId` (string (uuid), nullable): Billing batch the entry is billed in
  - `billableMinutes` (integer): Minutes billed
  - `billedRate` (number, nullable): Hourly rate (or article price) the entry was billed at
  - `billing` (string): Key of a billing type
  - `contract` (WorkContractRef | null): Trade contract that decides billing
  - `correctionOf` (string (uuid), nullable): The approved or billed entry this one corrects; its minutes are the difference (may be negative)
  - `createdAt` (string (date-time)): When the work entry was created
  - `createdBy` (string): Who booked the entry (e-mail)
  - `customer` (WorkCustomerRef | null): Customer the work is billed to
  - `description` (string): What was done
  - `durationSeconds` (integer): The exact length in seconds (the stopwatch's seconds, else `minutes` × 60)
  - `employeeId` (string (uuid)): Id of the employee
  - `employeeName` (string): Display name of the employee – only in `listApprovableWorkEntries`
  - `endedAt` (string (date-time), nullable): `null` for the running stopwatch and for an entry without a span
  - `id` (string (uuid)): Id of the work entry
  - `kind` (string): Key of a work kind (`getWorkEntrySettings`)
  - `km` (number): Kilometres travelled (kinds that allow travel)
  - `minutes` (integer): The length in minutes that sums and billing use (a correction's difference, may be negative; 0 for a stopwatch run that rounded to nothing)
  - `origin` (string): The call or appointment the time comes from: `comms:interaction:<id>` or `comms:calendar:<id>`; omitted for other work. Booked at most once per tenant (`409 already_booked`)
  - `project` (WorkProjectRef | null): Project the work counts for
  - `running` (boolean): The running stopwatch entry (start, no end)
  - `source` (string): How the entry was booked (one of `manual`, `stopwatch`, `interaction`, `calendar`, `correction`)
  - `startedAt` (string (date-time), nullable): `null` for an entry booked as a length only
  - `state` (string): suggested → confirmed → approved → billed (one of `suggested`, `confirmed`, `approved`, `billed`)
  - `subject` (string): What was worked on: `desk:item:<id>`, `forge:item:<id>`, `crm:activity:<id>`, a project `desk:project:<id>` / `forge:project:<id>`; empty for work on the customer only or internal work
  - `subjectLabel` (string): The subject's name at booking time (the origin's without a subject)
  - `travelMinutes` (integer): Travel time in minutes (kinds that allow travel)
  - `updatedAt` (string (date-time)): When the work entry was last changed
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
  - `workDate` (string (date)): The day the work counts for (the person's choice; with a start its day in the tenant's time zone)
- `open` (array of OpenItem, required): Not booked yet (own day only)
  - `customer` (WorkCustomerRef | null, required): The customer comms suggests
  - `end` (string (date-time), required): End
  - `kind` (string, required): Kind of the item (one of `call`, `meeting`, `remote_session`, `calendar`)
  - `label` (string, required): Subject or other side; empty for a private appointment (busy time)
  - `private` (boolean, required): A private appointment (no label)
  - `start` (string (date-time), required): Start
  - `subject` (string, required): `comms:interaction:<id>` or `comms:calendar:<id>`
- `openTruncated` (boolean, required): comms listed only part of the day
- `openUnavailable` (boolean, required): comms could not be asked; `open` holds what arrived
- `running` (WorkEntry | null, required): The running stopwatch entry, whatever day it started
- `totals` (MyDayTotals, required)
  - `attendedMinutes` (integer, required): The attendance's actual time
  - `billableMinutes` (integer, required): Billable minutes of the finished entries
  - `bookedMinutes` (integer, required): Finished entries, corrections with their sign (as `getWorkSummary`)
  - `gapMinutes` (integer, required): max(0, attended − booked)
  - `internalMinutes` (integer, required): Booked on non-billable billing types

Example 200 answer:

```json
{
  "attendance": {
    "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": []
  },
  "attendanceHidden": false,
  "date": "2026-11-19",
  "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "entries": [
    {
      "billableMinutes": 0,
      "billing": "none",
      "createdAt": "2026-11-19T07:21:00Z",
      "createdBy": "sophie.huber@muster-it.example",
      "description": "Ticket-Queue gesichtet und verteilt",
      "durationSeconds": 2700,
      "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "endedAt": "2026-11-19T07:20:00Z",
      "id": "0f2b4d6f-8b0d-4f2b-9d6f-8b0d2f4b6d57",
      "kind": "internal",
      "minutes": 45,
      "running": false,
      "source": "manual",
      "startedAt": "2026-11-19T06:35:00Z",
      "state": "confirmed",
      "subject": "",
      "updatedAt": "2026-11-19T07:21:00Z",
      "version": 1,
      "workDate": "2026-11-19"
    }
  ],
  "open": [
    {
      "customer": {
        "id": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
        "name": "Kanzlei Hofmann \u0026 Partner"
      },
      "end": "2026-11-19T08:13:00Z",
      "kind": "call",
      "label": "Florian Pichler",
      "private": false,
      "start": "2026-11-19T08:05:00Z",
      "subject": "comms:interaction:2d4f6b8d-0f2b-4d4f-8b8d-0f2b4d6f8b56"
    }
  ],
  "openTruncated": false,
  "openUnavailable": false,
  "running": {
    "billableMinutes": 0,
    "billing": "hourly",
    "createdAt": "2026-11-19T08:40:00Z",
    "createdBy": "sophie.huber@muster-it.example",
    "customer": {
      "id": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
      "name": "Kanzlei Hofmann \u0026 Partner"
    },
    "description": "Drucker im Empfang einrichten",
    "durationSeconds": 0,
    "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
    "endedAt": null,
    "id": "9c1e3a5c-7e9a-4c1e-8a5c-7e9a1c3e5a54",
    "kind": "remote",
    "minutes": 0,
    "running": true,
    "source": "stopwatch",
    "startedAt": "2026-11-19T08:40:00Z",
    "state": "confirmed",
    "subject": "desk:item:8c0e2a4c-6e8a-4c0e-9a2c-4e6a8c0e2a55",
    "subjectLabel": "#231 Neuer Drucker am Empfang",
    "updatedAt": "2026-11-19T08:40:00Z",
    "version": 1,
    "workDate": "2026-11-19"
  },
  "totals": {
    "attendedMinutes": 145,
    "billableMinutes": 0,
    "bookedMinutes": 45,
    "gapMinutes": 100,
    "internalMinutes": 45
  }
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/employees/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/my-day' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Work kinds, billing types and the tenant's work rules (tenant:access or hr:work:manage)

`GET /api/hr/v1/work-entry-settings`

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

### Responses

- **200** Settings with the defaults filled in (`application/json`)

Fields of the 200 answer:

- `activityDefaults` (object): Booking defaults per activity kind (`call`, `meeting`, `remote_session`, `appointment`) of the activity list; a kind without an entry books with HR's default kind and billing type, no minimum and no rounding.
- `billingTypes` (array of object): How work is billed (Nach Aufwand, Pauschale, Kontingent, Nicht verrechenbar)
  - `flags` (array of string): Meaning for the code: the default type, nothing billed, a flat rate billed, a contract quota consumed
  - `key` (string): Stable key of the billing type
  - `label` (string): Display name
- `kinds` (array of object): Kinds of work (Remote, Vor Ort, Intern, …)
  - `flags` (array of string): Meaning for the code: the default kind, travel time and km allowed, internal work
  - `key` (string): Stable key of the kind
  - `label` (string): Display name
- `rounding` (object): How the seconds of a stopped stopwatch become minutes, once, when it stops. Manual entries, edits and an explicit `endedAt` are never rounded; the exact seconds stay in `durationSeconds`. Always returned; a save without it means `nearest` and `1`.
  - `direction` (string): `nearest` rounds half up (one of `up`, `down`, `nearest`; default `"nearest"`)
  - `stepMinutes` (integer): Rounds to a multiple of this many minutes (one of `1`, `5`, `10`, `15`, `30`, `60`; default `1`)
- `selfApproval` (boolean): Approvers may approve their own work
- `tax` (number): Tax rate of hourly invoice lines (default 19)
- `trafficLight` (object): The time traffic light: booked time as a share of the time worked or of the target
  - `denominator` (string): What it is compared with: time worked so far or the target of the day (one of `worked`, `target`)
  - `greenAt` (integer): Green from this percentage
  - `numerator` (string): What booked time counts (one of `all`, `billable`, `nonBillable`)
  - `yellowAt` (integer): Yellow from this percentage (else red)
- `unit` (string): Unit of hourly invoice lines (default Std)
- `version` (integer (int64)): The configuration's version; send it back on save

Example 200 answer:

```json
{
  "activityDefaults": {
    "call": {
      "billing": "",
      "minMinutes": 15,
      "minSeconds": 60,
      "roundMinutes": 15,
      "timeKind": "remote"
    },
    "remote_session": {
      "billing": "",
      "minMinutes": 15,
      "minSeconds": 120,
      "roundMinutes": 5,
      "timeKind": "remote"
    }
  },
  "billingTypes": [
    {
      "flags": [
        "default"
      ],
      "key": "hourly",
      "label": "Nach Aufwand"
    },
    {
      "flags": [
        "flatRate"
      ],
      "key": "flat",
      "label": "Pauschale"
    },
    {
      "flags": [
        "quota"
      ],
      "key": "quota",
      "label": "Kontingent"
    },
    {
      "flags": [
        "nonBillable"
      ],
      "key": "none",
      "label": "Nicht verrechenbar"
    }
  ],
  "kinds": [
    {
      "flags": [
        "internal"
      ],
      "key": "internal",
      "label": "Intern"
    },
    {
      "flags": [
        "default"
      ],
      "key": "remote",
      "label": "Remote"
    },
    {
      "flags": [
        "allowsTravel"
      ],
      "key": "onsite",
      "label": "Vor Ort"
    }
  ],
  "rounding": {
    "direction": "up",
    "stepMinutes": 5
  },
  "selfApproval": false,
  "tax": 19,
  "trafficLight": {
    "denominator": "worked",
    "greenAt": 80,
    "numerator": "all",
    "yellowAt": 50
  },
  "unit": "Std",
  "version": 3
}
```

### Example request

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

## Save the work settings (hr:work:manage)

`PUT /api/hr/v1/work-entry-settings`

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

Replaces only the work part of HR's module configuration, at its `version` (`0` before anything was saved;
stale: `409 version_conflict`). Configured kinds and billing types each name exactly one default; configured
billing types include one `nonBillable` (internal work).

### Request body

`application/json` (required)

- `activityDefaults` (object): Booking defaults per activity kind (`call`, `meeting`, `remote_session`, `appointment`) of the activity list; a kind without an entry books with HR's default kind and billing type, no minimum and no rounding.
- `billingTypes` (array of object): How work is billed (Nach Aufwand, Pauschale, Kontingent, Nicht verrechenbar)
  - `flags` (array of string): Meaning for the code: the default type, nothing billed, a flat rate billed, a contract quota consumed
  - `key` (string): Stable key of the billing type
  - `label` (string): Display name
- `kinds` (array of object): Kinds of work (Remote, Vor Ort, Intern, …)
  - `flags` (array of string): Meaning for the code: the default kind, travel time and km allowed, internal work
  - `key` (string): Stable key of the kind
  - `label` (string): Display name
- `rounding` (object): How the seconds of a stopped stopwatch become minutes, once, when it stops. Manual entries, edits and an explicit `endedAt` are never rounded; the exact seconds stay in `durationSeconds`. Always returned; a save without it means `nearest` and `1`.
  - `direction` (string): `nearest` rounds half up (one of `up`, `down`, `nearest`; default `"nearest"`)
  - `stepMinutes` (integer): Rounds to a multiple of this many minutes (one of `1`, `5`, `10`, `15`, `30`, `60`; default `1`)
- `selfApproval` (boolean): Approvers may approve their own work
- `tax` (number): Tax rate of hourly invoice lines (default 19)
- `trafficLight` (object): The time traffic light: booked time as a share of the time worked or of the target
  - `denominator` (string): What it is compared with: time worked so far or the target of the day (one of `worked`, `target`)
  - `greenAt` (integer): Green from this percentage
  - `numerator` (string): What booked time counts (one of `all`, `billable`, `nonBillable`)
  - `yellowAt` (integer): Yellow from this percentage (else red)
- `unit` (string): Unit of hourly invoice lines (default Std)
- `version` (integer (int64)): The configuration's version; send it back on save

Example:

```json
{
  "activityDefaults": {
    "call": {
      "billing": "",
      "minMinutes": 15,
      "minSeconds": 60,
      "roundMinutes": 15,
      "timeKind": "remote"
    },
    "remote_session": {
      "billing": "",
      "minMinutes": 15,
      "minSeconds": 120,
      "roundMinutes": 5,
      "timeKind": "remote"
    }
  },
  "billingTypes": [
    {
      "flags": [
        "default"
      ],
      "key": "hourly",
      "label": "Nach Aufwand"
    },
    {
      "flags": [
        "flatRate"
      ],
      "key": "flat",
      "label": "Pauschale"
    },
    {
      "flags": [
        "quota"
      ],
      "key": "quota",
      "label": "Kontingent"
    },
    {
      "flags": [
        "nonBillable"
      ],
      "key": "none",
      "label": "Nicht verrechenbar"
    }
  ],
  "kinds": [
    {
      "flags": [
        "internal"
      ],
      "key": "internal",
      "label": "Intern"
    },
    {
      "flags": [
        "default"
      ],
      "key": "remote",
      "label": "Remote"
    },
    {
      "flags": [
        "allowsTravel"
      ],
      "key": "onsite",
      "label": "Vor Ort"
    }
  ],
  "rounding": {
    "direction": "up",
    "stepMinutes": 5
  },
  "selfApproval": false,
  "tax": 19,
  "trafficLight": {
    "denominator": "worked",
    "greenAt": 80,
    "numerator": "all",
    "yellowAt": 50
  },
  "unit": "Std",
  "version": 3
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `activityDefaults` (object): Booking defaults per activity kind (`call`, `meeting`, `remote_session`, `appointment`) of the activity list; a kind without an entry books with HR's default kind and billing type, no minimum and no rounding.
- `billingTypes` (array of object): How work is billed (Nach Aufwand, Pauschale, Kontingent, Nicht verrechenbar)
  - `flags` (array of string): Meaning for the code: the default type, nothing billed, a flat rate billed, a contract quota consumed
  - `key` (string): Stable key of the billing type
  - `label` (string): Display name
- `kinds` (array of object): Kinds of work (Remote, Vor Ort, Intern, …)
  - `flags` (array of string): Meaning for the code: the default kind, travel time and km allowed, internal work
  - `key` (string): Stable key of the kind
  - `label` (string): Display name
- `rounding` (object): How the seconds of a stopped stopwatch become minutes, once, when it stops. Manual entries, edits and an explicit `endedAt` are never rounded; the exact seconds stay in `durationSeconds`. Always returned; a save without it means `nearest` and `1`.
  - `direction` (string): `nearest` rounds half up (one of `up`, `down`, `nearest`; default `"nearest"`)
  - `stepMinutes` (integer): Rounds to a multiple of this many minutes (one of `1`, `5`, `10`, `15`, `30`, `60`; default `1`)
- `selfApproval` (boolean): Approvers may approve their own work
- `tax` (number): Tax rate of hourly invoice lines (default 19)
- `trafficLight` (object): The time traffic light: booked time as a share of the time worked or of the target
  - `denominator` (string): What it is compared with: time worked so far or the target of the day (one of `worked`, `target`)
  - `greenAt` (integer): Green from this percentage
  - `numerator` (string): What booked time counts (one of `all`, `billable`, `nonBillable`)
  - `yellowAt` (integer): Yellow from this percentage (else red)
- `unit` (string): Unit of hourly invoice lines (default Std)
- `version` (integer (int64)): The configuration's version; send it back on save

Example 200 answer:

```json
{
  "activityDefaults": {
    "call": {
      "billing": "",
      "minMinutes": 15,
      "minSeconds": 60,
      "roundMinutes": 15,
      "timeKind": "remote"
    },
    "remote_session": {
      "billing": "",
      "minMinutes": 15,
      "minSeconds": 120,
      "roundMinutes": 5,
      "timeKind": "remote"
    }
  },
  "billingTypes": [
    {
      "flags": [
        "default"
      ],
      "key": "hourly",
      "label": "Nach Aufwand"
    },
    {
      "flags": [
        "flatRate"
      ],
      "key": "flat",
      "label": "Pauschale"
    },
    {
      "flags": [
        "quota"
      ],
      "key": "quota",
      "label": "Kontingent"
    },
    {
      "flags": [
        "nonBillable"
      ],
      "key": "none",
      "label": "Nicht verrechenbar"
    }
  ],
  "kinds": [
    {
      "flags": [
        "internal"
      ],
      "key": "internal",
      "label": "Intern"
    },
    {
      "flags": [
        "default"
      ],
      "key": "remote",
      "label": "Remote"
    },
    {
      "flags": [
        "allowsTravel"
      ],
      "key": "onsite",
      "label": "Vor Ort"
    }
  ],
  "rounding": {
    "direction": "up",
    "stepMinutes": 5
  },
  "selfApproval": false,
  "tax": 19,
  "trafficLight": {
    "denominator": "worked",
    "greenAt": 80,
    "numerator": "all",
    "yellowAt": 50
  },
  "unit": "Std",
  "version": 3
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/work-entry-settings' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"activityDefaults":{"call":{"billing":"","minMinutes":15,"minSeconds":60,"roundMinutes":15,"timeKind":"remote"},"remote_session":{"billing":"","minMinutes":15,"minSeconds":120,"roundMinutes":5,"timeKind":"remote"}},"billingTypes":[{"flags":["default"],"key":"hourly","label":"Nach Aufwand"},{"flags":["flatRate"],"key":"flat","label":"Pauschale"},{"flags":["quota"],"key":"quota","label":"Kontingent"},{"flags":["nonBillable"],"key":"none","label":"Nicht verrechenbar"}],"kinds":[{"flags":["internal"],"key":"internal","label":"Intern"},{"flags":["default"],"key":"remote","label":"Remote"},{"flags":["allowsTravel"],"key":"onsite","label":"Vor Ort"}],"rounding":{"direction":"up","stepMinutes":5},"selfApproval":false,"tax":19,"trafficLight":{"denominator":"worked","greenAt":80,"numerator":"all","yellowAt":50},"unit":"Std","version":3}'
```

## A customer's active contracts for the booking form (tenant:access)

`GET /api/hr/v1/work-contracts`

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

The customer's contracts in trade that run on `date` (default today); empty without trade.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `customerId` | query | string | yes | The customer's masterdata address id |
| `date` | query | string (date) |  |  |

### Responses

- **200** Contracts (`application/json`)
- **400** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of object, required): Active contracts of the customer
  - `active` (boolean): The contract is active
  - `customerId` (string): Customer (masterdata address id)
  - `id` (string): Id of the trade contract
  - `number` (string): Number of the contract
  - `quota` (boolean): A quota contract (work on it consumes its contingent)
  - `title` (string): Title of the contract

Example 200 answer:

```json
{
  "items": [
    {
      "active": true,
      "customerId": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
      "id": "7a9c1e3a-5c7e-4a9c-8e3a-5c7e9a1c3e52",
      "number": "WV-2026-0007",
      "quota": true,
      "title": "Wartungsvertrag Netzwerk und WLAN"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/work-contracts?customerId=string' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Work billing

## Open billing units outside projects and recent batches (hr:work:billing)

`GET /api/hr/v1/work-billing`

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

The contracts and customers with approved billable work outside projects that no batch holds (`openEntries`,
`openMinutes` – hourly minutes only) or with entries waiting for approval (`unapproved`), and the newest 100
contract and customer batches.

### Responses

- **200** Units and batches (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `batches` (array of WorkBatch): The newest 100 contract and customer batches
  - `billableMinutes` (integer): Hourly minutes (flat-rate entries are not counted)
  - `contractId` (string): Trade contract of contract batches
  - `createdAt` (string (date-time)): When the batch was created
  - `customerId` (string): Customer (masterdata address id) of contract and customer batches
  - `entryCount` (integer): Number of entries in the batch
  - `grossTotal` (number, nullable): Gross total of trade's invoice
  - `id` (string (uuid)): Id of the batch
  - `invoiceNumber` (string): Given by trade on release
  - `invoicedOn` (string (date), nullable): Date of the invoice (YYYY-MM-DD) once released
  - `label` (string): Names the unit on the invoice and in lists
  - `lastError` (string): Why the last send failed (German)
  - `netAmount` (number): Net amount HR computed
  - `netTotal` (number, nullable): Net total of trade's invoice
  - `periodFrom` (string (date)): First work day of the period (YYYY-MM-DD)
  - `periodTo` (string (date)): Last work day of the period (YYYY-MM-DD)
  - `projectRef` (string): Reference of the project (project batches)
  - `requestedAt` (string (date-time)): When the batch was requested
  - `requestedBy` (string): Who requested it (e-mail)
  - `scope` (string): Billing unit of the batch (one of `project`, `contract`, `customer`)
  - `sendAttempts` (integer): Attempts to send the draft to trade
  - `state` (string): requested → drafted (trade holds the draft) → invoiced; discarded: the draft was deleted, the entries are free again (one of `requested`, `drafted`, `invoiced`, `discarded`)
  - `tradeTransactionId` (string): Id of trade's document
  - `updatedAt` (string (date-time)): When the batch was last changed
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `units` (array of object): Contracts and customers with open billable work outside projects
  - `contractId` (string): Trade contract (contract units)
  - `contractNumber` (string): Number of the contract
  - `contractTitle` (string): Title of the contract
  - `customerId` (string): Customer (masterdata address id)
  - `customerName` (string): Name of the customer
  - `firstOpen` (string): First work day (YYYY-MM-DD) of the approved open entries; empty when the unit has only unapproved ones
  - `lastOpen` (string): Last work day (YYYY-MM-DD) of the approved open entries; empty when the unit has only unapproved ones
  - `openEntries` (integer): Approved billable entries no batch holds
  - `openMinutes` (integer): Hourly minutes of those entries
  - `scope` (string): Billing unit (one of `contract`, `customer`)
  - `unapproved` (integer): Entries waiting for approval

Example 200 answer:

```json
{
  "batches": [
    {
      "billableMinutes": 270,
      "createdAt": "2026-11-03T10:15:00Z",
      "customerId": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
      "entryCount": 2,
      "id": "1f3b5d7f-9b1d-4f3b-8d7f-9b1d3f5b7d61",
      "label": "Kanzlei Hofmann \u0026 Partner",
      "netAmount": 427.5,
      "periodFrom": "2026-10-01",
      "periodTo": "2026-10-31",
      "requestedAt": "2026-11-03T10:15:00Z",
      "requestedBy": "christina.adler@muster-it.example",
      "scope": "customer",
      "sendAttempts": 1,
      "state": "drafted",
      "tradeTransactionId": "3b5d7f9b-1d3f-4b5d-9f9b-1d3f5b7d9f62",
      "updatedAt": "2026-11-03T10:15:04Z",
      "version": 2
    }
  ],
  "units": [
    {
      "customerId": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
      "customerName": "Kanzlei Hofmann \u0026 Partner",
      "firstOpen": "2026-11-02",
      "lastOpen": "2026-11-17",
      "openEntries": 5,
      "openMinutes": 225,
      "scope": "customer",
      "unapproved": 1
    },
    {
      "contractId": "7a9c1e3a-5c7e-4a9c-8e3a-5c7e9a1c3e52",
      "contractNumber": "WV-2026-0007",
      "contractTitle": "Wartungsvertrag Netzwerk und WLAN",
      "customerId": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
      "customerName": "Alpenhotel Seeblick GmbH",
      "firstOpen": "2026-11-04",
      "lastOpen": "2026-11-16",
      "openEntries": 2,
      "openMinutes": 0,
      "scope": "contract",
      "unapproved": 0
    }
  ]
}
```

### Example request

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

## Batches of every unit, newest first (hr:work:billing)

`GET /api/hr/v1/work-batches`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer |  | 1–200; another value is a 400 invalid. (default `50`; max 200) |
| `offset` | query | integer |  | (default `0`) |

### Responses

- **200** Batches (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of WorkBatch, required): Batches of this page
  - `billableMinutes` (integer): Hourly minutes (flat-rate entries are not counted)
  - `contractId` (string): Trade contract of contract batches
  - `createdAt` (string (date-time)): When the batch was created
  - `customerId` (string): Customer (masterdata address id) of contract and customer batches
  - `entryCount` (integer): Number of entries in the batch
  - `grossTotal` (number, nullable): Gross total of trade's invoice
  - `id` (string (uuid)): Id of the batch
  - `invoiceNumber` (string): Given by trade on release
  - `invoicedOn` (string (date), nullable): Date of the invoice (YYYY-MM-DD) once released
  - `label` (string): Names the unit on the invoice and in lists
  - `lastError` (string): Why the last send failed (German)
  - `netAmount` (number): Net amount HR computed
  - `netTotal` (number, nullable): Net total of trade's invoice
  - `periodFrom` (string (date)): First work day of the period (YYYY-MM-DD)
  - `periodTo` (string (date)): Last work day of the period (YYYY-MM-DD)
  - `projectRef` (string): Reference of the project (project batches)
  - `requestedAt` (string (date-time)): When the batch was requested
  - `requestedBy` (string): Who requested it (e-mail)
  - `scope` (string): Billing unit of the batch (one of `project`, `contract`, `customer`)
  - `sendAttempts` (integer): Attempts to send the draft to trade
  - `state` (string): requested → drafted (trade holds the draft) → invoiced; discarded: the draft was deleted, the entries are free again (one of `requested`, `drafted`, `invoiced`, `discarded`)
  - `tradeTransactionId` (string): Id of trade's document
  - `updatedAt` (string (date-time)): When the batch was last changed
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `total` (integer): Number of all batches

Example 200 answer:

```json
{
  "items": [
    {
      "billableMinutes": 270,
      "createdAt": "2026-11-03T10:15:00Z",
      "customerId": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
      "entryCount": 2,
      "id": "1f3b5d7f-9b1d-4f3b-8d7f-9b1d3f5b7d61",
      "label": "Kanzlei Hofmann \u0026 Partner",
      "netAmount": 427.5,
      "periodFrom": "2026-10-01",
      "periodTo": "2026-10-31",
      "requestedAt": "2026-11-03T10:15:00Z",
      "requestedBy": "christina.adler@muster-it.example",
      "scope": "customer",
      "sendAttempts": 1,
      "state": "drafted",
      "tradeTransactionId": "3b5d7f9b-1d3f-4b5d-9f9b-1d3f5b7d9f62",
      "updatedAt": "2026-11-03T10:15:04Z",
      "version": 2
    },
    {
      "billableMinutes": 180,
      "createdAt": "2026-10-02T09:00:00Z",
      "customerId": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
      "entryCount": 4,
      "grossTotal": 339.15,
      "id": "5d7f9b1d-3f5b-4d7f-8b1d-3f5b7d9f1b63",
      "invoiceNumber": "RE-2026-0418",
      "invoicedOn": "2026-10-05",
      "label": "Kanzlei Hofmann \u0026 Partner",
      "netAmount": 285,
      "netTotal": 285,
      "periodFrom": "2026-09-01",
      "periodTo": "2026-09-30",
      "requestedAt": "2026-10-02T09:00:00Z",
      "requestedBy": "christina.adler@muster-it.example",
      "scope": "customer",
      "sendAttempts": 1,
      "state": "invoiced",
      "tradeTransactionId": "7f9b1d3f-5b7d-4f9b-9d3f-5b7d9f1b3d64",
      "updatedAt": "2026-10-05T11:30:00Z",
      "version": 4
    }
  ],
  "total": 2
}
```

### Example request

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

## Bill a unit's approved work in a period (hr:work:billing)

`POST /api/hr/v1/work-batches`

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

Bills the approved entries of a project (`scope: project`, `projectRef`; the customer is that of the project's
work, `customerId` picks one when it bills several), a contract outside projects (`contract`, `customerId`,
`contractId`) or a customer outside projects and contracts (`customer`, `customerId`) whose work date lies in
`from`–`to`. Hourly entries are priced with the rate table (project, contract, customer, default; a rate for the
entry's kind before one for all kinds; the newest `validFrom` on or before the work date), flat-rate entries
with an article at the article's sales price in masterdata (one line, quantity 1). With `dryRun=true` the answer
is the preview and nothing is stored. Otherwise the entries are put into the batch with their rate
(`billedRate`) and the invoice draft goes to trade at once (reference `hr:work-batch:<id>`); when trade does not
take it the batch stays `requested` with `lastError` and is sent again automatically. Refused (`400`, field
`from`, `hourlyRate` or `article`): no approved billable work, entries without rate, flat-rate articles without
price or gone, a sum of 0 or less. Without trade `503 trade_unavailable`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `dryRun` | query | boolean |  | Answer the preview only (default `false`) |

### Request body

`application/json` (required)

- `from` (string (date), required): First work day of the period (YYYY-MM-DD), inclusive
- `scope` (string, required): Billing unit: contract (customerId, contractId), customer (customerId) or project (projectRef) (one of `project`, `contract`, `customer`)
- `to` (string (date), required): Inclusive; at most a year after `from`
- `contractId` (string): The contract of a contract batch
- `customerId` (string): The customer (masterdata address id); for a project only when its work bills several
- `projectRef` (string): The project of a project batch

Example:

```json
{
  "customerId": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
  "from": "2026-10-01",
  "scope": "customer",
  "to": "2026-10-31"
}
```

### Responses

- **200** The preview (dryRun) (`application/json`)
- **201** The batch with what it bills (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **409** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 201 answer:

- `batch` (WorkBatch): One hourly invoice of a billing unit – a draft in trade until a person releases it there.
  - `billableMinutes` (integer): Hourly minutes (flat-rate entries are not counted)
  - `contractId` (string): Trade contract of contract batches
  - `createdAt` (string (date-time)): When the batch was created
  - `customerId` (string): Customer (masterdata address id) of contract and customer batches
  - `entryCount` (integer): Number of entries in the batch
  - `grossTotal` (number, nullable): Gross total of trade's invoice
  - `id` (string (uuid)): Id of the batch
  - `invoiceNumber` (string): Given by trade on release
  - `invoicedOn` (string (date), nullable): Date of the invoice (YYYY-MM-DD) once released
  - `label` (string): Names the unit on the invoice and in lists
  - `lastError` (string): Why the last send failed (German)
  - `netAmount` (number): Net amount HR computed
  - `netTotal` (number, nullable): Net total of trade's invoice
  - `periodFrom` (string (date)): First work day of the period (YYYY-MM-DD)
  - `periodTo` (string (date)): Last work day of the period (YYYY-MM-DD)
  - `projectRef` (string): Reference of the project (project batches)
  - `requestedAt` (string (date-time)): When the batch was requested
  - `requestedBy` (string): Who requested it (e-mail)
  - `scope` (string): Billing unit of the batch (one of `project`, `contract`, `customer`)
  - `sendAttempts` (integer): Attempts to send the draft to trade
  - `state` (string): requested → drafted (trade holds the draft) → invoiced; discarded: the draft was deleted, the entries are free again (one of `requested`, `drafted`, `invoiced`, `discarded`)
  - `tradeTransactionId` (string): Id of trade's document
  - `updatedAt` (string (date-time)): When the batch was last changed
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `billableMinutes` (integer): Billable minutes of the batch
- `flatWithoutArticle` (integer): Approved flat-rate entries without article (never billed)
- `lines` (array of object): The entries with their rate and net amount
  - `entry` (WorkEntry): A booked piece of work of an employee.
    - `approvedAt` (string (date-time), nullable): When the entry was approved
    - `approvedBy` (string): Who approved the entry (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
    - `article` (WorkArticleRef | null): Masterdata article a flat-rate entry is billed as
    - `batchId` (string (uuid), nullable): Billing batch the entry is billed in
    - `billableMinutes` (integer): Minutes billed
    - `billedRate` (number, nullable): Hourly rate (or article price) the entry was billed at
    - `billing` (string): Key of a billing type
    - `contract` (WorkContractRef | null): Trade contract that decides billing
    - `correctionOf` (string (uuid), nullable): The approved or billed entry this one corrects; its minutes are the difference (may be negative)
    - `createdAt` (string (date-time)): When the work entry was created
    - `createdBy` (string): Who booked the entry (e-mail)
    - `customer` (WorkCustomerRef | null): Customer the work is billed to
    - `description` (string): What was done
    - `durationSeconds` (integer): The exact length in seconds (the stopwatch's seconds, else `minutes` × 60)
    - `employeeId` (string (uuid)): Id of the employee
    - `employeeName` (string): Display name of the employee – only in `listApprovableWorkEntries`
    - `endedAt` (string (date-time), nullable): `null` for the running stopwatch and for an entry without a span
    - `id` (string (uuid)): Id of the work entry
    - `kind` (string): Key of a work kind (`getWorkEntrySettings`)
    - `km` (number): Kilometres travelled (kinds that allow travel)
    - `minutes` (integer): The length in minutes that sums and billing use (a correction's difference, may be negative; 0 for a stopwatch run that rounded to nothing)
    - `origin` (string): The call or appointment the time comes from: `comms:interaction:<id>` or `comms:calendar:<id>`; omitted for other work. Booked at most once per tenant (`409 already_booked`)
    - `project` (WorkProjectRef | null): Project the work counts for
    - `running` (boolean): The running stopwatch entry (start, no end)
    - `source` (string): How the entry was booked (one of `manual`, `stopwatch`, `interaction`, `calendar`, `correction`)
    - `startedAt` (string (date-time), nullable): `null` for an entry booked as a length only
    - `state` (string): suggested → confirmed → approved → billed (one of `suggested`, `confirmed`, `approved`, `billed`)
    - `subject` (string): What was worked on: `desk:item:<id>`, `forge:item:<id>`, `crm:activity:<id>`, a project `desk:project:<id>` / `forge:project:<id>`; empty for work on the customer only or internal work
    - `subjectLabel` (string): The subject's name at booking time (the origin's without a subject)
    - `travelMinutes` (integer): Travel time in minutes (kinds that allow travel)
    - `updatedAt` (string (date-time)): When the work entry was last changed
    - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
    - `workDate` (string (date)): The day the work counts for (the person's choice; with a start its day in the tenant's time zone)
  - `flat` (boolean): Billed as the entry's article (quantity 1)
  - `net` (number): Net amount of the line
  - `rate` (number, nullable): Hourly rate or article price; `null` none
- `missingPrice` (integer): Flat-rate entries whose article is gone
- `missingRate` (integer): Entries without hourly rate
- `netAmount` (number): Net amount of the batch
- `noPrice` (integer): Flat-rate entries whose article has no sales price

Example 201 answer:

```json
{
  "billableMinutes": 270,
  "flatWithoutArticle": 0,
  "lines": [
    {
      "entry": {
        "billableMinutes": 90,
        "billing": "hourly",
        "customer": {
          "id": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
          "name": "Kanzlei Hofmann \u0026 Partner"
        },
        "description": "Neuer Arbeitsplatz Büroleitung eingerichtet",
        "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
        "id": "3d5f7b9d-1f3b-4d5f-8b9d-1f3b5d7f9b65",
        "kind": "onsite",
        "minutes": 90,
        "source": "manual",
        "state": "approved",
        "subject": "desk:item:9f1b3d5f-7b9d-4f1b-8d5f-7b9d1f3b5d66",
        "subjectLabel": "#198 Arbeitsplatz Herr Pichler",
        "version": 2,
        "workDate": "2026-10-14"
      },
      "flat": false,
      "net": 142.5,
      "rate": 95
    },
    {
      "entry": {
        "billableMinutes": 180,
        "billing": "hourly",
        "customer": {
          "id": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
          "name": "Kanzlei Hofmann \u0026 Partner"
        },
        "description": "Datensicherung umgestellt und Rücksicherung getestet",
        "employeeId": "c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06",
        "id": "1b3d5f7b-9d1f-4b3d-9f5b-9d1f3b5d7f67",
        "kind": "remote",
        "minutes": 180,
        "source": "manual",
        "state": "approved",
        "subject": "desk:item:3f5b7d9f-1b3d-4f5b-9d9f-1b3d5f7b9d68",
        "subjectLabel": "#205 Backup-Umstellung",
        "version": 2,
        "workDate": "2026-10-22"
      },
      "flat": false,
      "net": 285,
      "rate": 95
    }
  ],
  "missingPrice": 0,
  "missingRate": 0,
  "netAmount": 427.5,
  "noPrice": 0
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/work-batches' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"customerId":"1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50","from":"2026-10-01","scope":"customer","to":"2026-10-31"}'
```

## Send a requested batch to trade again at once (hr:work:billing)

`POST /api/hr/v1/work-batches/{id}/send`

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

Only a `requested` batch (`409 batch_state`); without trade `503 trade_unavailable`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The batch after the attempt (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 200 answer:

- `billableMinutes` (integer): Hourly minutes (flat-rate entries are not counted)
- `contractId` (string): Trade contract of contract batches
- `createdAt` (string (date-time)): When the batch was created
- `customerId` (string): Customer (masterdata address id) of contract and customer batches
- `entryCount` (integer): Number of entries in the batch
- `grossTotal` (number, nullable): Gross total of trade's invoice
- `id` (string (uuid)): Id of the batch
- `invoiceNumber` (string): Given by trade on release
- `invoicedOn` (string (date), nullable): Date of the invoice (YYYY-MM-DD) once released
- `label` (string): Names the unit on the invoice and in lists
- `lastError` (string): Why the last send failed (German)
- `netAmount` (number): Net amount HR computed
- `netTotal` (number, nullable): Net total of trade's invoice
- `periodFrom` (string (date)): First work day of the period (YYYY-MM-DD)
- `periodTo` (string (date)): Last work day of the period (YYYY-MM-DD)
- `projectRef` (string): Reference of the project (project batches)
- `requestedAt` (string (date-time)): When the batch was requested
- `requestedBy` (string): Who requested it (e-mail)
- `scope` (string): Billing unit of the batch (one of `project`, `contract`, `customer`)
- `sendAttempts` (integer): Attempts to send the draft to trade
- `state` (string): requested → drafted (trade holds the draft) → invoiced; discarded: the draft was deleted, the entries are free again (one of `requested`, `drafted`, `invoiced`, `discarded`)
- `tradeTransactionId` (string): Id of trade's document
- `updatedAt` (string (date-time)): When the batch was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "billableMinutes": 270,
  "createdAt": "2026-11-03T10:15:00Z",
  "customerId": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
  "entryCount": 2,
  "grossTotal": null,
  "id": "1f3b5d7f-9b1d-4f3b-8d7f-9b1d3f5b7d61",
  "invoiceNumber": "",
  "invoicedOn": null,
  "label": "Kanzlei Hofmann \u0026 Partner",
  "lastError": "",
  "netAmount": 427.5,
  "netTotal": null,
  "periodFrom": "2026-10-01",
  "periodTo": "2026-10-31",
  "requestedAt": "2026-11-03T10:15:00Z",
  "requestedBy": "christina.adler@muster-it.example",
  "scope": "customer",
  "sendAttempts": 1,
  "state": "drafted",
  "tradeTransactionId": "3b5d7f9b-1d3f-4b5d-9f9b-1d3f5b7d9f62",
  "updatedAt": "2026-11-03T10:15:04Z",
  "version": 2
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/work-batches/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/send' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Take back a batch trade has not taken yet (hr:work:billing)

`POST /api/hr/v1/work-batches/{id}/withdraw`

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

A `requested` batch without trade document is discarded and its entries are free for the next batch. Once trade
holds the draft (`409 batch_state`), discard the draft in trade instead.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The discarded batch (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `billableMinutes` (integer): Hourly minutes (flat-rate entries are not counted)
- `contractId` (string): Trade contract of contract batches
- `createdAt` (string (date-time)): When the batch was created
- `customerId` (string): Customer (masterdata address id) of contract and customer batches
- `entryCount` (integer): Number of entries in the batch
- `grossTotal` (number, nullable): Gross total of trade's invoice
- `id` (string (uuid)): Id of the batch
- `invoiceNumber` (string): Given by trade on release
- `invoicedOn` (string (date), nullable): Date of the invoice (YYYY-MM-DD) once released
- `label` (string): Names the unit on the invoice and in lists
- `lastError` (string): Why the last send failed (German)
- `netAmount` (number): Net amount HR computed
- `netTotal` (number, nullable): Net total of trade's invoice
- `periodFrom` (string (date)): First work day of the period (YYYY-MM-DD)
- `periodTo` (string (date)): Last work day of the period (YYYY-MM-DD)
- `projectRef` (string): Reference of the project (project batches)
- `requestedAt` (string (date-time)): When the batch was requested
- `requestedBy` (string): Who requested it (e-mail)
- `scope` (string): Billing unit of the batch (one of `project`, `contract`, `customer`)
- `sendAttempts` (integer): Attempts to send the draft to trade
- `state` (string): requested → drafted (trade holds the draft) → invoiced; discarded: the draft was deleted, the entries are free again (one of `requested`, `drafted`, `invoiced`, `discarded`)
- `tradeTransactionId` (string): Id of trade's document
- `updatedAt` (string (date-time)): When the batch was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "billableMinutes": 270,
  "createdAt": "2026-11-03T10:15:00Z",
  "customerId": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
  "entryCount": 2,
  "grossTotal": null,
  "id": "1f3b5d7f-9b1d-4f3b-8d7f-9b1d3f5b7d61",
  "invoiceNumber": "",
  "invoicedOn": null,
  "label": "Kanzlei Hofmann \u0026 Partner",
  "lastError": "",
  "netAmount": 427.5,
  "netTotal": null,
  "periodFrom": "2026-10-01",
  "periodTo": "2026-10-31",
  "requestedAt": "2026-11-03T10:15:00Z",
  "requestedBy": "christina.adler@muster-it.example",
  "scope": "customer",
  "sendAttempts": 1,
  "state": "drafted",
  "tradeTransactionId": "3b5d7f9b-1d3f-4b5d-9f9b-1d3f5b7d9f62",
  "updatedAt": "2026-11-03T10:15:04Z",
  "version": 2
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/work-batches/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/withdraw' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## A project's open work and its batches (hr:work:billing)

`GET /api/hr/v1/projects/{ref}/work-batches`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | The project reference |

### Responses

- **200** Open work and batches, newest first (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of WorkBatch, required): Batches of the project, newest first
  - `billableMinutes` (integer): Hourly minutes (flat-rate entries are not counted)
  - `contractId` (string): Trade contract of contract batches
  - `createdAt` (string (date-time)): When the batch was created
  - `customerId` (string): Customer (masterdata address id) of contract and customer batches
  - `entryCount` (integer): Number of entries in the batch
  - `grossTotal` (number, nullable): Gross total of trade's invoice
  - `id` (string (uuid)): Id of the batch
  - `invoiceNumber` (string): Given by trade on release
  - `invoicedOn` (string (date), nullable): Date of the invoice (YYYY-MM-DD) once released
  - `label` (string): Names the unit on the invoice and in lists
  - `lastError` (string): Why the last send failed (German)
  - `netAmount` (number): Net amount HR computed
  - `netTotal` (number, nullable): Net total of trade's invoice
  - `periodFrom` (string (date)): First work day of the period (YYYY-MM-DD)
  - `periodTo` (string (date)): Last work day of the period (YYYY-MM-DD)
  - `projectRef` (string): Reference of the project (project batches)
  - `requestedAt` (string (date-time)): When the batch was requested
  - `requestedBy` (string): Who requested it (e-mail)
  - `scope` (string): Billing unit of the batch (one of `project`, `contract`, `customer`)
  - `sendAttempts` (integer): Attempts to send the draft to trade
  - `state` (string): requested → drafted (trade holds the draft) → invoiced; discarded: the draft was deleted, the entries are free again (one of `requested`, `drafted`, `invoiced`, `discarded`)
  - `tradeTransactionId` (string): Id of trade's document
  - `updatedAt` (string (date-time)): When the batch was last changed
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `openEntries` (integer): Approved billable entries no batch holds (any date)
- `openMinutes` (integer): Billable hourly minutes of the approved entries no batch holds
- `projectRef` (string): Reference of the project (e.g. desk:project:<id>)
- `unapproved` (integer): Confirmed entries waiting for approval

Example 200 answer:

```json
{
  "items": [
    {
      "billableMinutes": 1680,
      "createdAt": "2026-11-02T08:30:00Z",
      "customerId": "5f7b9d1f-3b5d-4f7b-8d1f-3b5d7f9b1d71",
      "entryCount": 14,
      "grossTotal": 3498.6,
      "id": "9b1d3f5b-7d9f-4b1d-9f5b-7d9f1b3d5f70",
      "invoiceNumber": "RE-2026-0431",
      "invoicedOn": "2026-11-04",
      "label": "PRJ-3 Netzwerkerneuerung Donau Maschinenbau",
      "netAmount": 2940,
      "netTotal": 2940,
      "periodFrom": "2026-10-01",
      "periodTo": "2026-10-31",
      "projectRef": "desk:project:5b7d9f1b-3d5f-4b7d-8f1b-3d5f7b9d1f69",
      "requestedAt": "2026-11-02T08:30:00Z",
      "requestedBy": "christina.adler@muster-it.example",
      "scope": "project",
      "sendAttempts": 1,
      "state": "invoiced",
      "tradeTransactionId": "1d3f5b7d-9f1b-4d3f-8b7d-9f1b3d5f7b72",
      "updatedAt": "2026-11-04T09:12:00Z",
      "version": 4
    }
  ],
  "openEntries": 3,
  "openMinutes": 330,
  "projectRef": "desk:project:5b7d9f1b-3d5f-4b7d-8f1b-3d5f7b9d1f69",
  "unapproved": 2
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/projects/desk:project:0b0b0b0b-1111-4222-8333-444444444444/work-batches' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## The rate table (hr:work:billing)

`GET /api/hr/v1/work-rates`

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

### Responses

- **200** Rates (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of WorkRate, required): Rows of the rate table
  - `scope` (string, required): What the rate applies to; a project rate comes first, then contract, customer, default (one of `default`, `customer`, `contract`, `project`)
  - `createdAt` (string (date-time), read-only): When the rate was created
  - `flatRateArticle` (WorkArticleRef | null): Only on project rows
  - `id` (string (uuid), read-only): Id of the rate
  - `kind` (string): Work kind key; empty for every kind
  - `label` (string): Name shown in the table
  - `rate` (number, nullable): Net hourly rate; `null` on a project row that names only the flat-rate article
  - `scopeRef` (string): The customer or contract id, the project reference (`desk:project:<id>`); empty for `default`
  - `updatedAt` (string (date-time), read-only): When the rate was last changed
  - `updatedBy` (string, read-only): Who last changed the rate (e-mail)
  - `validFrom` (string (date), nullable): First work date the rate applies to; `null` always
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "items": [
    {
      "createdAt": "2025-01-08T09:00:00Z",
      "id": "7d9f1b3d-5f7b-4d9f-9b3d-5f7b9d1f3b74",
      "kind": "",
      "label": "Standard",
      "rate": 105,
      "scope": "default",
      "scopeRef": "",
      "updatedAt": "2026-01-02T09:00:00Z",
      "updatedBy": "christina.adler@muster-it.example",
      "validFrom": null,
      "version": 2
    },
    {
      "createdAt": "2025-01-08T09:00:00Z",
      "id": "9f1b3d5f-7b9d-4f1b-9d5f-7b9d1f3b5d75",
      "kind": "onsite",
      "label": "Standard Vor Ort",
      "rate": 115,
      "scope": "default",
      "scopeRef": "",
      "updatedAt": "2025-01-08T09:00:00Z",
      "updatedBy": "christina.adler@muster-it.example",
      "validFrom": null,
      "version": 1
    },
    {
      "createdAt": "2025-12-15T10:00:00Z",
      "id": "3f5b7d9f-1b3d-4f5b-8d9f-1b3d5f7b9d73",
      "kind": "",
      "label": "Kanzlei Hofmann \u0026 Partner",
      "rate": 95,
      "scope": "customer",
      "scopeRef": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
      "updatedAt": "2025-12-15T10:00:00Z",
      "updatedBy": "christina.adler@muster-it.example",
      "validFrom": "2026-01-01",
      "version": 1
    },
    {
      "createdAt": "2026-09-15T14:00:00Z",
      "flatRateArticle": {
        "articleNumber": "DL-PAUSCH-VO",
        "id": "6b8d0f2b-4d6f-4b8d-9f2b-4d6f8b0d2f77",
        "name": "Pauschale Vor-Ort-Einsatz",
        "unit": "Stk"
      },
      "id": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f76",
      "kind": "",
      "label": "PRJ-3 Netzwerkerneuerung Donau Maschinenbau",
      "rate": null,
      "scope": "project",
      "scopeRef": "desk:project:5b7d9f1b-3d5f-4b7d-8f1b-3d5f7b9d1f69",
      "updatedAt": "2026-09-15T14:00:00Z",
      "updatedBy": "christina.adler@muster-it.example",
      "validFrom": null,
      "version": 1
    }
  ]
}
```

### Example request

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

## Add a rate (hr:work:billing)

`POST /api/hr/v1/work-rates`

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

A net hourly rate for the tenant (`default`), a customer, a contract or a project (`scopeRef`: its id or
reference), for one work kind or all (`kind` empty), from `validFrom` on. A project row may name only the
project's flat-rate article (`flatRateArticle.id`; HR stores its masterdata snapshot). One rate per scope,
reference, kind and start (`409 duplicate`).

### Request body

`application/json` (required)

- `scope` (string, required): What the rate applies to; a project rate comes first, then contract, customer, default (one of `default`, `customer`, `contract`, `project`)
- `createdAt` (string (date-time), read-only): When the rate was created
- `flatRateArticle` (WorkArticleRef | null): Only on project rows
- `id` (string (uuid), read-only): Id of the rate
- `kind` (string): Work kind key; empty for every kind
- `label` (string): Name shown in the table
- `rate` (number, nullable): Net hourly rate; `null` on a project row that names only the flat-rate article
- `scopeRef` (string): The customer or contract id, the project reference (`desk:project:<id>`); empty for `default`
- `updatedAt` (string (date-time), read-only): When the rate was last changed
- `updatedBy` (string, read-only): Who last changed the rate (e-mail)
- `validFrom` (string (date), nullable): First work date the rate applies to; `null` always
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example:

```json
{
  "createdAt": "2025-12-15T10:00:00Z",
  "id": "3f5b7d9f-1b3d-4f5b-8d9f-1b3d5f7b9d73",
  "kind": "",
  "label": "Kanzlei Hofmann \u0026 Partner",
  "rate": 95,
  "scope": "customer",
  "scopeRef": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
  "updatedAt": "2025-12-15T10:00:00Z",
  "updatedBy": "christina.adler@muster-it.example",
  "validFrom": "2026-01-01",
  "version": 1
}
```

### Responses

- **201** The rate (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **409** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 201 answer:

- `scope` (string, required): What the rate applies to; a project rate comes first, then contract, customer, default (one of `default`, `customer`, `contract`, `project`)
- `createdAt` (string (date-time), read-only): When the rate was created
- `flatRateArticle` (WorkArticleRef | null): Only on project rows
- `id` (string (uuid), read-only): Id of the rate
- `kind` (string): Work kind key; empty for every kind
- `label` (string): Name shown in the table
- `rate` (number, nullable): Net hourly rate; `null` on a project row that names only the flat-rate article
- `scopeRef` (string): The customer or contract id, the project reference (`desk:project:<id>`); empty for `default`
- `updatedAt` (string (date-time), read-only): When the rate was last changed
- `updatedBy` (string, read-only): Who last changed the rate (e-mail)
- `validFrom` (string (date), nullable): First work date the rate applies to; `null` always
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 201 answer:

```json
{
  "createdAt": "2025-12-15T10:00:00Z",
  "id": "3f5b7d9f-1b3d-4f5b-8d9f-1b3d5f7b9d73",
  "kind": "",
  "label": "Kanzlei Hofmann \u0026 Partner",
  "rate": 95,
  "scope": "customer",
  "scopeRef": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
  "updatedAt": "2025-12-15T10:00:00Z",
  "updatedBy": "christina.adler@muster-it.example",
  "validFrom": "2026-01-01",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/work-rates' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"createdAt":"2025-12-15T10:00:00Z","id":"3f5b7d9f-1b3d-4f5b-8d9f-1b3d5f7b9d73","kind":"","label":"Kanzlei Hofmann \u0026 Partner","rate":95,"scope":"customer","scopeRef":"1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50","updatedAt":"2025-12-15T10:00:00Z","updatedBy":"christina.adler@muster-it.example","validFrom":"2026-01-01","version":1}'
```

## Change a rate at its version (hr:work:billing)

`PUT /api/hr/v1/work-rates/{id}`

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

Batches keep the rate their entries were billed at. A stale `version` is `409 version_conflict`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `scope` (string, required): What the rate applies to; a project rate comes first, then contract, customer, default (one of `default`, `customer`, `contract`, `project`)
- `createdAt` (string (date-time), read-only): When the rate was created
- `flatRateArticle` (WorkArticleRef | null): Only on project rows
- `id` (string (uuid), read-only): Id of the rate
- `kind` (string): Work kind key; empty for every kind
- `label` (string): Name shown in the table
- `rate` (number, nullable): Net hourly rate; `null` on a project row that names only the flat-rate article
- `scopeRef` (string): The customer or contract id, the project reference (`desk:project:<id>`); empty for `default`
- `updatedAt` (string (date-time), read-only): When the rate was last changed
- `updatedBy` (string, read-only): Who last changed the rate (e-mail)
- `validFrom` (string (date), nullable): First work date the rate applies to; `null` always
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example:

```json
{
  "kind": "",
  "label": "Kanzlei Hofmann \u0026 Partner",
  "rate": 98,
  "scope": "customer",
  "scopeRef": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
  "validFrom": "2027-01-01",
  "version": 1
}
```

### Responses

- **200** The rate (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `scope` (string, required): What the rate applies to; a project rate comes first, then contract, customer, default (one of `default`, `customer`, `contract`, `project`)
- `createdAt` (string (date-time), read-only): When the rate was created
- `flatRateArticle` (WorkArticleRef | null): Only on project rows
- `id` (string (uuid), read-only): Id of the rate
- `kind` (string): Work kind key; empty for every kind
- `label` (string): Name shown in the table
- `rate` (number, nullable): Net hourly rate; `null` on a project row that names only the flat-rate article
- `scopeRef` (string): The customer or contract id, the project reference (`desk:project:<id>`); empty for `default`
- `updatedAt` (string (date-time), read-only): When the rate was last changed
- `updatedBy` (string, read-only): Who last changed the rate (e-mail)
- `validFrom` (string (date), nullable): First work date the rate applies to; `null` always
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "createdAt": "2025-12-15T10:00:00Z",
  "id": "3f5b7d9f-1b3d-4f5b-8d9f-1b3d5f7b9d73",
  "kind": "",
  "label": "Kanzlei Hofmann \u0026 Partner",
  "rate": 95,
  "scope": "customer",
  "scopeRef": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
  "updatedAt": "2025-12-15T10:00:00Z",
  "updatedBy": "christina.adler@muster-it.example",
  "validFrom": "2026-01-01",
  "version": 1
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/work-rates/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"kind":"","label":"Kanzlei Hofmann \u0026 Partner","rate":98,"scope":"customer","scopeRef":"1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50","validFrom":"2027-01-01","version":1}'
```

## Delete a rate (hr:work:billing)

`DELETE /api/hr/v1/work-rates/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **404** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/hr/v1/work-rates/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Recruiting

## Stages, application forms and what the caller may do (hr:recruiting:* or named on a posting)

`GET /api/hr/v1/recruiting/bootstrap`

Module: HR · operationId: `getRecruitingBootstrap` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

`canManage` is `hr:recruiting:manage`, `canReadAll` `hr:recruiting:read` or more; people named on the access
list of a posting (or heading its org unit) get `onAnyPosting`. `settings` only for `hr:recruiting:manage`.
Everybody else `403`.

### Responses

- **200** Configuration (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `canManage` (boolean): The caller holds hr:recruiting:manage
- `canReadAll` (boolean): The caller sees every posting
- `formTemplates` (array of ApplicationForm): Application form templates
  - `name` (string, required): Name of the form (max length 200)
  - `archived` (boolean): Archived: no longer offered for new data, kept for existing data
  - `createdAt` (string (date-time), read-only): When the application form was created
  - `description` (string): Description of the form (max length 2000)
  - `fields` (array of ApplicationFormField): Questions of the form after the fixed fields
    - `key` (string, required): Lower-case letters, digits, - or _; not a core field (first_name, last_name, email, phone, cover_letter, cv, attachments)
    - `kind` (string, required): Kind of answer (one of `text`, `longtext`, `number`, `date`, `bool`, `select`, `multiselect`, `url`, `file`)
    - `label` (string, required): Question text (max length 300)
    - `help` (string): Help text shown with the question (max length 1000)
    - `options` (array of object): Choices of select and multiselect questions
      - `label` (string): Display text of the choice
      - `value` (string): Stored value of the choice
    - `required` (boolean): An answer is required
  - `id` (string (uuid), read-only): Id of the application form
  - `updatedAt` (string (date-time), read-only): When the application form was last changed
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `onAnyPosting` (boolean): The caller is named on the access list of a posting
- `settings` (RecruitingSettings)
  - `career` (CareerSite): The tenant's public careers page on its host (`https://<subdomain>.<tenant host domain>/karriere`). Publishing it needs the tenant's subdomain (HR settings; `400` field `subdomain`) and a recruiting mailbox (`409 no_mailbox`).
    - `color` (string): Accent colour #rrggbb; empty for the default
    - `company` (string): The employer named on the page and in the postings' structured data (max length 200)
    - `enabled` (boolean): The page and the public API answer for the tenant's subdomain
    - `intro` (string): Markdown above the postings (max length 20000)
    - `origins` (array of string): Websites (https://host) that may embed the list of postings
    - `subdomain` (string, read-only): The tenant's subdomain (HR settings), the address of the page; empty while the tenant has none
    - `title` (string): Title of the careers page (max length 200)
    - `url` (string, read-only): The page; empty without a subdomain (or where the platform has no tenant hosts)
  - `consentText` (string): The data-protection consent applicants accept (max length 5000)
  - `consentVersion` (integer, read-only): Version of the consent text; counts its changes
  - `fromName` (string): Sender name and signature of applicant mail (max length 200)
  - `mailboxId` (string): The comms mailbox (consumer recruiting) applicant mail is sent from and answered to; empty: no applicant mail
  - `privacyUrl` (string): https link to the privacy notice
  - `retentionDays` (integer): Rejected, withdrawn and hired applications are deleted this long after they closed (default 183, AGG) (max 3650)
  - `talentPoolMonths` (integer): How long applications of people who agreed to the talent pool are kept (max 60)
  - `updatedAt` (string (date-time), read-only): When the settings were last changed
  - `updatedBy` (string, read-only): Who last changed the settings (e-mail)
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `stages` (array of RecruitingStage): Stages of the pipeline
  - `name` (string, required): Name of the stage (max length 100)
  - `phase` (string, required): Phase of the stage; rules look only at the phase (one of `new`, `active`, `hired`, `rejected`, `withdrawn`)
  - `archived` (boolean): Archived: no longer offered, kept for existing applications
  - `id` (string (uuid)): Empty for a new stage
  - `position` (integer, read-only): Position in the pipeline

Example 200 answer:

```json
{
  "canManage": true,
  "canReadAll": true,
  "formTemplates": [
    {
      "archived": false,
      "createdAt": "2026-09-01T09:00:00Z",
      "description": "Zusatzfragen für Stellen in Technik und Service Desk",
      "fields": [
        {
          "key": "fruehester_start",
          "kind": "date",
          "label": "Ab wann können Sie bei uns starten?",
          "required": true
        }
      ],
      "id": "3e5a7c9e-1a3c-4e5a-9c7e-1a3c5e7a9c90",
      "name": "Technische Stellen",
      "updatedAt": "2026-09-15T13:20:00Z",
      "version": 2
    }
  ],
  "onAnyPosting": true,
  "settings": {
    "consentVersion": 2,
    "fromName": "Muster IT-Systemhaus GmbH – Personal",
    "mailboxId": "5a7c9e1a-3c5e-4a7c-8e1a-3c5e7a9c1e91",
    "privacyUrl": "https://www.muster-it.example/datenschutz",
    "retentionDays": 183,
    "talentPoolMonths": 12,
    "version": 4
  },
  "stages": [
    {
      "archived": false,
      "id": "6c8e0a2c-4e6a-4c8e-8a2c-4e6a8c0e2a82",
      "name": "Eingegangen",
      "phase": "new",
      "position": 1
    },
    {
      "archived": false,
      "id": "8e0a2c4e-6a8c-4e0a-9c4e-6a8c0e2a4c83",
      "name": "In Prüfung",
      "phase": "active",
      "position": 2
    },
    {
      "archived": false,
      "id": "0a2c4e6a-8c0e-4a2c-8e6a-8c0e2a4c6e84",
      "name": "Interview",
      "phase": "active",
      "position": 3
    },
    {
      "archived": false,
      "id": "2c4e6a8c-0e2a-4c4e-9a8c-0e2a4c6e8a85",
      "name": "Angebot",
      "phase": "active",
      "position": 4
    },
    {
      "archived": false,
      "id": "4e6a8c0e-2a4c-4e6a-8c0e-2a4c6e8a0c86",
      "name": "Eingestellt",
      "phase": "hired",
      "position": 5
    },
    {
      "archived": false,
      "id": "6a8c0e2a-4c6e-4a8c-9e2a-4c6e8a0c2e87",
      "name": "Abgesagt",
      "phase": "rejected",
      "position": 6
    },
    {
      "archived": false,
      "id": "8c0e2a4c-6e8a-4c0e-8a4c-6e8a0c2e4a88",
      "name": "Zurückgezogen",
      "phase": "withdrawn",
      "position": 7
    }
  ]
}
```

### Example request

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

## Save retention, consent and the applicant mailbox (hr:recruiting:manage)

`PUT /api/hr/v1/recruiting/settings`

Module: HR · operationId: `setRecruitingSettings` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

A changed `consentText` gets a new `consentVersion`; applications store the version they accepted. Publishing the careers page (`career.enabled`) needs the tenant's subdomain (`400`, field `subdomain`) and a mailbox (`409 no_mailbox`).

### Request body

`application/json` (required)

- `career` (CareerSite): The tenant's public careers page on its host (`https://<subdomain>.<tenant host domain>/karriere`). Publishing it needs the tenant's subdomain (HR settings; `400` field `subdomain`) and a recruiting mailbox (`409 no_mailbox`).
  - `color` (string): Accent colour #rrggbb; empty for the default
  - `company` (string): The employer named on the page and in the postings' structured data (max length 200)
  - `enabled` (boolean): The page and the public API answer for the tenant's subdomain
  - `intro` (string): Markdown above the postings (max length 20000)
  - `origins` (array of string): Websites (https://host) that may embed the list of postings
  - `subdomain` (string, read-only): The tenant's subdomain (HR settings), the address of the page; empty while the tenant has none
  - `title` (string): Title of the careers page (max length 200)
  - `url` (string, read-only): The page; empty without a subdomain (or where the platform has no tenant hosts)
- `consentText` (string): The data-protection consent applicants accept (max length 5000)
- `consentVersion` (integer, read-only): Version of the consent text; counts its changes
- `fromName` (string): Sender name and signature of applicant mail (max length 200)
- `mailboxId` (string): The comms mailbox (consumer recruiting) applicant mail is sent from and answered to; empty: no applicant mail
- `privacyUrl` (string): https link to the privacy notice
- `retentionDays` (integer): Rejected, withdrawn and hired applications are deleted this long after they closed (default 183, AGG) (max 3650)
- `talentPoolMonths` (integer): How long applications of people who agreed to the talent pool are kept (max 60)
- `updatedAt` (string (date-time), read-only): When the settings were last changed
- `updatedBy` (string, read-only): Who last changed the settings (e-mail)
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example:

```json
{
  "career": {
    "color": "#0a7c66",
    "company": "Muster IT-Systemhaus GmbH",
    "enabled": true,
    "intro": "Wir betreuen mit rund 25 Kolleginnen und Kollegen die IT von Mittelstand, Praxen und Kanzleien in Ostbayern.",
    "origins": [
      "https://www.muster-it.example"
    ],
    "subdomain": "demo",
    "title": "Karriere bei Muster IT",
    "url": "https://demo.on.example.com/karriere"
  },
  "consentText": "Ich bin einverstanden, dass die Muster IT-Systemhaus GmbH meine Angaben zur Bearbeitung meiner Bewerbung speichert und verarbeitet.",
  "consentVersion": 2,
  "fromName": "Muster IT-Systemhaus GmbH – Personal",
  "mailboxId": "5a7c9e1a-3c5e-4a7c-8e1a-3c5e7a9c1e91",
  "privacyUrl": "https://www.muster-it.example/datenschutz",
  "retentionDays": 183,
  "talentPoolMonths": 12,
  "updatedAt": "2026-10-20T08:45:00Z",
  "updatedBy": "clara.becker@muster-it.example",
  "version": 4
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `career` (CareerSite): The tenant's public careers page on its host (`https://<subdomain>.<tenant host domain>/karriere`). Publishing it needs the tenant's subdomain (HR settings; `400` field `subdomain`) and a recruiting mailbox (`409 no_mailbox`).
  - `color` (string): Accent colour #rrggbb; empty for the default
  - `company` (string): The employer named on the page and in the postings' structured data (max length 200)
  - `enabled` (boolean): The page and the public API answer for the tenant's subdomain
  - `intro` (string): Markdown above the postings (max length 20000)
  - `origins` (array of string): Websites (https://host) that may embed the list of postings
  - `subdomain` (string, read-only): The tenant's subdomain (HR settings), the address of the page; empty while the tenant has none
  - `title` (string): Title of the careers page (max length 200)
  - `url` (string, read-only): The page; empty without a subdomain (or where the platform has no tenant hosts)
- `consentText` (string): The data-protection consent applicants accept (max length 5000)
- `consentVersion` (integer, read-only): Version of the consent text; counts its changes
- `fromName` (string): Sender name and signature of applicant mail (max length 200)
- `mailboxId` (string): The comms mailbox (consumer recruiting) applicant mail is sent from and answered to; empty: no applicant mail
- `privacyUrl` (string): https link to the privacy notice
- `retentionDays` (integer): Rejected, withdrawn and hired applications are deleted this long after they closed (default 183, AGG) (max 3650)
- `talentPoolMonths` (integer): How long applications of people who agreed to the talent pool are kept (max 60)
- `updatedAt` (string (date-time), read-only): When the settings were last changed
- `updatedBy` (string, read-only): Who last changed the settings (e-mail)
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "career": {
    "color": "#0a7c66",
    "company": "Muster IT-Systemhaus GmbH",
    "enabled": true,
    "intro": "Wir betreuen mit rund 25 Kolleginnen und Kollegen die IT von Mittelstand, Praxen und Kanzleien in Ostbayern.",
    "origins": [
      "https://www.muster-it.example"
    ],
    "subdomain": "demo",
    "title": "Karriere bei Muster IT",
    "url": "https://demo.on.example.com/karriere"
  },
  "consentText": "Ich bin einverstanden, dass die Muster IT-Systemhaus GmbH meine Angaben zur Bearbeitung meiner Bewerbung speichert und verarbeitet.",
  "consentVersion": 2,
  "fromName": "Muster IT-Systemhaus GmbH – Personal",
  "mailboxId": "5a7c9e1a-3c5e-4a7c-8e1a-3c5e7a9c1e91",
  "privacyUrl": "https://www.muster-it.example/datenschutz",
  "retentionDays": 183,
  "talentPoolMonths": 12,
  "updatedAt": "2026-10-20T08:45:00Z",
  "updatedBy": "clara.becker@muster-it.example",
  "version": 4
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/recruiting/settings' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"career":{"color":"#0a7c66","company":"Muster IT-Systemhaus GmbH","enabled":true,"intro":"Wir betreuen mit rund 25 Kolleginnen und Kollegen die IT von Mittelstand, Praxen und Kanzleien in Ostbayern.","origins":["https://www.muster-it.example"],"subdomain":"demo","title":"Karriere bei Muster IT","url":"https://demo.on.example.com/karriere"},"consentText":"Ich bin einverstanden, dass die Muster IT-Systemhaus GmbH meine Angaben zur Bearbeitung meiner Bewerbung speichert und verarbeitet.","consentVersion":2,"fromName":"Muster IT-Systemhaus GmbH – Personal","mailboxId":"5a7c9e1a-3c5e-4a7c-8e1a-3c5e7a9c1e91","privacyUrl":"https://www.muster-it.example/datenschutz","retentionDays":183,"talentPoolMonths":12,"updatedAt":"2026-10-20T08:45:00Z","updatedBy":"clara.becker@muster-it.example","version":4}'
```

## Replace the pipeline (hr:recruiting:manage)

`PUT /api/hr/v1/recruiting/stages`

Module: HR · operationId: `setRecruitingStages` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

The stages in order. Every phase (`new`, `active`, `hired`, `rejected`, `withdrawn`) needs a stage that is not
archived; existing stages keep their phase and are archived, never removed. Stages without `id` are added.

### Request body

`application/json` (required)

- `stages` (array of RecruitingStage): The whole pipeline in order (at most 30); existing stages are archived, never left out (400)
  - `name` (string, required): Name of the stage (max length 100)
  - `phase` (string, required): Phase of the stage; rules look only at the phase (one of `new`, `active`, `hired`, `rejected`, `withdrawn`)
  - `archived` (boolean): Archived: no longer offered, kept for existing applications
  - `id` (string (uuid)): Empty for a new stage
  - `position` (integer, read-only): Position in the pipeline

Example:

```json
{
  "stages": [
    {
      "id": "6c8e0a2c-4e6a-4c8e-8a2c-4e6a8c0e2a82",
      "name": "Eingegangen",
      "phase": "new"
    },
    {
      "id": "8e0a2c4e-6a8c-4e0a-9c4e-6a8c0e2a4c83",
      "name": "In Prüfung",
      "phase": "active"
    },
    {
      "name": "Telefoninterview",
      "phase": "active"
    },
    {
      "id": "0a2c4e6a-8c0e-4a2c-8e6a-8c0e2a4c6e84",
      "name": "Fachgespräch",
      "phase": "active"
    },
    {
      "id": "2c4e6a8c-0e2a-4c4e-9a8c-0e2a4c6e8a85",
      "name": "Angebot",
      "phase": "active"
    },
    {
      "id": "4e6a8c0e-2a4c-4e6a-8c0e-2a4c6e8a0c86",
      "name": "Eingestellt",
      "phase": "hired"
    },
    {
      "id": "6a8c0e2a-4c6e-4a8c-9e2a-4c6e8a0c2e87",
      "name": "Abgesagt",
      "phase": "rejected"
    },
    {
      "id": "8c0e2a4c-6e8a-4c0e-8a4c-6e8a0c2e4a88",
      "name": "Zurückgezogen",
      "phase": "withdrawn"
    }
  ]
}
```

### Responses

- **200** The pipeline (`application/json`)
- **400** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of RecruitingStage, required): The saved pipeline
  - `name` (string, required): Name of the stage (max length 100)
  - `phase` (string, required): Phase of the stage; rules look only at the phase (one of `new`, `active`, `hired`, `rejected`, `withdrawn`)
  - `archived` (boolean): Archived: no longer offered, kept for existing applications
  - `id` (string (uuid)): Empty for a new stage
  - `position` (integer, read-only): Position in the pipeline

Example 200 answer:

```json
{
  "items": [
    {
      "archived": false,
      "id": "6c8e0a2c-4e6a-4c8e-8a2c-4e6a8c0e2a82",
      "name": "Eingegangen",
      "phase": "new",
      "position": 1
    },
    {
      "archived": false,
      "id": "8e0a2c4e-6a8c-4e0a-9c4e-6a8c0e2a4c83",
      "name": "In Prüfung",
      "phase": "active",
      "position": 2
    },
    {
      "archived": false,
      "id": "1e3a5c7e-9a1c-4e3a-9c5e-9a1c3e5a7c92",
      "name": "Telefoninterview",
      "phase": "active",
      "position": 3
    },
    {
      "archived": false,
      "id": "0a2c4e6a-8c0e-4a2c-8e6a-8c0e2a4c6e84",
      "name": "Fachgespräch",
      "phase": "active",
      "position": 4
    },
    {
      "archived": false,
      "id": "2c4e6a8c-0e2a-4c4e-9a8c-0e2a4c6e8a85",
      "name": "Angebot",
      "phase": "active",
      "position": 5
    },
    {
      "archived": false,
      "id": "4e6a8c0e-2a4c-4e6a-8c0e-2a4c6e8a0c86",
      "name": "Eingestellt",
      "phase": "hired",
      "position": 6
    },
    {
      "archived": false,
      "id": "6a8c0e2a-4c6e-4a8c-9e2a-4c6e8a0c2e87",
      "name": "Abgesagt",
      "phase": "rejected",
      "position": 7
    },
    {
      "archived": false,
      "id": "8c0e2a4c-6e8a-4c0e-8a4c-6e8a0c2e4a88",
      "name": "Zurückgezogen",
      "phase": "withdrawn",
      "position": 8
    }
  ]
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/recruiting/stages' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"stages":[{"id":"6c8e0a2c-4e6a-4c8e-8a2c-4e6a8c0e2a82","name":"Eingegangen","phase":"new"},{"id":"8e0a2c4e-6a8c-4e0a-9c4e-6a8c0e2a4c83","name":"In Prüfung","phase":"active"},{"name":"Telefoninterview","phase":"active"},{"id":"0a2c4e6a-8c0e-4a2c-8e6a-8c0e2a4c6e84","name":"Fachgespräch","phase":"active"},{"id":"2c4e6a8c-0e2a-4c4e-9a8c-0e2a4c6e8a85","name":"Angebot","phase":"active"},{"id":"4e6a8c0e-2a4c-4e6a-8c0e-2a4c6e8a0c86","name":"Eingestellt","phase":"hired"},{"id":"6a8c0e2a-4c6e-4a8c-9e2a-4c6e8a0c2e87","name":"Abgesagt","phase":"rejected"},{"id":"8c0e2a4c-6e8a-4c0e-8a4c-6e8a0c2e4a88","name":"Zurückgezogen","phase":"withdrawn"}]}'
```

## Create an application form (hr:recruiting:manage)

`POST /api/hr/v1/recruiting/form-templates`

Module: HR · operationId: `createApplicationForm` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Request body

`application/json` (required)

- `name` (string, required): Name of the form (max length 200)
- `archived` (boolean): Archived: no longer offered for new data, kept for existing data
- `createdAt` (string (date-time), read-only): When the application form was created
- `description` (string): Description of the form (max length 2000)
- `fields` (array of ApplicationFormField): Questions of the form after the fixed fields
  - `key` (string, required): Lower-case letters, digits, - or _; not a core field (first_name, last_name, email, phone, cover_letter, cv, attachments)
  - `kind` (string, required): Kind of answer (one of `text`, `longtext`, `number`, `date`, `bool`, `select`, `multiselect`, `url`, `file`)
  - `label` (string, required): Question text (max length 300)
  - `help` (string): Help text shown with the question (max length 1000)
  - `options` (array of object): Choices of select and multiselect questions
    - `label` (string): Display text of the choice
    - `value` (string): Stored value of the choice
  - `required` (boolean): An answer is required
- `id` (string (uuid), read-only): Id of the application form
- `updatedAt` (string (date-time), read-only): When the application form was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example:

```json
{
  "archived": false,
  "createdAt": "2026-09-01T09:00:00Z",
  "description": "Zusatzfragen für Stellen in Technik und Service Desk",
  "fields": [
    {
      "key": "fruehester_start",
      "kind": "date",
      "label": "Ab wann können Sie bei uns starten?",
      "required": true
    },
    {
      "key": "gehaltsvorstellung",
      "kind": "number",
      "label": "Ihre Gehaltsvorstellung (brutto pro Jahr)",
      "required": false
    },
    {
      "key": "zertifizierungen",
      "kind": "multiselect",
      "label": "Welche Microsoft-Zertifizierungen haben Sie?",
      "options": [
        {
          "label": "MS-102",
          "value": "ms_102"
        },
        {
          "label": "MD-102",
          "value": "md_102"
        },
        {
          "label": "AZ-104",
          "value": "az_104"
        }
      ],
      "required": false
    }
  ],
  "id": "3e5a7c9e-1a3c-4e5a-9c7e-1a3c5e7a9c90",
  "name": "Technische Stellen",
  "updatedAt": "2026-09-15T13:20:00Z",
  "version": 2
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)

Fields of the 201 answer:

- `name` (string, required): Name of the form (max length 200)
- `archived` (boolean): Archived: no longer offered for new data, kept for existing data
- `createdAt` (string (date-time), read-only): When the application form was created
- `description` (string): Description of the form (max length 2000)
- `fields` (array of ApplicationFormField): Questions of the form after the fixed fields
  - `key` (string, required): Lower-case letters, digits, - or _; not a core field (first_name, last_name, email, phone, cover_letter, cv, attachments)
  - `kind` (string, required): Kind of answer (one of `text`, `longtext`, `number`, `date`, `bool`, `select`, `multiselect`, `url`, `file`)
  - `label` (string, required): Question text (max length 300)
  - `help` (string): Help text shown with the question (max length 1000)
  - `options` (array of object): Choices of select and multiselect questions
    - `label` (string): Display text of the choice
    - `value` (string): Stored value of the choice
  - `required` (boolean): An answer is required
- `id` (string (uuid), read-only): Id of the application form
- `updatedAt` (string (date-time), read-only): When the application form was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 201 answer:

```json
{
  "archived": false,
  "createdAt": "2026-09-01T09:00:00Z",
  "description": "Zusatzfragen für Stellen in Technik und Service Desk",
  "fields": [
    {
      "key": "fruehester_start",
      "kind": "date",
      "label": "Ab wann können Sie bei uns starten?",
      "required": true
    },
    {
      "key": "gehaltsvorstellung",
      "kind": "number",
      "label": "Ihre Gehaltsvorstellung (brutto pro Jahr)",
      "required": false
    },
    {
      "key": "zertifizierungen",
      "kind": "multiselect",
      "label": "Welche Microsoft-Zertifizierungen haben Sie?",
      "options": [
        {
          "label": "MS-102",
          "value": "ms_102"
        },
        {
          "label": "MD-102",
          "value": "md_102"
        },
        {
          "label": "AZ-104",
          "value": "az_104"
        }
      ],
      "required": false
    }
  ],
  "id": "3e5a7c9e-1a3c-4e5a-9c7e-1a3c5e7a9c90",
  "name": "Technische Stellen",
  "updatedAt": "2026-09-15T13:20:00Z",
  "version": 2
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/recruiting/form-templates' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"archived":false,"createdAt":"2026-09-01T09:00:00Z","description":"Zusatzfragen für Stellen in Technik und Service Desk","fields":[{"key":"fruehester_start","kind":"date","label":"Ab wann können Sie bei uns starten?","required":true},{"key":"gehaltsvorstellung","kind":"number","label":"Ihre Gehaltsvorstellung (brutto pro Jahr)","required":false},{"key":"zertifizierungen","kind":"multiselect","label":"Welche Microsoft-Zertifizierungen haben Sie?","options":[{"label":"MS-102","value":"ms_102"},{"label":"MD-102","value":"md_102"},{"label":"AZ-104","value":"az_104"}],"required":false}],"id":"3e5a7c9e-1a3c-4e5a-9c7e-1a3c5e7a9c90","name":"Technische Stellen","updatedAt":"2026-09-15T13:20:00Z","version":2}'
```

## Change or archive an application form (hr:recruiting:manage)

`PUT /api/hr/v1/recruiting/form-templates/{id}`

Module: HR · operationId: `updateApplicationForm` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `name` (string, required): Name of the form (max length 200)
- `archived` (boolean): Archived: no longer offered for new data, kept for existing data
- `createdAt` (string (date-time), read-only): When the application form was created
- `description` (string): Description of the form (max length 2000)
- `fields` (array of ApplicationFormField): Questions of the form after the fixed fields
  - `key` (string, required): Lower-case letters, digits, - or _; not a core field (first_name, last_name, email, phone, cover_letter, cv, attachments)
  - `kind` (string, required): Kind of answer (one of `text`, `longtext`, `number`, `date`, `bool`, `select`, `multiselect`, `url`, `file`)
  - `label` (string, required): Question text (max length 300)
  - `help` (string): Help text shown with the question (max length 1000)
  - `options` (array of object): Choices of select and multiselect questions
    - `label` (string): Display text of the choice
    - `value` (string): Stored value of the choice
  - `required` (boolean): An answer is required
- `id` (string (uuid), read-only): Id of the application form
- `updatedAt` (string (date-time), read-only): When the application form was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example:

```json
{
  "archived": false,
  "createdAt": "2026-09-01T09:00:00Z",
  "description": "Zusatzfragen für Stellen in Technik und Service Desk",
  "fields": [
    {
      "key": "fruehester_start",
      "kind": "date",
      "label": "Ab wann können Sie bei uns starten?",
      "required": true
    },
    {
      "key": "gehaltsvorstellung",
      "kind": "number",
      "label": "Ihre Gehaltsvorstellung (brutto pro Jahr)",
      "required": false
    },
    {
      "key": "zertifizierungen",
      "kind": "multiselect",
      "label": "Welche Microsoft-Zertifizierungen haben Sie?",
      "options": [
        {
          "label": "MS-102",
          "value": "ms_102"
        },
        {
          "label": "MD-102",
          "value": "md_102"
        },
        {
          "label": "AZ-104",
          "value": "az_104"
        }
      ],
      "required": false
    }
  ],
  "id": "3e5a7c9e-1a3c-4e5a-9c7e-1a3c5e7a9c90",
  "name": "Technische Stellen",
  "updatedAt": "2026-09-15T13:20:00Z",
  "version": 2
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `name` (string, required): Name of the form (max length 200)
- `archived` (boolean): Archived: no longer offered for new data, kept for existing data
- `createdAt` (string (date-time), read-only): When the application form was created
- `description` (string): Description of the form (max length 2000)
- `fields` (array of ApplicationFormField): Questions of the form after the fixed fields
  - `key` (string, required): Lower-case letters, digits, - or _; not a core field (first_name, last_name, email, phone, cover_letter, cv, attachments)
  - `kind` (string, required): Kind of answer (one of `text`, `longtext`, `number`, `date`, `bool`, `select`, `multiselect`, `url`, `file`)
  - `label` (string, required): Question text (max length 300)
  - `help` (string): Help text shown with the question (max length 1000)
  - `options` (array of object): Choices of select and multiselect questions
    - `label` (string): Display text of the choice
    - `value` (string): Stored value of the choice
  - `required` (boolean): An answer is required
- `id` (string (uuid), read-only): Id of the application form
- `updatedAt` (string (date-time), read-only): When the application form was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "archived": false,
  "createdAt": "2026-09-01T09:00:00Z",
  "description": "Zusatzfragen für Stellen in Technik und Service Desk",
  "fields": [
    {
      "key": "fruehester_start",
      "kind": "date",
      "label": "Ab wann können Sie bei uns starten?",
      "required": true
    },
    {
      "key": "gehaltsvorstellung",
      "kind": "number",
      "label": "Ihre Gehaltsvorstellung (brutto pro Jahr)",
      "required": false
    },
    {
      "key": "zertifizierungen",
      "kind": "multiselect",
      "label": "Welche Microsoft-Zertifizierungen haben Sie?",
      "options": [
        {
          "label": "MS-102",
          "value": "ms_102"
        },
        {
          "label": "MD-102",
          "value": "md_102"
        },
        {
          "label": "AZ-104",
          "value": "az_104"
        }
      ],
      "required": false
    }
  ],
  "id": "3e5a7c9e-1a3c-4e5a-9c7e-1a3c5e7a9c90",
  "name": "Technische Stellen",
  "updatedAt": "2026-09-15T13:20:00Z",
  "version": 2
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/recruiting/form-templates/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"archived":false,"createdAt":"2026-09-01T09:00:00Z","description":"Zusatzfragen für Stellen in Technik und Service Desk","fields":[{"key":"fruehester_start","kind":"date","label":"Ab wann können Sie bei uns starten?","required":true},{"key":"gehaltsvorstellung","kind":"number","label":"Ihre Gehaltsvorstellung (brutto pro Jahr)","required":false},{"key":"zertifizierungen","kind":"multiselect","label":"Welche Microsoft-Zertifizierungen haben Sie?","options":[{"label":"MS-102","value":"ms_102"},{"label":"MD-102","value":"md_102"},{"label":"AZ-104","value":"az_104"}],"required":false}],"id":"3e5a7c9e-1a3c-4e5a-9c7e-1a3c5e7a9c90","name":"Technische Stellen","updatedAt":"2026-09-15T13:20:00Z","version":2}'
```

## Job postings the caller sees (tenant:access; hr:recruiting:* sees all, others the postings they are named on)

`GET /api/hr/v1/recruiting/postings`

Module: HR · operationId: `listJobPostings` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `status` | query | string |  | Without it every posting but archived ones (one of `draft`, `published`, `closed`, `archived`) |
| `q` | query | string |  | Searches title and location |
| `limit` | query | integer |  | 1–200; another value is a 400 invalid. (default `50`; max 200) |
| `offset` | query | integer |  | (default `0`) |

### Responses

- **200** A page of postings (`application/json`)

Fields of the 200 answer:

- `items` (array of JobPosting): Postings of this page
- `total` (integer): Number of all matching postings

Example 200 answer:

```json
{
  "items": [
    {
      "contactEmployeeId": "9b1d3f5a-7c9e-4b1d-8f3a-5c7e9b1d3f2e",
      "counts": {
        "active": 3,
        "new": 1
      },
      "createdAt": "2026-09-29T14:10:00Z",
      "createdBy": "tobias.hartl@muster-it.example",
      "employmentType": "full_time",
      "id": "4a6c8e0a-2c4e-4a6c-9e0a-2c4e6a8c0e81",
      "location": "Regensburg",
      "number": 1,
      "orgUnitId": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
      "publishedAt": "2026-10-01T07:00:00Z",
      "role": "manager",
      "salaryCurrency": "EUR",
      "salaryMax": 58000,
      "salaryMin": 48000,
      "salaryPeriod": "year",
      "startDate": "2027-01-01",
      "status": "published",
      "title": "Systemadministrator:in (m/w/d) Microsoft 365",
      "updatedAt": "2026-10-01T07:00:00Z",
      "version": 3,
      "workplace": "hybrid"
    },
    {
      "counts": {
        "active": 1,
        "new": 2
      },
      "createdAt": "2026-10-02T11:00:00Z",
      "createdBy": "andrea.peschke@muster-it.example",
      "employmentType": "full_time",
      "id": "6c8e0a2c-4e6a-4c8e-9a2c-4e6a8c0e2a93",
      "location": "Regensburg",
      "number": 2,
      "orgUnitId": "5a7c9e1a-3c5e-4a7c-9e1a-3c5e7a9c1e73",
      "publishedAt": "2026-10-05T07:00:00Z",
      "role": "viewer",
      "salaryCurrency": "EUR",
      "salaryMax": 46000,
      "salaryMin": 38000,
      "salaryPeriod": "year",
      "startDate": "2026-12-01",
      "status": "published",
      "title": "Vertriebsmitarbeiter:in Innendienst (m/w/d)",
      "updatedAt": "2026-10-05T07:00:00Z",
      "version": 2,
      "workplace": "onsite"
    }
  ],
  "total": 2
}
```

### Example request

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

## Create a draft posting (hr:recruiting:manage)

`POST /api/hr/v1/recruiting/postings`

Module: HR · operationId: `createJobPosting` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Request body

`application/json` (required)

- `employmentType` (string, required): Kind of employment (one of `full_time`, `part_time`, `mini_job`, `apprenticeship`, `internship`, `working_student`, `freelance`)
- `title` (string, required): Title of the posting (max length 300)
- `contactEmployeeId` (string (uuid)): Employee id of the contact person
- `description` (string): Markdown
- `formTemplateId` (string (uuid)): Id of the application form template
- `location` (string): Place of work (max length 300)
- `orgUnitId` (string (uuid)): Heads and deputies of the unit (and the units above it) review the posting
- `publishFrom` (string (date-time)): A published posting is shown on the careers site from then on (empty: at once)
- `publishUntil` (string (date-time)): A published posting is shown on the careers site until then (empty: until closed)
- `questions` (array of ApplicationFormField): Questions of this posting after those of its form template
  - `key` (string, required): Lower-case letters, digits, - or _; not a core field (first_name, last_name, email, phone, cover_letter, cv, attachments)
  - `kind` (string, required): Kind of answer (one of `text`, `longtext`, `number`, `date`, `bool`, `select`, `multiselect`, `url`, `file`)
  - `label` (string, required): Question text (max length 300)
  - `help` (string): Help text shown with the question (max length 1000)
  - `options` (array of object): Choices of select and multiselect questions
    - `label` (string): Display text of the choice
    - `value` (string): Stored value of the choice
  - `required` (boolean): An answer is required
- `salaryCurrency` (string): Currency of the salary (ISO 4217) (default `"EUR"`)
- `salaryMax` (integer (int64)): Upper end of the salary range
- `salaryMin` (integer (int64)): In the currency's main unit per period
- `salaryPeriod` (string): Period the salary refers to (one of `year`, `month`, `hour`; default `"year"`)
- `startDate` (string (date)): Start date (YYYY-MM-DD), empty for none
- `version` (integer): Version of the posting a change is based on
- `workplace` (string): Where the work is done (one of `onsite`, `hybrid`, `remote`; default `"onsite"`)

Example:

```json
{
  "contactEmployeeId": "9b1d3f5a-7c9e-4b1d-8f3a-5c7e9b1d3f2e",
  "description": "## Ihre Aufgaben\n- Betrieb und Weiterentwicklung der Microsoft-365-Umgebungen unserer Kunden (Exchange Online, Teams, SharePoint, Intune)\n- Migrationen von On-Premises-Servern in die Cloud",
  "employmentType": "full_time",
  "formTemplateId": "3e5a7c9e-1a3c-4e5a-9c7e-1a3c5e7a9c90",
  "location": "Regensburg",
  "orgUnitId": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
  "questions": [
    {
      "key": "powershell",
      "kind": "select",
      "label": "Wie schätzen Sie Ihre PowerShell-Kenntnisse ein?",
      "options": [
        {
          "label": "Grundlagen",
          "value": "grundlagen"
        },
        {
          "label": "Fortgeschritten",
          "value": "fortgeschritten"
        },
        {
          "label": "Experte",
          "value": "experte"
        }
      ],
      "required": false
    }
  ],
  "salaryCurrency": "EUR",
  "salaryMax": 58000,
  "salaryMin": 48000,
  "salaryPeriod": "year",
  "startDate": "2027-01-01",
  "title": "Systemadministrator:in (m/w/d) Microsoft 365",
  "workplace": "hybrid"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)

Fields of the 201 answer:

- `employmentType` (string, required): Kind of employment (one of `full_time`, `part_time`, `mini_job`, `apprenticeship`, `internship`, `working_student`, `freelance`)
- `title` (string, required): Title of the posting (max length 300)
- `contactEmployeeId` (string (uuid)): Employee id of the contact person
- `description` (string): Markdown
- `formTemplateId` (string (uuid)): Id of the application form template
- `location` (string): Place of work (max length 300)
- `orgUnitId` (string (uuid)): Heads and deputies of the unit (and the units above it) review the posting
- `publishFrom` (string (date-time)): A published posting is shown on the careers site from then on (empty: at once)
- `publishUntil` (string (date-time)): A published posting is shown on the careers site until then (empty: until closed)
- `questions` (array of ApplicationFormField): Questions of this posting after those of its form template
  - `key` (string, required): Lower-case letters, digits, - or _; not a core field (first_name, last_name, email, phone, cover_letter, cv, attachments)
  - `kind` (string, required): Kind of answer (one of `text`, `longtext`, `number`, `date`, `bool`, `select`, `multiselect`, `url`, `file`)
  - `label` (string, required): Question text (max length 300)
  - `help` (string): Help text shown with the question (max length 1000)
  - `options` (array of object): Choices of select and multiselect questions
    - `label` (string): Display text of the choice
    - `value` (string): Stored value of the choice
  - `required` (boolean): An answer is required
- `salaryCurrency` (string): Currency of the salary (ISO 4217) (default `"EUR"`)
- `salaryMax` (integer (int64)): Upper end of the salary range
- `salaryMin` (integer (int64)): In the currency's main unit per period
- `salaryPeriod` (string): Period the salary refers to (one of `year`, `month`, `hour`; default `"year"`)
- `startDate` (string (date)): Start date (YYYY-MM-DD), empty for none
- `version` (integer): Version of the posting a change is based on
- `workplace` (string): Where the work is done (one of `onsite`, `hybrid`, `remote`; default `"onsite"`)
- `access` (array of PostingAccessEntry): Only for managers of the posting
  - `role` (string, required): viewer reads; reviewer also notes, rates and sees interviews; manager moves, rejects, hires, mails, schedules and edits the posting (one of `viewer`, `reviewer`, `manager`)
  - `subjectId` (string (uuid), required): Id of the employee, group or org unit
  - `subjectKind` (string, required): Who is named: one employee, the members of a group or of an org unit (one of `employee`, `group`, `org_unit`)
  - `includeSubunits` (boolean): org_unit only: the members of the units below it too
  - `subjectName` (string, read-only): Name of the employee, group or org unit (filled on reads)
- `closedAt` (string (date-time)): When the posting was closed
- `counts` (object): Applications per phase
- `createdAt` (string (date-time)): When the posting was created
- `createdBy` (string): Who created the posting (e-mail of the caller)
- `id` (string (uuid)): Id of the posting
- `number` (integer): Number of the posting, unique in the tenant (careers site address)
- `publishedAt` (string (date-time)): When the posting was last published
- `role` (string): The caller's role on the posting (one of `viewer`, `reviewer`, `manager`)
- `status` (string): State of the posting (one of `draft`, `published`, `closed`, `archived`)
- `updatedAt` (string (date-time)): When the posting was last changed

Example 201 answer:

```json
{
  "access": [
    {
      "role": "reviewer",
      "subjectId": "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c",
      "subjectKind": "employee",
      "subjectName": "Jonas Bauer"
    },
    {
      "includeSubunits": true,
      "role": "viewer",
      "subjectId": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
      "subjectKind": "org_unit",
      "subjectName": "Technik"
    }
  ],
  "contactEmployeeId": "9b1d3f5a-7c9e-4b1d-8f3a-5c7e9b1d3f2e",
  "counts": {
    "active": 3,
    "hired": 0,
    "new": 1,
    "rejected": 0,
    "withdrawn": 0
  },
  "createdAt": "2026-09-29T14:10:00Z",
  "createdBy": "tobias.hartl@muster-it.example",
  "description": "## Ihre Aufgaben\n- Betrieb und Weiterentwicklung der Microsoft-365-Umgebungen unserer Kunden (Exchange Online, Teams, SharePoint, Intune)\n- Migrationen von On-Premises-Servern in die Cloud",
  "employmentType": "full_time",
  "formTemplateId": "3e5a7c9e-1a3c-4e5a-9c7e-1a3c5e7a9c90",
  "id": "4a6c8e0a-2c4e-4a6c-9e0a-2c4e6a8c0e81",
  "location": "Regensburg",
  "number": 1,
  "orgUnitId": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
  "publishedAt": "2026-10-01T07:00:00Z",
  "questions": [],
  "role": "manager",
  "salaryCurrency": "EUR",
  "salaryMax": 58000,
  "salaryMin": 48000,
  "salaryPeriod": "year",
  "startDate": "2027-01-01",
  "status": "published",
  "title": "Systemadministrator:in (m/w/d) Microsoft 365",
  "updatedAt": "2026-10-01T07:00:00Z",
  "version": 3,
  "workplace": "hybrid"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/recruiting/postings' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"contactEmployeeId":"9b1d3f5a-7c9e-4b1d-8f3a-5c7e9b1d3f2e","description":"## Ihre Aufgaben\n- Betrieb und Weiterentwicklung der Microsoft-365-Umgebungen unserer Kunden (Exchange Online, Teams, SharePoint, Intune)\n- Migrationen von On-Premises-Servern in die Cloud","employmentType":"full_time","formTemplateId":"3e5a7c9e-1a3c-4e5a-9c7e-1a3c5e7a9c90","location":"Regensburg","orgUnitId":"2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72","questions":[{"key":"powershell","kind":"select","label":"Wie schätzen Sie Ihre PowerShell-Kenntnisse ein?","options":[{"label":"Grundlagen","value":"grundlagen"},{"label":"Fortgeschritten","value":"fortgeschritten"},{"label":"Experte","value":"experte"}],"required":false}],"salaryCurrency":"EUR","salaryMax":58000,"salaryMin":48000,"salaryPeriod":"year","startDate":"2027-01-01","title":"Systemadministrator:in (m/w/d) Microsoft 365","workplace":"hybrid"}'
```

## One posting with the caller's role (its access list for managers of the posting)

`GET /api/hr/v1/recruiting/postings/{id}`

Module: HR · operationId: `getJobPosting` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The posting (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `employmentType` (string, required): Kind of employment (one of `full_time`, `part_time`, `mini_job`, `apprenticeship`, `internship`, `working_student`, `freelance`)
- `title` (string, required): Title of the posting (max length 300)
- `contactEmployeeId` (string (uuid)): Employee id of the contact person
- `description` (string): Markdown
- `formTemplateId` (string (uuid)): Id of the application form template
- `location` (string): Place of work (max length 300)
- `orgUnitId` (string (uuid)): Heads and deputies of the unit (and the units above it) review the posting
- `publishFrom` (string (date-time)): A published posting is shown on the careers site from then on (empty: at once)
- `publishUntil` (string (date-time)): A published posting is shown on the careers site until then (empty: until closed)
- `questions` (array of ApplicationFormField): Questions of this posting after those of its form template
  - `key` (string, required): Lower-case letters, digits, - or _; not a core field (first_name, last_name, email, phone, cover_letter, cv, attachments)
  - `kind` (string, required): Kind of answer (one of `text`, `longtext`, `number`, `date`, `bool`, `select`, `multiselect`, `url`, `file`)
  - `label` (string, required): Question text (max length 300)
  - `help` (string): Help text shown with the question (max length 1000)
  - `options` (array of object): Choices of select and multiselect questions
    - `label` (string): Display text of the choice
    - `value` (string): Stored value of the choice
  - `required` (boolean): An answer is required
- `salaryCurrency` (string): Currency of the salary (ISO 4217) (default `"EUR"`)
- `salaryMax` (integer (int64)): Upper end of the salary range
- `salaryMin` (integer (int64)): In the currency's main unit per period
- `salaryPeriod` (string): Period the salary refers to (one of `year`, `month`, `hour`; default `"year"`)
- `startDate` (string (date)): Start date (YYYY-MM-DD), empty for none
- `version` (integer): Version of the posting a change is based on
- `workplace` (string): Where the work is done (one of `onsite`, `hybrid`, `remote`; default `"onsite"`)
- `access` (array of PostingAccessEntry): Only for managers of the posting
  - `role` (string, required): viewer reads; reviewer also notes, rates and sees interviews; manager moves, rejects, hires, mails, schedules and edits the posting (one of `viewer`, `reviewer`, `manager`)
  - `subjectId` (string (uuid), required): Id of the employee, group or org unit
  - `subjectKind` (string, required): Who is named: one employee, the members of a group or of an org unit (one of `employee`, `group`, `org_unit`)
  - `includeSubunits` (boolean): org_unit only: the members of the units below it too
  - `subjectName` (string, read-only): Name of the employee, group or org unit (filled on reads)
- `closedAt` (string (date-time)): When the posting was closed
- `counts` (object): Applications per phase
- `createdAt` (string (date-time)): When the posting was created
- `createdBy` (string): Who created the posting (e-mail of the caller)
- `id` (string (uuid)): Id of the posting
- `number` (integer): Number of the posting, unique in the tenant (careers site address)
- `publishedAt` (string (date-time)): When the posting was last published
- `role` (string): The caller's role on the posting (one of `viewer`, `reviewer`, `manager`)
- `status` (string): State of the posting (one of `draft`, `published`, `closed`, `archived`)
- `updatedAt` (string (date-time)): When the posting was last changed

Example 200 answer:

```json
{
  "access": [
    {
      "role": "reviewer",
      "subjectId": "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c",
      "subjectKind": "employee",
      "subjectName": "Jonas Bauer"
    },
    {
      "includeSubunits": true,
      "role": "viewer",
      "subjectId": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
      "subjectKind": "org_unit",
      "subjectName": "Technik"
    }
  ],
  "contactEmployeeId": "9b1d3f5a-7c9e-4b1d-8f3a-5c7e9b1d3f2e",
  "counts": {
    "active": 3,
    "hired": 0,
    "new": 1,
    "rejected": 0,
    "withdrawn": 0
  },
  "createdAt": "2026-09-29T14:10:00Z",
  "createdBy": "tobias.hartl@muster-it.example",
  "description": "## Ihre Aufgaben\n- Betrieb und Weiterentwicklung der Microsoft-365-Umgebungen unserer Kunden (Exchange Online, Teams, SharePoint, Intune)\n- Migrationen von On-Premises-Servern in die Cloud",
  "employmentType": "full_time",
  "formTemplateId": "3e5a7c9e-1a3c-4e5a-9c7e-1a3c5e7a9c90",
  "id": "4a6c8e0a-2c4e-4a6c-9e0a-2c4e6a8c0e81",
  "location": "Regensburg",
  "number": 1,
  "orgUnitId": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
  "publishedAt": "2026-10-01T07:00:00Z",
  "questions": [],
  "role": "manager",
  "salaryCurrency": "EUR",
  "salaryMax": 58000,
  "salaryMin": 48000,
  "salaryPeriod": "year",
  "startDate": "2027-01-01",
  "status": "published",
  "title": "Systemadministrator:in (m/w/d) Microsoft 365",
  "updatedAt": "2026-10-01T07:00:00Z",
  "version": 3,
  "workplace": "hybrid"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/recruiting/postings/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Delete a draft without applications (hr:recruiting:manage)

`DELETE /api/hr/v1/recruiting/postings/{id}`

Module: HR · operationId: `deleteJobPosting` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/hr/v1/recruiting/postings/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change a posting (managers of the posting; not when archived)

`PATCH /api/hr/v1/recruiting/postings/{id}`

Module: HR · operationId: `updateJobPosting` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

Sends the whole posting with its `version`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `employmentType` (string, required): Kind of employment (one of `full_time`, `part_time`, `mini_job`, `apprenticeship`, `internship`, `working_student`, `freelance`)
- `title` (string, required): Title of the posting (max length 300)
- `contactEmployeeId` (string (uuid)): Employee id of the contact person
- `description` (string): Markdown
- `formTemplateId` (string (uuid)): Id of the application form template
- `location` (string): Place of work (max length 300)
- `orgUnitId` (string (uuid)): Heads and deputies of the unit (and the units above it) review the posting
- `publishFrom` (string (date-time)): A published posting is shown on the careers site from then on (empty: at once)
- `publishUntil` (string (date-time)): A published posting is shown on the careers site until then (empty: until closed)
- `questions` (array of ApplicationFormField): Questions of this posting after those of its form template
  - `key` (string, required): Lower-case letters, digits, - or _; not a core field (first_name, last_name, email, phone, cover_letter, cv, attachments)
  - `kind` (string, required): Kind of answer (one of `text`, `longtext`, `number`, `date`, `bool`, `select`, `multiselect`, `url`, `file`)
  - `label` (string, required): Question text (max length 300)
  - `help` (string): Help text shown with the question (max length 1000)
  - `options` (array of object): Choices of select and multiselect questions
    - `label` (string): Display text of the choice
    - `value` (string): Stored value of the choice
  - `required` (boolean): An answer is required
- `salaryCurrency` (string): Currency of the salary (ISO 4217) (default `"EUR"`)
- `salaryMax` (integer (int64)): Upper end of the salary range
- `salaryMin` (integer (int64)): In the currency's main unit per period
- `salaryPeriod` (string): Period the salary refers to (one of `year`, `month`, `hour`; default `"year"`)
- `startDate` (string (date)): Start date (YYYY-MM-DD), empty for none
- `version` (integer): Version of the posting a change is based on
- `workplace` (string): Where the work is done (one of `onsite`, `hybrid`, `remote`; default `"onsite"`)

Example:

```json
{
  "contactEmployeeId": "9b1d3f5a-7c9e-4b1d-8f3a-5c7e9b1d3f2e",
  "employmentType": "full_time",
  "formTemplateId": "3e5a7c9e-1a3c-4e5a-9c7e-1a3c5e7a9c90",
  "location": "Regensburg",
  "orgUnitId": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
  "publishUntil": "2027-01-31T23:00:00Z",
  "salaryCurrency": "EUR",
  "salaryMax": 60000,
  "salaryMin": 50000,
  "salaryPeriod": "year",
  "startDate": "2027-01-01",
  "title": "Systemadministrator:in (m/w/d) Microsoft 365",
  "version": 3,
  "workplace": "hybrid"
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `employmentType` (string, required): Kind of employment (one of `full_time`, `part_time`, `mini_job`, `apprenticeship`, `internship`, `working_student`, `freelance`)
- `title` (string, required): Title of the posting (max length 300)
- `contactEmployeeId` (string (uuid)): Employee id of the contact person
- `description` (string): Markdown
- `formTemplateId` (string (uuid)): Id of the application form template
- `location` (string): Place of work (max length 300)
- `orgUnitId` (string (uuid)): Heads and deputies of the unit (and the units above it) review the posting
- `publishFrom` (string (date-time)): A published posting is shown on the careers site from then on (empty: at once)
- `publishUntil` (string (date-time)): A published posting is shown on the careers site until then (empty: until closed)
- `questions` (array of ApplicationFormField): Questions of this posting after those of its form template
  - `key` (string, required): Lower-case letters, digits, - or _; not a core field (first_name, last_name, email, phone, cover_letter, cv, attachments)
  - `kind` (string, required): Kind of answer (one of `text`, `longtext`, `number`, `date`, `bool`, `select`, `multiselect`, `url`, `file`)
  - `label` (string, required): Question text (max length 300)
  - `help` (string): Help text shown with the question (max length 1000)
  - `options` (array of object): Choices of select and multiselect questions
    - `label` (string): Display text of the choice
    - `value` (string): Stored value of the choice
  - `required` (boolean): An answer is required
- `salaryCurrency` (string): Currency of the salary (ISO 4217) (default `"EUR"`)
- `salaryMax` (integer (int64)): Upper end of the salary range
- `salaryMin` (integer (int64)): In the currency's main unit per period
- `salaryPeriod` (string): Period the salary refers to (one of `year`, `month`, `hour`; default `"year"`)
- `startDate` (string (date)): Start date (YYYY-MM-DD), empty for none
- `version` (integer): Version of the posting a change is based on
- `workplace` (string): Where the work is done (one of `onsite`, `hybrid`, `remote`; default `"onsite"`)
- `access` (array of PostingAccessEntry): Only for managers of the posting
  - `role` (string, required): viewer reads; reviewer also notes, rates and sees interviews; manager moves, rejects, hires, mails, schedules and edits the posting (one of `viewer`, `reviewer`, `manager`)
  - `subjectId` (string (uuid), required): Id of the employee, group or org unit
  - `subjectKind` (string, required): Who is named: one employee, the members of a group or of an org unit (one of `employee`, `group`, `org_unit`)
  - `includeSubunits` (boolean): org_unit only: the members of the units below it too
  - `subjectName` (string, read-only): Name of the employee, group or org unit (filled on reads)
- `closedAt` (string (date-time)): When the posting was closed
- `counts` (object): Applications per phase
- `createdAt` (string (date-time)): When the posting was created
- `createdBy` (string): Who created the posting (e-mail of the caller)
- `id` (string (uuid)): Id of the posting
- `number` (integer): Number of the posting, unique in the tenant (careers site address)
- `publishedAt` (string (date-time)): When the posting was last published
- `role` (string): The caller's role on the posting (one of `viewer`, `reviewer`, `manager`)
- `status` (string): State of the posting (one of `draft`, `published`, `closed`, `archived`)
- `updatedAt` (string (date-time)): When the posting was last changed

Example 200 answer:

```json
{
  "access": [
    {
      "role": "reviewer",
      "subjectId": "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c",
      "subjectKind": "employee",
      "subjectName": "Jonas Bauer"
    },
    {
      "includeSubunits": true,
      "role": "viewer",
      "subjectId": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
      "subjectKind": "org_unit",
      "subjectName": "Technik"
    }
  ],
  "contactEmployeeId": "9b1d3f5a-7c9e-4b1d-8f3a-5c7e9b1d3f2e",
  "counts": {
    "active": 3,
    "hired": 0,
    "new": 1,
    "rejected": 0,
    "withdrawn": 0
  },
  "createdAt": "2026-09-29T14:10:00Z",
  "createdBy": "tobias.hartl@muster-it.example",
  "description": "## Ihre Aufgaben\n- Betrieb und Weiterentwicklung der Microsoft-365-Umgebungen unserer Kunden (Exchange Online, Teams, SharePoint, Intune)\n- Migrationen von On-Premises-Servern in die Cloud",
  "employmentType": "full_time",
  "formTemplateId": "3e5a7c9e-1a3c-4e5a-9c7e-1a3c5e7a9c90",
  "id": "4a6c8e0a-2c4e-4a6c-9e0a-2c4e6a8c0e81",
  "location": "Regensburg",
  "number": 1,
  "orgUnitId": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
  "publishedAt": "2026-10-01T07:00:00Z",
  "questions": [],
  "role": "manager",
  "salaryCurrency": "EUR",
  "salaryMax": 58000,
  "salaryMin": 48000,
  "salaryPeriod": "year",
  "startDate": "2027-01-01",
  "status": "published",
  "title": "Systemadministrator:in (m/w/d) Microsoft 365",
  "updatedAt": "2026-10-01T07:00:00Z",
  "version": 3,
  "workplace": "hybrid"
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/hr/v1/recruiting/postings/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"contactEmployeeId":"9b1d3f5a-7c9e-4b1d-8f3a-5c7e9b1d3f2e","employmentType":"full_time","formTemplateId":"3e5a7c9e-1a3c-4e5a-9c7e-1a3c5e7a9c90","location":"Regensburg","orgUnitId":"2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72","publishUntil":"2027-01-31T23:00:00Z","salaryCurrency":"EUR","salaryMax":60000,"salaryMin":50000,"salaryPeriod":"year","startDate":"2027-01-01","title":"Systemadministrator:in (m/w/d) Microsoft 365","version":3,"workplace":"hybrid"}'
```

## Publish, close, archive or reopen a posting (managers of the posting)

`POST /api/hr/v1/recruiting/postings/{id}/{action}`

Module: HR · operationId: `changeJobPostingStatus` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

Drafts and closed postings are published, published ones closed, drafts and closed ones archived, archived ones reopened as drafts; anything else `409 posting_state`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `action` | path | string | yes | (one of `publish`, `close`, `archive`, `reopen`) |

### Request body

`application/json` (required)

- `version` (integer): The version the change is based on (409 version_conflict when it changed)

Example:

```json
{
  "version": 3
}
```

### Responses

- **200** The posting (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `employmentType` (string, required): Kind of employment (one of `full_time`, `part_time`, `mini_job`, `apprenticeship`, `internship`, `working_student`, `freelance`)
- `title` (string, required): Title of the posting (max length 300)
- `contactEmployeeId` (string (uuid)): Employee id of the contact person
- `description` (string): Markdown
- `formTemplateId` (string (uuid)): Id of the application form template
- `location` (string): Place of work (max length 300)
- `orgUnitId` (string (uuid)): Heads and deputies of the unit (and the units above it) review the posting
- `publishFrom` (string (date-time)): A published posting is shown on the careers site from then on (empty: at once)
- `publishUntil` (string (date-time)): A published posting is shown on the careers site until then (empty: until closed)
- `questions` (array of ApplicationFormField): Questions of this posting after those of its form template
  - `key` (string, required): Lower-case letters, digits, - or _; not a core field (first_name, last_name, email, phone, cover_letter, cv, attachments)
  - `kind` (string, required): Kind of answer (one of `text`, `longtext`, `number`, `date`, `bool`, `select`, `multiselect`, `url`, `file`)
  - `label` (string, required): Question text (max length 300)
  - `help` (string): Help text shown with the question (max length 1000)
  - `options` (array of object): Choices of select and multiselect questions
    - `label` (string): Display text of the choice
    - `value` (string): Stored value of the choice
  - `required` (boolean): An answer is required
- `salaryCurrency` (string): Currency of the salary (ISO 4217) (default `"EUR"`)
- `salaryMax` (integer (int64)): Upper end of the salary range
- `salaryMin` (integer (int64)): In the currency's main unit per period
- `salaryPeriod` (string): Period the salary refers to (one of `year`, `month`, `hour`; default `"year"`)
- `startDate` (string (date)): Start date (YYYY-MM-DD), empty for none
- `version` (integer): Version of the posting a change is based on
- `workplace` (string): Where the work is done (one of `onsite`, `hybrid`, `remote`; default `"onsite"`)
- `access` (array of PostingAccessEntry): Only for managers of the posting
  - `role` (string, required): viewer reads; reviewer also notes, rates and sees interviews; manager moves, rejects, hires, mails, schedules and edits the posting (one of `viewer`, `reviewer`, `manager`)
  - `subjectId` (string (uuid), required): Id of the employee, group or org unit
  - `subjectKind` (string, required): Who is named: one employee, the members of a group or of an org unit (one of `employee`, `group`, `org_unit`)
  - `includeSubunits` (boolean): org_unit only: the members of the units below it too
  - `subjectName` (string, read-only): Name of the employee, group or org unit (filled on reads)
- `closedAt` (string (date-time)): When the posting was closed
- `counts` (object): Applications per phase
- `createdAt` (string (date-time)): When the posting was created
- `createdBy` (string): Who created the posting (e-mail of the caller)
- `id` (string (uuid)): Id of the posting
- `number` (integer): Number of the posting, unique in the tenant (careers site address)
- `publishedAt` (string (date-time)): When the posting was last published
- `role` (string): The caller's role on the posting (one of `viewer`, `reviewer`, `manager`)
- `status` (string): State of the posting (one of `draft`, `published`, `closed`, `archived`)
- `updatedAt` (string (date-time)): When the posting was last changed

Example 200 answer:

```json
{
  "access": [
    {
      "role": "reviewer",
      "subjectId": "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c",
      "subjectKind": "employee",
      "subjectName": "Jonas Bauer"
    },
    {
      "includeSubunits": true,
      "role": "viewer",
      "subjectId": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
      "subjectKind": "org_unit",
      "subjectName": "Technik"
    }
  ],
  "contactEmployeeId": "9b1d3f5a-7c9e-4b1d-8f3a-5c7e9b1d3f2e",
  "counts": {
    "active": 3,
    "hired": 0,
    "new": 1,
    "rejected": 0,
    "withdrawn": 0
  },
  "createdAt": "2026-09-29T14:10:00Z",
  "createdBy": "tobias.hartl@muster-it.example",
  "description": "## Ihre Aufgaben\n- Betrieb und Weiterentwicklung der Microsoft-365-Umgebungen unserer Kunden (Exchange Online, Teams, SharePoint, Intune)\n- Migrationen von On-Premises-Servern in die Cloud",
  "employmentType": "full_time",
  "formTemplateId": "3e5a7c9e-1a3c-4e5a-9c7e-1a3c5e7a9c90",
  "id": "4a6c8e0a-2c4e-4a6c-9e0a-2c4e6a8c0e81",
  "location": "Regensburg",
  "number": 1,
  "orgUnitId": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
  "publishedAt": "2026-10-01T07:00:00Z",
  "questions": [],
  "role": "manager",
  "salaryCurrency": "EUR",
  "salaryMax": 58000,
  "salaryMin": 48000,
  "salaryPeriod": "year",
  "startDate": "2027-01-01",
  "status": "published",
  "title": "Systemadministrator:in (m/w/d) Microsoft 365",
  "updatedAt": "2026-10-01T07:00:00Z",
  "version": 3,
  "workplace": "hybrid"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/recruiting/postings/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/publish' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"version":3}'
```

## Replace who works on a posting (managers of the posting)

`PUT /api/hr/v1/recruiting/postings/{id}/access`

Module: HR · operationId: `setJobPostingAccess` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

People, groups and org units (optionally with the units below them) as viewer, reviewer or manager. Heads and
deputies of the posting's org unit and the units above it are reviewers without an entry. Access lists only
apply to people signed in themselves; API keys act with their permissions.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `entries` (array of PostingAccessEntry): Who works on the posting; replaces the list
  - `role` (string, required): viewer reads; reviewer also notes, rates and sees interviews; manager moves, rejects, hires, mails, schedules and edits the posting (one of `viewer`, `reviewer`, `manager`)
  - `subjectId` (string (uuid), required): Id of the employee, group or org unit
  - `subjectKind` (string, required): Who is named: one employee, the members of a group or of an org unit (one of `employee`, `group`, `org_unit`)
  - `includeSubunits` (boolean): org_unit only: the members of the units below it too
  - `subjectName` (string, read-only): Name of the employee, group or org unit (filled on reads)

Example:

```json
{
  "entries": [
    {
      "role": "reviewer",
      "subjectId": "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c",
      "subjectKind": "employee"
    },
    {
      "includeSubunits": true,
      "role": "viewer",
      "subjectId": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
      "subjectKind": "org_unit"
    }
  ]
}
```

### Responses

- **200** The access list with names (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `entries` (array of PostingAccessEntry): The saved access list
  - `role` (string, required): viewer reads; reviewer also notes, rates and sees interviews; manager moves, rejects, hires, mails, schedules and edits the posting (one of `viewer`, `reviewer`, `manager`)
  - `subjectId` (string (uuid), required): Id of the employee, group or org unit
  - `subjectKind` (string, required): Who is named: one employee, the members of a group or of an org unit (one of `employee`, `group`, `org_unit`)
  - `includeSubunits` (boolean): org_unit only: the members of the units below it too
  - `subjectName` (string, read-only): Name of the employee, group or org unit (filled on reads)

Example 200 answer:

```json
{
  "entries": [
    {
      "role": "reviewer",
      "subjectId": "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c",
      "subjectKind": "employee",
      "subjectName": "Jonas Bauer"
    },
    {
      "includeSubunits": true,
      "role": "viewer",
      "subjectId": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
      "subjectKind": "org_unit",
      "subjectName": "Technik"
    }
  ]
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/recruiting/postings/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/access' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"entries":[{"role":"reviewer","subjectId":"f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c","subjectKind":"employee"},{"includeSubunits":true,"role":"viewer","subjectId":"2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72","subjectKind":"org_unit"}]}'
```

## The questions of a posting (its form template's, then its own)

`GET /api/hr/v1/recruiting/postings/{id}/form`

Module: HR · operationId: `getJobPostingForm` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Questions (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `fields` (array of ApplicationFormField): Questions of the posting: its form template's, then its own
  - `key` (string, required): Lower-case letters, digits, - or _; not a core field (first_name, last_name, email, phone, cover_letter, cv, attachments)
  - `kind` (string, required): Kind of answer (one of `text`, `longtext`, `number`, `date`, `bool`, `select`, `multiselect`, `url`, `file`)
  - `label` (string, required): Question text (max length 300)
  - `help` (string): Help text shown with the question (max length 1000)
  - `options` (array of object): Choices of select and multiselect questions
    - `label` (string): Display text of the choice
    - `value` (string): Stored value of the choice
  - `required` (boolean): An answer is required

Example 200 answer:

```json
{
  "fields": [
    {
      "key": "fruehester_start",
      "kind": "date",
      "label": "Ab wann können Sie bei uns starten?",
      "required": true
    },
    {
      "key": "gehaltsvorstellung",
      "kind": "number",
      "label": "Ihre Gehaltsvorstellung (brutto pro Jahr)",
      "required": false
    },
    {
      "key": "powershell",
      "kind": "select",
      "label": "Wie schätzen Sie Ihre PowerShell-Kenntnisse ein?",
      "options": [
        {
          "label": "Grundlagen",
          "value": "grundlagen"
        },
        {
          "label": "Fortgeschritten",
          "value": "fortgeschritten"
        },
        {
          "label": "Experte",
          "value": "experte"
        }
      ],
      "required": false
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/recruiting/postings/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/form' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Applications to the postings the caller sees

`GET /api/hr/v1/recruiting/applications`

Module: HR · operationId: `listApplications` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `postingId` | query | string (uuid) |  |  |
| `stageId` | query | string (uuid) |  |  |
| `phase` | query | string |  | Comma-separated phases, e.g. `new,active` |
| `q` | query | string |  | Searches name and e-mail |
| `talentPool` | query | boolean |  | Only applications in the talent pool |
| `limit` | query | integer |  | 1–200; another value is a 400 invalid. (default `50`; max 200) |
| `offset` | query | integer |  | (default `0`) |

### Responses

- **200** A page of applications (`application/json`)

Fields of the 200 answer:

- `items` (array of Application): Applications of this page
  - `answers` (object): Answers to the form questions by question key
  - `closeReason` (string): Reason given when it was closed
  - `closedAt` (string (date-time)): When it was rejected, withdrawn or hired
  - `consentAt` (string (date-time)): When the applicant gave the consent
  - `consentVersion` (integer): Version of the consent text the applicant accepted (0: none)
  - `coverLetter` (string): Cover letter text
  - `createdAt` (string (date-time)): When the application was created
  - `deleteAfter` (string (date-time)): When the application is deleted
  - `email` (string): Applicant's e-mail address
  - `employeeId` (string (uuid)): The employee created from it (hired)
  - `files` (array of ApplicationFile): Files of the application (single reads)
    - `contentType` (string): Media type of the file
    - `createdAt` (string (date-time)): When the file was added
    - `documentId` (string): Id of the document in DMS
    - `fieldKey` (string): Key of the form question the file answers (role answer)
    - `fileName` (string): File name
    - `id` (string (uuid)): Id of the file
    - `role` (string): What the file is (CV, attachment, answer to a file question, mail attachment) (one of `cv`, `attachment`, `answer`, `mail`)
    - `scanStatus` (string): Result of the malware scan; content is served only when CLEAN (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
    - `sizeBytes` (integer (int64)): Size in bytes
  - `firstName` (string): Applicant's first name
  - `id` (string (uuid)): Id of the application
  - `lastName` (string): Applicant's last name
  - `nextInterview` (string (date-time)): Start of the next interview, if any
  - `number` (integer): Number of the application, unique in the tenant
  - `phase` (string): Phase of the current stage (one of `new`, `active`, `hired`, `rejected`, `withdrawn`)
  - `phone` (string): Applicant's phone number
  - `postingId` (string (uuid)): Id of the posting applied to
  - `postingTitle` (string): Title of the posting
  - `rating` (object): Summary of the reviewers' ratings
    - `average` (number): Average score (1–5)
    - `count` (integer): Number of ratings
    - `mine` (integer): The caller's score (0 not rated)
  - `role` (string): The caller's role on the posting (one of `viewer`, `reviewer`, `manager`)
  - `source` (string): How the application arrived (one of `manual`, `portal`, `api`)
  - `stageChangedAt` (string (date-time)): When the application entered its current stage
  - `stageId` (string (uuid)): Id of the current pipeline stage
  - `talentPoolUntil` (string (date-time)): Kept in the talent pool until then (applicant agreed)
  - `updatedAt` (string (date-time)): When the application was last changed
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `total` (integer): Number of all matching applications

Example 200 answer:

```json
{
  "items": [
    {
      "consentVersion": 2,
      "createdAt": "2026-11-02T18:43:00Z",
      "email": "stefan.lindner@mail.example",
      "firstName": "Stefan",
      "id": "1c3e5a7c-9e1a-4c3e-9a5c-9e1a3c5e7a89",
      "lastName": "Lindner",
      "nextInterview": "2026-11-24T09:00:00Z",
      "number": 3,
      "phase": "active",
      "postingId": "4a6c8e0a-2c4e-4a6c-9e0a-2c4e6a8c0e81",
      "postingTitle": "Systemadministrator:in (m/w/d) Microsoft 365",
      "rating": {
        "average": 3.5,
        "count": 2,
        "mine": 3
      },
      "role": "manager",
      "source": "portal",
      "stageChangedAt": "2026-11-12T10:30:00Z",
      "stageId": "0a2c4e6a-8c0e-4a2c-8e6a-8c0e2a4c6e84",
      "updatedAt": "2026-11-12T10:30:00Z",
      "version": 5
    },
    {
      "consentVersion": 2,
      "createdAt": "2026-11-01T10:12:00Z",
      "email": "katharina.reiter@mail.example",
      "firstName": "Katharina",
      "id": "7e9a1c3e-5a7c-4e9a-9c1e-5a7c9e1a3c96",
      "lastName": "Reiter",
      "number": 2,
      "phase": "active",
      "postingId": "4a6c8e0a-2c4e-4a6c-9e0a-2c4e6a8c0e81",
      "postingTitle": "Systemadministrator:in (m/w/d) Microsoft 365",
      "rating": {
        "average": 4,
        "count": 1,
        "mine": 4
      },
      "role": "manager",
      "source": "manual",
      "stageChangedAt": "2026-11-05T09:00:00Z",
      "stageId": "8e0a2c4e-6a8c-4e0a-9c4e-6a8c0e2a4c83",
      "talentPoolUntil": "2027-11-02T00:00:00Z",
      "updatedAt": "2026-11-05T09:00:00Z",
      "version": 3
    }
  ],
  "total": 2
}
```

### Example request

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

## Enter an application by hand (managers of the posting)

`POST /api/hr/v1/recruiting/applications`

Module: HR · operationId: `createApplication` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

For applications received on paper or by mail; the posting must be published or closed. Required questions may stay open. Files follow with `uploadApplicationFile`. One open application per e-mail address and posting (`409 duplicate`).

### Request body

`application/json` (required)

- `email` (string (email), required): Applicant's e-mail address
- `postingId` (string (uuid), required): Id of the posting
- `answers` (object): Answers by question key
- `consent` (boolean): The person agreed to the current consent text
- `coverLetter` (string): Cover letter text (max length 20000)
- `firstName` (string): Applicant's first name (max length 200)
- `lastName` (string): Applicant's last name (max length 200)
- `phone` (string): Applicant's phone number (max length 100)
- `sendConfirmation` (boolean): Mail the default confirmation of receipt
- `stageId` (string (uuid)): A stage of the open phases (default the first new one)
- `talentPool` (boolean): The person agreed to the talent pool

Example:

```json
{
  "answers": {
    "fruehester_start": "2027-02-01"
  },
  "consent": true,
  "coverLetter": "Seit sechs Jahren betreue ich als Systemadministrator die Microsoft-365-Umgebung eines Maschinenbauers mit 120 Arbeitsplätzen.",
  "email": "johannes.kraus@mail.example",
  "firstName": "Johannes",
  "lastName": "Kraus",
  "phone": "+49 151 55501001",
  "postingId": "4a6c8e0a-2c4e-4a6c-9e0a-2c4e6a8c0e81",
  "sendConfirmation": true,
  "talentPool": false
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `answers` (object): Answers to the form questions by question key
- `closeReason` (string): Reason given when it was closed
- `closedAt` (string (date-time)): When it was rejected, withdrawn or hired
- `consentAt` (string (date-time)): When the applicant gave the consent
- `consentVersion` (integer): Version of the consent text the applicant accepted (0: none)
- `coverLetter` (string): Cover letter text
- `createdAt` (string (date-time)): When the application was created
- `deleteAfter` (string (date-time)): When the application is deleted
- `email` (string): Applicant's e-mail address
- `employeeId` (string (uuid)): The employee created from it (hired)
- `files` (array of ApplicationFile): Files of the application (single reads)
  - `contentType` (string): Media type of the file
  - `createdAt` (string (date-time)): When the file was added
  - `documentId` (string): Id of the document in DMS
  - `fieldKey` (string): Key of the form question the file answers (role answer)
  - `fileName` (string): File name
  - `id` (string (uuid)): Id of the file
  - `role` (string): What the file is (CV, attachment, answer to a file question, mail attachment) (one of `cv`, `attachment`, `answer`, `mail`)
  - `scanStatus` (string): Result of the malware scan; content is served only when CLEAN (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
  - `sizeBytes` (integer (int64)): Size in bytes
- `firstName` (string): Applicant's first name
- `id` (string (uuid)): Id of the application
- `lastName` (string): Applicant's last name
- `nextInterview` (string (date-time)): Start of the next interview, if any
- `number` (integer): Number of the application, unique in the tenant
- `phase` (string): Phase of the current stage (one of `new`, `active`, `hired`, `rejected`, `withdrawn`)
- `phone` (string): Applicant's phone number
- `postingId` (string (uuid)): Id of the posting applied to
- `postingTitle` (string): Title of the posting
- `rating` (object): Summary of the reviewers' ratings
  - `average` (number): Average score (1–5)
  - `count` (integer): Number of ratings
  - `mine` (integer): The caller's score (0 not rated)
- `role` (string): The caller's role on the posting (one of `viewer`, `reviewer`, `manager`)
- `source` (string): How the application arrived (one of `manual`, `portal`, `api`)
- `stageChangedAt` (string (date-time)): When the application entered its current stage
- `stageId` (string (uuid)): Id of the current pipeline stage
- `talentPoolUntil` (string (date-time)): Kept in the talent pool until then (applicant agreed)
- `updatedAt` (string (date-time)): When the application was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 201 answer:

```json
{
  "answers": {
    "fruehester_start": "2027-01-01",
    "gehaltsvorstellung": 52000,
    "powershell": "grundlagen"
  },
  "consentAt": "2026-11-02T18:43:00Z",
  "consentVersion": 2,
  "coverLetter": "Ich bin Fachinformatiker für Systemintegration und möchte mich nach vier Jahren im Rechenzentrum stärker auf Cloud-Arbeitsplätze spezialisieren.",
  "createdAt": "2026-11-02T18:43:00Z",
  "deleteAfter": "2027-11-02T18:43:00Z",
  "email": "stefan.lindner@mail.example",
  "files": [
    {
      "contentType": "application/pdf",
      "createdAt": "2026-11-02T18:41:00Z",
      "documentId": "5c7e9a1c-3e5a-4c7e-9a9c-3e5a7c9e1a95",
      "fileName": "lebenslauf-stefan-lindner.pdf",
      "id": "3a5c7e9a-1c3e-4a5c-8e7a-1c3e5a7c9e94",
      "role": "cv",
      "scanStatus": "CLEAN",
      "sizeBytes": 248311
    }
  ],
  "firstName": "Stefan",
  "id": "1c3e5a7c-9e1a-4c3e-9a5c-9e1a3c5e7a89",
  "lastName": "Lindner",
  "nextInterview": "2026-11-24T09:00:00Z",
  "number": 3,
  "phase": "active",
  "phone": "+49 170 55501003",
  "postingId": "4a6c8e0a-2c4e-4a6c-9e0a-2c4e6a8c0e81",
  "postingTitle": "Systemadministrator:in (m/w/d) Microsoft 365",
  "rating": {
    "average": 3.5,
    "count": 2,
    "mine": 3
  },
  "role": "manager",
  "source": "portal",
  "stageChangedAt": "2026-11-12T10:30:00Z",
  "stageId": "0a2c4e6a-8c0e-4a2c-8e6a-8c0e2a4c6e84",
  "updatedAt": "2026-11-12T10:30:00Z",
  "version": 5
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/recruiting/applications' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"answers":{"fruehester_start":"2027-02-01"},"consent":true,"coverLetter":"Seit sechs Jahren betreue ich als Systemadministrator die Microsoft-365-Umgebung eines Maschinenbauers mit 120 Arbeitsplätzen.","email":"johannes.kraus@mail.example","firstName":"Johannes","lastName":"Kraus","phone":"+49 151 55501001","postingId":"4a6c8e0a-2c4e-4a6c-9e0a-2c4e6a8c0e81","sendConfirmation":true,"talentPool":false}'
```

## One application with its files and rating

`GET /api/hr/v1/recruiting/applications/{id}`

Module: HR · operationId: `getApplication` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

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

Fields of the 200 answer:

- `answers` (object): Answers to the form questions by question key
- `closeReason` (string): Reason given when it was closed
- `closedAt` (string (date-time)): When it was rejected, withdrawn or hired
- `consentAt` (string (date-time)): When the applicant gave the consent
- `consentVersion` (integer): Version of the consent text the applicant accepted (0: none)
- `coverLetter` (string): Cover letter text
- `createdAt` (string (date-time)): When the application was created
- `deleteAfter` (string (date-time)): When the application is deleted
- `email` (string): Applicant's e-mail address
- `employeeId` (string (uuid)): The employee created from it (hired)
- `files` (array of ApplicationFile): Files of the application (single reads)
  - `contentType` (string): Media type of the file
  - `createdAt` (string (date-time)): When the file was added
  - `documentId` (string): Id of the document in DMS
  - `fieldKey` (string): Key of the form question the file answers (role answer)
  - `fileName` (string): File name
  - `id` (string (uuid)): Id of the file
  - `role` (string): What the file is (CV, attachment, answer to a file question, mail attachment) (one of `cv`, `attachment`, `answer`, `mail`)
  - `scanStatus` (string): Result of the malware scan; content is served only when CLEAN (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
  - `sizeBytes` (integer (int64)): Size in bytes
- `firstName` (string): Applicant's first name
- `id` (string (uuid)): Id of the application
- `lastName` (string): Applicant's last name
- `nextInterview` (string (date-time)): Start of the next interview, if any
- `number` (integer): Number of the application, unique in the tenant
- `phase` (string): Phase of the current stage (one of `new`, `active`, `hired`, `rejected`, `withdrawn`)
- `phone` (string): Applicant's phone number
- `postingId` (string (uuid)): Id of the posting applied to
- `postingTitle` (string): Title of the posting
- `rating` (object): Summary of the reviewers' ratings
  - `average` (number): Average score (1–5)
  - `count` (integer): Number of ratings
  - `mine` (integer): The caller's score (0 not rated)
- `role` (string): The caller's role on the posting (one of `viewer`, `reviewer`, `manager`)
- `source` (string): How the application arrived (one of `manual`, `portal`, `api`)
- `stageChangedAt` (string (date-time)): When the application entered its current stage
- `stageId` (string (uuid)): Id of the current pipeline stage
- `talentPoolUntil` (string (date-time)): Kept in the talent pool until then (applicant agreed)
- `updatedAt` (string (date-time)): When the application was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "answers": {
    "fruehester_start": "2027-01-01",
    "gehaltsvorstellung": 52000,
    "powershell": "grundlagen"
  },
  "consentAt": "2026-11-02T18:43:00Z",
  "consentVersion": 2,
  "coverLetter": "Ich bin Fachinformatiker für Systemintegration und möchte mich nach vier Jahren im Rechenzentrum stärker auf Cloud-Arbeitsplätze spezialisieren.",
  "createdAt": "2026-11-02T18:43:00Z",
  "deleteAfter": "2027-11-02T18:43:00Z",
  "email": "stefan.lindner@mail.example",
  "files": [
    {
      "contentType": "application/pdf",
      "createdAt": "2026-11-02T18:41:00Z",
      "documentId": "5c7e9a1c-3e5a-4c7e-9a9c-3e5a7c9e1a95",
      "fileName": "lebenslauf-stefan-lindner.pdf",
      "id": "3a5c7e9a-1c3e-4a5c-8e7a-1c3e5a7c9e94",
      "role": "cv",
      "scanStatus": "CLEAN",
      "sizeBytes": 248311
    }
  ],
  "firstName": "Stefan",
  "id": "1c3e5a7c-9e1a-4c3e-9a5c-9e1a3c5e7a89",
  "lastName": "Lindner",
  "nextInterview": "2026-11-24T09:00:00Z",
  "number": 3,
  "phase": "active",
  "phone": "+49 170 55501003",
  "postingId": "4a6c8e0a-2c4e-4a6c-9e0a-2c4e6a8c0e81",
  "postingTitle": "Systemadministrator:in (m/w/d) Microsoft 365",
  "rating": {
    "average": 3.5,
    "count": 2,
    "mine": 3
  },
  "role": "manager",
  "source": "portal",
  "stageChangedAt": "2026-11-12T10:30:00Z",
  "stageId": "0a2c4e6a-8c0e-4a2c-8e6a-8c0e2a4c6e84",
  "updatedAt": "2026-11-12T10:30:00Z",
  "version": 5
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/recruiting/applications/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change the applicant's data (managers of the posting)

`PATCH /api/hr/v1/recruiting/applications/{id}`

Module: HR · operationId: `updateApplication` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `answers` (object): Answers to the form questions by question key (omitted: unchanged)
- `coverLetter` (string): New cover letter (omitted: unchanged)
- `email` (string (email)): New e-mail address (omitted: unchanged)
- `firstName` (string): New first name (omitted: unchanged)
- `lastName` (string): New last name (omitted: unchanged)
- `phone` (string): New phone number (omitted: unchanged)
- `version` (integer): Version of the application the change is based on

Example:

```json
{
  "answers": {
    "gehaltsvorstellung": 54000
  },
  "phone": "+49 170 55501033",
  "version": 5
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `answers` (object): Answers to the form questions by question key
- `closeReason` (string): Reason given when it was closed
- `closedAt` (string (date-time)): When it was rejected, withdrawn or hired
- `consentAt` (string (date-time)): When the applicant gave the consent
- `consentVersion` (integer): Version of the consent text the applicant accepted (0: none)
- `coverLetter` (string): Cover letter text
- `createdAt` (string (date-time)): When the application was created
- `deleteAfter` (string (date-time)): When the application is deleted
- `email` (string): Applicant's e-mail address
- `employeeId` (string (uuid)): The employee created from it (hired)
- `files` (array of ApplicationFile): Files of the application (single reads)
  - `contentType` (string): Media type of the file
  - `createdAt` (string (date-time)): When the file was added
  - `documentId` (string): Id of the document in DMS
  - `fieldKey` (string): Key of the form question the file answers (role answer)
  - `fileName` (string): File name
  - `id` (string (uuid)): Id of the file
  - `role` (string): What the file is (CV, attachment, answer to a file question, mail attachment) (one of `cv`, `attachment`, `answer`, `mail`)
  - `scanStatus` (string): Result of the malware scan; content is served only when CLEAN (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
  - `sizeBytes` (integer (int64)): Size in bytes
- `firstName` (string): Applicant's first name
- `id` (string (uuid)): Id of the application
- `lastName` (string): Applicant's last name
- `nextInterview` (string (date-time)): Start of the next interview, if any
- `number` (integer): Number of the application, unique in the tenant
- `phase` (string): Phase of the current stage (one of `new`, `active`, `hired`, `rejected`, `withdrawn`)
- `phone` (string): Applicant's phone number
- `postingId` (string (uuid)): Id of the posting applied to
- `postingTitle` (string): Title of the posting
- `rating` (object): Summary of the reviewers' ratings
  - `average` (number): Average score (1–5)
  - `count` (integer): Number of ratings
  - `mine` (integer): The caller's score (0 not rated)
- `role` (string): The caller's role on the posting (one of `viewer`, `reviewer`, `manager`)
- `source` (string): How the application arrived (one of `manual`, `portal`, `api`)
- `stageChangedAt` (string (date-time)): When the application entered its current stage
- `stageId` (string (uuid)): Id of the current pipeline stage
- `talentPoolUntil` (string (date-time)): Kept in the talent pool until then (applicant agreed)
- `updatedAt` (string (date-time)): When the application was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "answers": {
    "fruehester_start": "2027-01-01",
    "gehaltsvorstellung": 52000,
    "powershell": "grundlagen"
  },
  "consentAt": "2026-11-02T18:43:00Z",
  "consentVersion": 2,
  "coverLetter": "Ich bin Fachinformatiker für Systemintegration und möchte mich nach vier Jahren im Rechenzentrum stärker auf Cloud-Arbeitsplätze spezialisieren.",
  "createdAt": "2026-11-02T18:43:00Z",
  "deleteAfter": "2027-11-02T18:43:00Z",
  "email": "stefan.lindner@mail.example",
  "files": [
    {
      "contentType": "application/pdf",
      "createdAt": "2026-11-02T18:41:00Z",
      "documentId": "5c7e9a1c-3e5a-4c7e-9a9c-3e5a7c9e1a95",
      "fileName": "lebenslauf-stefan-lindner.pdf",
      "id": "3a5c7e9a-1c3e-4a5c-8e7a-1c3e5a7c9e94",
      "role": "cv",
      "scanStatus": "CLEAN",
      "sizeBytes": 248311
    }
  ],
  "firstName": "Stefan",
  "id": "1c3e5a7c-9e1a-4c3e-9a5c-9e1a3c5e7a89",
  "lastName": "Lindner",
  "nextInterview": "2026-11-24T09:00:00Z",
  "number": 3,
  "phase": "active",
  "phone": "+49 170 55501003",
  "postingId": "4a6c8e0a-2c4e-4a6c-9e0a-2c4e6a8c0e81",
  "postingTitle": "Systemadministrator:in (m/w/d) Microsoft 365",
  "rating": {
    "average": 3.5,
    "count": 2,
    "mine": 3
  },
  "role": "manager",
  "source": "portal",
  "stageChangedAt": "2026-11-12T10:30:00Z",
  "stageId": "0a2c4e6a-8c0e-4a2c-8e6a-8c0e2a4c6e84",
  "updatedAt": "2026-11-12T10:30:00Z",
  "version": 5
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/hr/v1/recruiting/applications/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"answers":{"gehaltsvorstellung":54000},"phone":"+49 170 55501033","version":5}'
```

## Move an application to a stage of the open phases, or reopen a rejected or withdrawn one (managers of the posting)

`POST /api/hr/v1/recruiting/applications/{id}/move`

Module: HR · operationId: `moveApplication` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

Rejecting, withdrawing and hiring have their own operations; other moves answer `409 stage_not_allowed`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `stageId` (string (uuid), required): Id of the target stage
- `version` (integer): Version of the application the move is based on

Example:

```json
{
  "stageId": "2c4e6a8c-0e2a-4c4e-9a8c-0e2a4c6e8a85",
  "version": 5
}
```

### Responses

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

Fields of the 200 answer:

- `answers` (object): Answers to the form questions by question key
- `closeReason` (string): Reason given when it was closed
- `closedAt` (string (date-time)): When it was rejected, withdrawn or hired
- `consentAt` (string (date-time)): When the applicant gave the consent
- `consentVersion` (integer): Version of the consent text the applicant accepted (0: none)
- `coverLetter` (string): Cover letter text
- `createdAt` (string (date-time)): When the application was created
- `deleteAfter` (string (date-time)): When the application is deleted
- `email` (string): Applicant's e-mail address
- `employeeId` (string (uuid)): The employee created from it (hired)
- `files` (array of ApplicationFile): Files of the application (single reads)
  - `contentType` (string): Media type of the file
  - `createdAt` (string (date-time)): When the file was added
  - `documentId` (string): Id of the document in DMS
  - `fieldKey` (string): Key of the form question the file answers (role answer)
  - `fileName` (string): File name
  - `id` (string (uuid)): Id of the file
  - `role` (string): What the file is (CV, attachment, answer to a file question, mail attachment) (one of `cv`, `attachment`, `answer`, `mail`)
  - `scanStatus` (string): Result of the malware scan; content is served only when CLEAN (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
  - `sizeBytes` (integer (int64)): Size in bytes
- `firstName` (string): Applicant's first name
- `id` (string (uuid)): Id of the application
- `lastName` (string): Applicant's last name
- `nextInterview` (string (date-time)): Start of the next interview, if any
- `number` (integer): Number of the application, unique in the tenant
- `phase` (string): Phase of the current stage (one of `new`, `active`, `hired`, `rejected`, `withdrawn`)
- `phone` (string): Applicant's phone number
- `postingId` (string (uuid)): Id of the posting applied to
- `postingTitle` (string): Title of the posting
- `rating` (object): Summary of the reviewers' ratings
  - `average` (number): Average score (1–5)
  - `count` (integer): Number of ratings
  - `mine` (integer): The caller's score (0 not rated)
- `role` (string): The caller's role on the posting (one of `viewer`, `reviewer`, `manager`)
- `source` (string): How the application arrived (one of `manual`, `portal`, `api`)
- `stageChangedAt` (string (date-time)): When the application entered its current stage
- `stageId` (string (uuid)): Id of the current pipeline stage
- `talentPoolUntil` (string (date-time)): Kept in the talent pool until then (applicant agreed)
- `updatedAt` (string (date-time)): When the application was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "answers": {
    "fruehester_start": "2027-01-01",
    "gehaltsvorstellung": 52000,
    "powershell": "grundlagen"
  },
  "consentAt": "2026-11-02T18:43:00Z",
  "consentVersion": 2,
  "coverLetter": "Ich bin Fachinformatiker für Systemintegration und möchte mich nach vier Jahren im Rechenzentrum stärker auf Cloud-Arbeitsplätze spezialisieren.",
  "createdAt": "2026-11-02T18:43:00Z",
  "deleteAfter": "2027-11-02T18:43:00Z",
  "email": "stefan.lindner@mail.example",
  "files": [
    {
      "contentType": "application/pdf",
      "createdAt": "2026-11-02T18:41:00Z",
      "documentId": "5c7e9a1c-3e5a-4c7e-9a9c-3e5a7c9e1a95",
      "fileName": "lebenslauf-stefan-lindner.pdf",
      "id": "3a5c7e9a-1c3e-4a5c-8e7a-1c3e5a7c9e94",
      "role": "cv",
      "scanStatus": "CLEAN",
      "sizeBytes": 248311
    }
  ],
  "firstName": "Stefan",
  "id": "1c3e5a7c-9e1a-4c3e-9a5c-9e1a3c5e7a89",
  "lastName": "Lindner",
  "nextInterview": "2026-11-24T09:00:00Z",
  "number": 3,
  "phase": "active",
  "phone": "+49 170 55501003",
  "postingId": "4a6c8e0a-2c4e-4a6c-9e0a-2c4e6a8c0e81",
  "postingTitle": "Systemadministrator:in (m/w/d) Microsoft 365",
  "rating": {
    "average": 3.5,
    "count": 2,
    "mine": 3
  },
  "role": "manager",
  "source": "portal",
  "stageChangedAt": "2026-11-12T10:30:00Z",
  "stageId": "0a2c4e6a-8c0e-4a2c-8e6a-8c0e2a4c6e84",
  "updatedAt": "2026-11-12T10:30:00Z",
  "version": 5
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/recruiting/applications/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/move' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"stageId":"2c4e6a8c-0e2a-4c4e-9a8c-0e2a4c6e8a85","version":5}'
```

## Reject an application, optionally with a mail to the applicant (managers of the posting)

`POST /api/hr/v1/recruiting/applications/{id}/reject`

Module: HR · operationId: `rejectApplication` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

The rejection mail goes out with the change (`409 no_mailbox` without a recruiting mailbox). The application is deleted after the retention period (or the end of the talent pool).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `mail` (ApplicantMail)
  - `body` (string, required): Markdown (max length 50000)
  - `subject` (string, required): Subject of the mail (max length 300)
- `reason` (string): Internal reason (max length 2000)
- `stageId` (string (uuid)): A stage of the phase (default the first)
- `version` (integer): Version of the application the change is based on

Example:

```json
{
  "mail": {
    "body": "Guten Tag Herr Lindner,\n\nvielen Dank für Ihr Interesse und das offene Gespräch. Wir haben uns für eine andere Bewerberin entschieden.\n\nMit freundlichen Grüßen\nMuster IT-Systemhaus GmbH – Personal",
    "subject": "Ihre Bewerbung als Systemadministrator:in Microsoft 365"
  },
  "reason": "Wenig Erfahrung mit Kundenprojekten; Angebot ging an eine andere Bewerberin.",
  "stageId": "6a8c0e2a-4c6e-4a8c-9e2a-4c6e8a0c2e87",
  "version": 6
}
```

### Responses

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

Fields of the 200 answer:

- `answers` (object): Answers to the form questions by question key
- `closeReason` (string): Reason given when it was closed
- `closedAt` (string (date-time)): When it was rejected, withdrawn or hired
- `consentAt` (string (date-time)): When the applicant gave the consent
- `consentVersion` (integer): Version of the consent text the applicant accepted (0: none)
- `coverLetter` (string): Cover letter text
- `createdAt` (string (date-time)): When the application was created
- `deleteAfter` (string (date-time)): When the application is deleted
- `email` (string): Applicant's e-mail address
- `employeeId` (string (uuid)): The employee created from it (hired)
- `files` (array of ApplicationFile): Files of the application (single reads)
  - `contentType` (string): Media type of the file
  - `createdAt` (string (date-time)): When the file was added
  - `documentId` (string): Id of the document in DMS
  - `fieldKey` (string): Key of the form question the file answers (role answer)
  - `fileName` (string): File name
  - `id` (string (uuid)): Id of the file
  - `role` (string): What the file is (CV, attachment, answer to a file question, mail attachment) (one of `cv`, `attachment`, `answer`, `mail`)
  - `scanStatus` (string): Result of the malware scan; content is served only when CLEAN (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
  - `sizeBytes` (integer (int64)): Size in bytes
- `firstName` (string): Applicant's first name
- `id` (string (uuid)): Id of the application
- `lastName` (string): Applicant's last name
- `nextInterview` (string (date-time)): Start of the next interview, if any
- `number` (integer): Number of the application, unique in the tenant
- `phase` (string): Phase of the current stage (one of `new`, `active`, `hired`, `rejected`, `withdrawn`)
- `phone` (string): Applicant's phone number
- `postingId` (string (uuid)): Id of the posting applied to
- `postingTitle` (string): Title of the posting
- `rating` (object): Summary of the reviewers' ratings
  - `average` (number): Average score (1–5)
  - `count` (integer): Number of ratings
  - `mine` (integer): The caller's score (0 not rated)
- `role` (string): The caller's role on the posting (one of `viewer`, `reviewer`, `manager`)
- `source` (string): How the application arrived (one of `manual`, `portal`, `api`)
- `stageChangedAt` (string (date-time)): When the application entered its current stage
- `stageId` (string (uuid)): Id of the current pipeline stage
- `talentPoolUntil` (string (date-time)): Kept in the talent pool until then (applicant agreed)
- `updatedAt` (string (date-time)): When the application was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "answers": {
    "fruehester_start": "2027-01-01",
    "gehaltsvorstellung": 52000,
    "powershell": "grundlagen"
  },
  "consentAt": "2026-11-02T18:43:00Z",
  "consentVersion": 2,
  "coverLetter": "Ich bin Fachinformatiker für Systemintegration und möchte mich nach vier Jahren im Rechenzentrum stärker auf Cloud-Arbeitsplätze spezialisieren.",
  "createdAt": "2026-11-02T18:43:00Z",
  "deleteAfter": "2027-11-02T18:43:00Z",
  "email": "stefan.lindner@mail.example",
  "files": [
    {
      "contentType": "application/pdf",
      "createdAt": "2026-11-02T18:41:00Z",
      "documentId": "5c7e9a1c-3e5a-4c7e-9a9c-3e5a7c9e1a95",
      "fileName": "lebenslauf-stefan-lindner.pdf",
      "id": "3a5c7e9a-1c3e-4a5c-8e7a-1c3e5a7c9e94",
      "role": "cv",
      "scanStatus": "CLEAN",
      "sizeBytes": 248311
    }
  ],
  "firstName": "Stefan",
  "id": "1c3e5a7c-9e1a-4c3e-9a5c-9e1a3c5e7a89",
  "lastName": "Lindner",
  "nextInterview": "2026-11-24T09:00:00Z",
  "number": 3,
  "phase": "active",
  "phone": "+49 170 55501003",
  "postingId": "4a6c8e0a-2c4e-4a6c-9e0a-2c4e6a8c0e81",
  "postingTitle": "Systemadministrator:in (m/w/d) Microsoft 365",
  "rating": {
    "average": 3.5,
    "count": 2,
    "mine": 3
  },
  "role": "manager",
  "source": "portal",
  "stageChangedAt": "2026-11-12T10:30:00Z",
  "stageId": "0a2c4e6a-8c0e-4a2c-8e6a-8c0e2a4c6e84",
  "updatedAt": "2026-11-12T10:30:00Z",
  "version": 5
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/recruiting/applications/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/reject' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"mail":{"body":"Guten Tag Herr Lindner,\n\nvielen Dank für Ihr Interesse und das offene Gespräch. Wir haben uns für eine andere Bewerberin entschieden.\n\nMit freundlichen Grüßen\nMuster IT-Systemhaus GmbH – Personal","subject":"Ihre Bewerbung als Systemadministrator:in Microsoft 365"},"reason":"Wenig Erfahrung mit Kundenprojekten; Angebot ging an eine andere Bewerberin.","stageId":"6a8c0e2a-4c6e-4a8c-9e2a-4c6e8a0c2e87","version":6}'
```

## Record that the applicant withdrew (managers of the posting)

`POST /api/hr/v1/recruiting/applications/{id}/withdraw`

Module: HR · operationId: `withdrawApplication` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `mail` (ApplicantMail)
  - `body` (string, required): Markdown (max length 50000)
  - `subject` (string, required): Subject of the mail (max length 300)
- `reason` (string): Internal reason (max length 2000)
- `stageId` (string (uuid)): A stage of the phase (default the first)
- `version` (integer): Version of the application the change is based on

Example:

```json
{
  "reason": "Hat telefonisch abgesagt – Stelle beim bisherigen Arbeitgeber angenommen.",
  "stageId": "8c0e2a4c-6e8a-4c0e-8a4c-6e8a0c2e4a88",
  "version": 4
}
```

### Responses

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

Fields of the 200 answer:

- `answers` (object): Answers to the form questions by question key
- `closeReason` (string): Reason given when it was closed
- `closedAt` (string (date-time)): When it was rejected, withdrawn or hired
- `consentAt` (string (date-time)): When the applicant gave the consent
- `consentVersion` (integer): Version of the consent text the applicant accepted (0: none)
- `coverLetter` (string): Cover letter text
- `createdAt` (string (date-time)): When the application was created
- `deleteAfter` (string (date-time)): When the application is deleted
- `email` (string): Applicant's e-mail address
- `employeeId` (string (uuid)): The employee created from it (hired)
- `files` (array of ApplicationFile): Files of the application (single reads)
  - `contentType` (string): Media type of the file
  - `createdAt` (string (date-time)): When the file was added
  - `documentId` (string): Id of the document in DMS
  - `fieldKey` (string): Key of the form question the file answers (role answer)
  - `fileName` (string): File name
  - `id` (string (uuid)): Id of the file
  - `role` (string): What the file is (CV, attachment, answer to a file question, mail attachment) (one of `cv`, `attachment`, `answer`, `mail`)
  - `scanStatus` (string): Result of the malware scan; content is served only when CLEAN (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
  - `sizeBytes` (integer (int64)): Size in bytes
- `firstName` (string): Applicant's first name
- `id` (string (uuid)): Id of the application
- `lastName` (string): Applicant's last name
- `nextInterview` (string (date-time)): Start of the next interview, if any
- `number` (integer): Number of the application, unique in the tenant
- `phase` (string): Phase of the current stage (one of `new`, `active`, `hired`, `rejected`, `withdrawn`)
- `phone` (string): Applicant's phone number
- `postingId` (string (uuid)): Id of the posting applied to
- `postingTitle` (string): Title of the posting
- `rating` (object): Summary of the reviewers' ratings
  - `average` (number): Average score (1–5)
  - `count` (integer): Number of ratings
  - `mine` (integer): The caller's score (0 not rated)
- `role` (string): The caller's role on the posting (one of `viewer`, `reviewer`, `manager`)
- `source` (string): How the application arrived (one of `manual`, `portal`, `api`)
- `stageChangedAt` (string (date-time)): When the application entered its current stage
- `stageId` (string (uuid)): Id of the current pipeline stage
- `talentPoolUntil` (string (date-time)): Kept in the talent pool until then (applicant agreed)
- `updatedAt` (string (date-time)): When the application was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "answers": {
    "fruehester_start": "2027-01-01",
    "gehaltsvorstellung": 52000,
    "powershell": "grundlagen"
  },
  "consentAt": "2026-11-02T18:43:00Z",
  "consentVersion": 2,
  "coverLetter": "Ich bin Fachinformatiker für Systemintegration und möchte mich nach vier Jahren im Rechenzentrum stärker auf Cloud-Arbeitsplätze spezialisieren.",
  "createdAt": "2026-11-02T18:43:00Z",
  "deleteAfter": "2027-11-02T18:43:00Z",
  "email": "stefan.lindner@mail.example",
  "files": [
    {
      "contentType": "application/pdf",
      "createdAt": "2026-11-02T18:41:00Z",
      "documentId": "5c7e9a1c-3e5a-4c7e-9a9c-3e5a7c9e1a95",
      "fileName": "lebenslauf-stefan-lindner.pdf",
      "id": "3a5c7e9a-1c3e-4a5c-8e7a-1c3e5a7c9e94",
      "role": "cv",
      "scanStatus": "CLEAN",
      "sizeBytes": 248311
    }
  ],
  "firstName": "Stefan",
  "id": "1c3e5a7c-9e1a-4c3e-9a5c-9e1a3c5e7a89",
  "lastName": "Lindner",
  "nextInterview": "2026-11-24T09:00:00Z",
  "number": 3,
  "phase": "active",
  "phone": "+49 170 55501003",
  "postingId": "4a6c8e0a-2c4e-4a6c-9e0a-2c4e6a8c0e81",
  "postingTitle": "Systemadministrator:in (m/w/d) Microsoft 365",
  "rating": {
    "average": 3.5,
    "count": 2,
    "mine": 3
  },
  "role": "manager",
  "source": "portal",
  "stageChangedAt": "2026-11-12T10:30:00Z",
  "stageId": "0a2c4e6a-8c0e-4a2c-8e6a-8c0e2a4c6e84",
  "updatedAt": "2026-11-12T10:30:00Z",
  "version": 5
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/recruiting/applications/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/withdraw' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"reason":"Hat telefonisch abgesagt – Stelle beim bisherigen Arbeitgeber angenommen.","stageId":"8c0e2a4c-6e8a-4c0e-8a4c-6e8a0c2e4a88","version":4}'
```

## Employee data pre-filled from an application (managers of the posting)

`GET /api/hr/v1/recruiting/applications/{id}/hire`

Module: HR · operationId: `getHireDraft` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Draft (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `email` (string): Applicant's e-mail address
- `firstName` (string): Applicant's first name
- `lastName` (string): Applicant's last name
- `orgUnitId` (string (uuid)): Org unit of the posting, if it has one
- `phone` (string): Applicant's phone number

Example 200 answer:

```json
{
  "email": "miriam.auer@mail.example",
  "firstName": "Miriam",
  "lastName": "Auer",
  "orgUnitId": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
  "phone": "+49 151 55501004"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/recruiting/applications/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/hire' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Complete a hire with the employee created from the application (managers of the posting)

`POST /api/hr/v1/recruiting/applications/{id}/hire`

Module: HR · operationId: `hireApplicant` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

Create the employee first (`createEmployee`). The application moves to the hired phase and its files join the employee's Personalakte in the DMS.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `employeeId` (string (uuid), required): Id of the employee created from the application
- `stageId` (string (uuid)): A stage of the hired phase (default the first)
- `version` (integer): Version of the application the hire is based on

Example:

```json
{
  "employeeId": "9c1e3a5c-7e9a-4c1e-9a5c-7e9a1c3e5a97",
  "stageId": "4e6a8c0e-2a4c-4e6a-8c0e-2a4c6e8a0c86",
  "version": 7
}
```

### Responses

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

Fields of the 200 answer:

- `answers` (object): Answers to the form questions by question key
- `closeReason` (string): Reason given when it was closed
- `closedAt` (string (date-time)): When it was rejected, withdrawn or hired
- `consentAt` (string (date-time)): When the applicant gave the consent
- `consentVersion` (integer): Version of the consent text the applicant accepted (0: none)
- `coverLetter` (string): Cover letter text
- `createdAt` (string (date-time)): When the application was created
- `deleteAfter` (string (date-time)): When the application is deleted
- `email` (string): Applicant's e-mail address
- `employeeId` (string (uuid)): The employee created from it (hired)
- `files` (array of ApplicationFile): Files of the application (single reads)
  - `contentType` (string): Media type of the file
  - `createdAt` (string (date-time)): When the file was added
  - `documentId` (string): Id of the document in DMS
  - `fieldKey` (string): Key of the form question the file answers (role answer)
  - `fileName` (string): File name
  - `id` (string (uuid)): Id of the file
  - `role` (string): What the file is (CV, attachment, answer to a file question, mail attachment) (one of `cv`, `attachment`, `answer`, `mail`)
  - `scanStatus` (string): Result of the malware scan; content is served only when CLEAN (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
  - `sizeBytes` (integer (int64)): Size in bytes
- `firstName` (string): Applicant's first name
- `id` (string (uuid)): Id of the application
- `lastName` (string): Applicant's last name
- `nextInterview` (string (date-time)): Start of the next interview, if any
- `number` (integer): Number of the application, unique in the tenant
- `phase` (string): Phase of the current stage (one of `new`, `active`, `hired`, `rejected`, `withdrawn`)
- `phone` (string): Applicant's phone number
- `postingId` (string (uuid)): Id of the posting applied to
- `postingTitle` (string): Title of the posting
- `rating` (object): Summary of the reviewers' ratings
  - `average` (number): Average score (1–5)
  - `count` (integer): Number of ratings
  - `mine` (integer): The caller's score (0 not rated)
- `role` (string): The caller's role on the posting (one of `viewer`, `reviewer`, `manager`)
- `source` (string): How the application arrived (one of `manual`, `portal`, `api`)
- `stageChangedAt` (string (date-time)): When the application entered its current stage
- `stageId` (string (uuid)): Id of the current pipeline stage
- `talentPoolUntil` (string (date-time)): Kept in the talent pool until then (applicant agreed)
- `updatedAt` (string (date-time)): When the application was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "answers": {
    "fruehester_start": "2027-01-01",
    "gehaltsvorstellung": 52000,
    "powershell": "grundlagen"
  },
  "consentAt": "2026-11-02T18:43:00Z",
  "consentVersion": 2,
  "coverLetter": "Ich bin Fachinformatiker für Systemintegration und möchte mich nach vier Jahren im Rechenzentrum stärker auf Cloud-Arbeitsplätze spezialisieren.",
  "createdAt": "2026-11-02T18:43:00Z",
  "deleteAfter": "2027-11-02T18:43:00Z",
  "email": "stefan.lindner@mail.example",
  "files": [
    {
      "contentType": "application/pdf",
      "createdAt": "2026-11-02T18:41:00Z",
      "documentId": "5c7e9a1c-3e5a-4c7e-9a9c-3e5a7c9e1a95",
      "fileName": "lebenslauf-stefan-lindner.pdf",
      "id": "3a5c7e9a-1c3e-4a5c-8e7a-1c3e5a7c9e94",
      "role": "cv",
      "scanStatus": "CLEAN",
      "sizeBytes": 248311
    }
  ],
  "firstName": "Stefan",
  "id": "1c3e5a7c-9e1a-4c3e-9a5c-9e1a3c5e7a89",
  "lastName": "Lindner",
  "nextInterview": "2026-11-24T09:00:00Z",
  "number": 3,
  "phase": "active",
  "phone": "+49 170 55501003",
  "postingId": "4a6c8e0a-2c4e-4a6c-9e0a-2c4e6a8c0e81",
  "postingTitle": "Systemadministrator:in (m/w/d) Microsoft 365",
  "rating": {
    "average": 3.5,
    "count": 2,
    "mine": 3
  },
  "role": "manager",
  "source": "portal",
  "stageChangedAt": "2026-11-12T10:30:00Z",
  "stageId": "0a2c4e6a-8c0e-4a2c-8e6a-8c0e2a4c6e84",
  "updatedAt": "2026-11-12T10:30:00Z",
  "version": 5
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/recruiting/applications/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/hire' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"employeeId":"9c1e3a5c-7e9a-4c1e-9a5c-7e9a1c3e5a97","stageId":"4e6a8c0e-2a4c-4e6a-8c0e-2a4c6e8a0c86","version":7}'
```

## What happened to an application

`GET /api/hr/v1/recruiting/applications/{id}/history`

Module: HR · operationId: `getApplicationHistory` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** History, oldest first (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of ApplicationHistoryEntry): What happened, oldest first
  - `action` (string): created, updated, move, reopen, rejected, withdrawn, hired, file_added, file_removed, mail_sent, mail_received, mail_files_skipped, interview_scheduled, interview_invited, interview_confirmed, interview_declined, interview_cancelled
  - `actorName` (string): Display name of who did it
  - `actorRef` (string): Who did it (e-mail; the applicant for their own actions)
  - `at` (string (date-time)): When it happened
  - `detail` (object): Further facts of the action
  - `fromStageId` (string (uuid)): Stage before a move
  - `toStageId` (string (uuid)): Stage after a move

Example 200 answer:

```json
{
  "items": [
    {
      "action": "created",
      "actorName": "Stefan Lindner",
      "actorRef": "stefan.lindner@mail.example",
      "at": "2026-11-02T18:43:00Z",
      "toStageId": "6c8e0a2c-4e6a-4c8e-8a2c-4e6a8c0e2a82"
    },
    {
      "action": "move",
      "actorName": "Tobias Hartl",
      "actorRef": "tobias.hartl@muster-it.example",
      "at": "2026-11-05T08:50:00Z",
      "fromStageId": "6c8e0a2c-4e6a-4c8e-8a2c-4e6a8c0e2a82",
      "toStageId": "8e0a2c4e-6a8c-4e0a-9c4e-6a8c0e2a4c83"
    },
    {
      "action": "move",
      "actorName": "Tobias Hartl",
      "actorRef": "tobias.hartl@muster-it.example",
      "at": "2026-11-12T10:30:00Z",
      "fromStageId": "8e0a2c4e-6a8c-4e0a-9c4e-6a8c0e2a4c83",
      "toStageId": "0a2c4e6a-8c0e-4a2c-8e6a-8c0e2a4c6e84"
    },
    {
      "action": "interview_scheduled",
      "actorName": "Tobias Hartl",
      "actorRef": "tobias.hartl@muster-it.example",
      "at": "2026-11-12T10:34:00Z",
      "detail": {
        "interviewId": "5a7c9e1a-3c5e-4a7c-9e1a-3c5e7a9c1e98",
        "startsAt": "2026-11-24T09:00:00Z"
      }
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/recruiting/applications/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/history' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Add a file to an application (managers of the posting)

`POST /api/hr/v1/recruiting/applications/{id}/files`

Module: HR · operationId: `uploadApplicationFile` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

PDF, Word, OpenDocument text or a photo of at most 10 MB as multipart field `file`, at most 10 files per
application. The file is stored in the DMS, which scans it for malware: until the scan is `CLEAN` it is not
served; an `INFECTED` file is refused (`422 infected`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`multipart/form-data` (required)

- `file` (string (binary), required): The file
- `fieldKey` (string): The file question the file answers (role answer)
- `role` (string): What the file is (one of `cv`, `attachment`, `answer`; default `"attachment"`)

### Responses

- **201** Stored (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **413** Error (`application/json`)
- **422** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 201 answer:

- `contentType` (string): Media type of the file
- `createdAt` (string (date-time)): When the file was added
- `documentId` (string): Id of the document in DMS
- `fieldKey` (string): Key of the form question the file answers (role answer)
- `fileName` (string): File name
- `id` (string (uuid)): Id of the file
- `role` (string): What the file is (CV, attachment, answer to a file question, mail attachment) (one of `cv`, `attachment`, `answer`, `mail`)
- `scanStatus` (string): Result of the malware scan; content is served only when CLEAN (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
- `sizeBytes` (integer (int64)): Size in bytes

Example 201 answer:

```json
{
  "contentType": "application/pdf",
  "createdAt": "2026-11-02T18:41:00Z",
  "documentId": "5c7e9a1c-3e5a-4c7e-9a9c-3e5a7c9e1a95",
  "fileName": "lebenslauf-stefan-lindner.pdf",
  "id": "3a5c7e9a-1c3e-4a5c-8e7a-1c3e5a7c9e94",
  "role": "cv",
  "scanStatus": "CLEAN",
  "sizeBytes": 248311
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/recruiting/applications/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/files' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@document.pdf'
```

## Remove a file from an application (managers of the posting)

`DELETE /api/hr/v1/recruiting/applications/{id}/files/{fileId}`

Module: HR · operationId: `deleteApplicationFile` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `fileId` | path | string (uuid) | yes |  |

### Responses

- **204** Removed
- **403** Error (`application/json`)
- **404** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/hr/v1/recruiting/applications/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/files/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## The content of a file the malware scan cleared

`GET /api/hr/v1/recruiting/applications/{id}/files/{fileId}/content`

Module: HR · operationId: `getApplicationFileContent` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

`409 scan_pending` while the scan runs, `422 infected` or `422 scan_failed` (also when nothing scanned it).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `fileId` | path | string (uuid) | yes |  |

### Responses

- **200** The file (`application/octet-stream`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/recruiting/applications/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/files/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/content' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Internal notes of an application (reviewers and managers of the posting)

`GET /api/hr/v1/recruiting/applications/{id}/notes`

Module: HR · operationId: `listApplicationNotes` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Notes, oldest first (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of ApplicationNote): Notes of the application
  - `authorName` (string): Display name of who wrote the note
  - `authorRef` (string): Who wrote the note (e-mail)
  - `body` (string): Text of the note
  - `createdAt` (string (date-time)): When the note was written
  - `id` (string (uuid)): Id of the note

Example 200 answer:

```json
{
  "items": [
    {
      "authorName": "Julia Hagen",
      "authorRef": "julia.hagen@muster-it.example",
      "body": "Telefonat am Montag: freundlich, technisch solide bei Entra ID und Conditional Access, PowerShell eher Grundlagen.",
      "createdAt": "2026-11-09T15:20:00Z",
      "id": "7c9e1a3c-5e7a-4c9e-9a3c-5e7a9c1e3a99"
    },
    {
      "authorName": "Tobias Hartl",
      "authorRef": "tobias.hartl@muster-it.example",
      "body": "Wir laden zum Fachgespräch mit Marie und Jonas ein.",
      "createdAt": "2026-11-12T10:28:00Z",
      "id": "9e1a3c5e-7a9c-4e1a-8c5e-7a9c1e3a5c9a"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/recruiting/applications/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/notes' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Add an internal note (reviewers and managers of the posting)

`POST /api/hr/v1/recruiting/applications/{id}/notes`

Module: HR · operationId: `addApplicationNote` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `body` (string, required): Text of the note (at most 20000 characters) (max length 20000)

Example:

```json
{
  "body": "Wir laden zum Fachgespräch mit Marie und Jonas ein."
}
```

### Responses

- **201** Added (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 201 answer:

- `authorName` (string): Display name of who wrote the note
- `authorRef` (string): Who wrote the note (e-mail)
- `body` (string): Text of the note
- `createdAt` (string (date-time)): When the note was written
- `id` (string (uuid)): Id of the note

Example 201 answer:

```json
{
  "authorName": "Julia Hagen",
  "authorRef": "julia.hagen@muster-it.example",
  "body": "Telefonat am Montag: freundlich, technisch solide bei Entra ID und Conditional Access, PowerShell eher Grundlagen.",
  "createdAt": "2026-11-09T15:20:00Z",
  "id": "7c9e1a3c-5e7a-4c9e-9a3c-5e7a9c1e3a99"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/recruiting/applications/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/notes' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"body":"Wir laden zum Fachgespräch mit Marie und Jonas ein."}'
```

## Delete one of the caller's own notes

`DELETE /api/hr/v1/recruiting/applications/{id}/notes/{noteId}`

Module: HR · operationId: `deleteApplicationNote` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `noteId` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **404** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/hr/v1/recruiting/applications/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/notes/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## The reviewers' ratings of an application (reviewers and managers of the posting)

`GET /api/hr/v1/recruiting/applications/{id}/ratings`

Module: HR · operationId: `listApplicationRatings` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Ratings (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of ApplicationRating): The reviewers' ratings
  - `comment` (string): The reviewer's comment
  - `reviewerName` (string): Display name of who rated
  - `reviewerRef` (string): Who rated (e-mail)
  - `score` (integer): Score from 1 to 5 (max 5)
  - `updatedAt` (string (date-time)): When the rating was last changed

Example 200 answer:

```json
{
  "items": [
    {
      "comment": "Gutes Gespräch, lernbereit.",
      "reviewerName": "Julia Hagen",
      "reviewerRef": "julia.hagen@muster-it.example",
      "score": 4,
      "updatedAt": "2026-11-09T15:22:00Z"
    },
    {
      "comment": "Wenig Erfahrung mit Kundenprojekten.",
      "reviewerName": "Tobias Hartl",
      "reviewerRef": "tobias.hartl@muster-it.example",
      "score": 3,
      "updatedAt": "2026-11-12T10:29:00Z"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/recruiting/applications/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/ratings' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## The default text of a mail to the applicant (managers of the posting)

`GET /api/hr/v1/recruiting/applications/{id}/mail-draft`

Module: HR · operationId: `getApplicationMailDraft` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `kind` | query | string | yes | (one of `confirmation`, `rejection`, `message`) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Subject and Markdown body (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `body` (string, required): Markdown (max length 50000)
- `subject` (string, required): Subject of the mail (max length 300)

Example 200 answer:

```json
{
  "body": "Guten Tag Herr Lindner,\n\nvielen Dank für Ihr Interesse und das offene Gespräch. Wir haben uns für eine andere Bewerberin entschieden.\n\nMit freundlichen Grüßen\nMuster IT-Systemhaus GmbH – Personal",
  "subject": "Ihre Bewerbung als Systemadministrator:in Microsoft 365"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/recruiting/applications/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/mail-draft?kind=confirmation' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## The mail conversation with the applicant

`GET /api/hr/v1/recruiting/applications/{id}/messages`

Module: HR · operationId: `listApplicationMessages` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

Mail sent from the recruiting mailbox and the applicant's answers to it (matched by the reply address, else by the sender's only open application).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Messages, oldest first (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of ApplicationMessage): Mails of the conversation
  - `authorName` (string): Display name of who sent the mail
  - `authorRef` (string): Who sent the mail (e-mail)
  - `body` (string): Markdown (out) or text (in); links of interview invitations are left out
  - `createdAt` (string (date-time)): When the mail was sent or received
  - `deliveryDetail` (string): Details of a failed delivery
  - `deliveryState` (string): Delivery state reported by comms (one of `queued`, `sent`, `failed`, `received`)
  - `direction` (string): out: sent to the applicant, in: received from them (one of `out`, `in`)
  - `fromAddress` (string): Sender address of a received mail
  - `id` (string (uuid)): Id of the mail
  - `kind` (string): What the mail is about (one of `confirmation`, `rejection`, `message`, `interview`, `reply`)
  - `subject` (string): Subject of the mail

Example 200 answer:

```json
{
  "items": [
    {
      "body": "Guten Tag Herr Lindner,\n\nvielen Dank für Ihre Bewerbung. Wir melden uns in den nächsten Tagen bei Ihnen.",
      "createdAt": "2026-11-02T18:44:00Z",
      "deliveryState": "sent",
      "direction": "out",
      "id": "3c5e7a9c-1e3a-4c5e-8a7c-1e3a5c7e9a9c",
      "kind": "confirmation",
      "subject": "Ihre Bewerbung bei der Muster IT-Systemhaus GmbH"
    },
    {
      "authorName": "Tobias Hartl",
      "authorRef": "tobias.hartl@muster-it.example",
      "body": "Guten Tag Herr Lindner,\n\nkönnten Sie uns noch Ihr letztes Arbeitszeugnis schicken?",
      "createdAt": "2026-11-10T09:05:00Z",
      "deliveryState": "sent",
      "direction": "out",
      "id": "1a3c5e7a-9c1e-4a3c-9e5a-9c1e3a5c7e9b",
      "kind": "message",
      "subject": "Ihre Bewerbung – Unterlagen"
    },
    {
      "body": "Guten Tag Herr Hartl,\n\nanbei das Zeugnis.\n\nViele Grüße\nStefan Lindner",
      "createdAt": "2026-11-10T19:32:00Z",
      "deliveryState": "received",
      "direction": "in",
      "fromAddress": "stefan.lindner@mail.example",
      "id": "5e7a9c1e-3a5c-4e7a-8c9e-3a5c7e9a1c9d",
      "kind": "reply",
      "subject": "AW: Ihre Bewerbung – Unterlagen"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/recruiting/applications/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/messages' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Mail the applicant from the recruiting mailbox (managers of the posting)

`POST /api/hr/v1/recruiting/applications/{id}/messages`

Module: HR · operationId: `sendApplicationMessage` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `body` (string, required): Markdown (max length 50000)
- `subject` (string, required): Subject of the mail (max length 300)
- `kind` (string): message, or confirmation for the receipt confirmation (one of `message`, `confirmation`; default `"message"`)

Example:

```json
{
  "body": "Guten Tag Herr Lindner,\n\nkönnten Sie uns noch Ihr letztes Arbeitszeugnis schicken?\n\nViele Grüße\nMuster IT-Systemhaus GmbH – Personal",
  "kind": "message",
  "subject": "Ihre Bewerbung – Unterlagen"
}
```

### Responses

- **201** Queued (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 201 answer:

- `authorName` (string): Display name of who sent the mail
- `authorRef` (string): Who sent the mail (e-mail)
- `body` (string): Markdown (out) or text (in); links of interview invitations are left out
- `createdAt` (string (date-time)): When the mail was sent or received
- `deliveryDetail` (string): Details of a failed delivery
- `deliveryState` (string): Delivery state reported by comms (one of `queued`, `sent`, `failed`, `received`)
- `direction` (string): out: sent to the applicant, in: received from them (one of `out`, `in`)
- `fromAddress` (string): Sender address of a received mail
- `id` (string (uuid)): Id of the mail
- `kind` (string): What the mail is about (one of `confirmation`, `rejection`, `message`, `interview`, `reply`)
- `subject` (string): Subject of the mail

Example 201 answer:

```json
{
  "authorName": "Tobias Hartl",
  "authorRef": "tobias.hartl@muster-it.example",
  "body": "Guten Tag Herr Lindner,\n\nkönnten Sie uns noch Ihr letztes Arbeitszeugnis schicken?\n\nViele Grüße\nMuster IT-Systemhaus GmbH – Personal",
  "createdAt": "2026-11-10T09:05:00Z",
  "deliveryState": "sent",
  "direction": "out",
  "id": "1a3c5e7a-9c1e-4a3c-9e5a-9c1e3a5c7e9b",
  "kind": "message",
  "subject": "Ihre Bewerbung – Unterlagen"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/recruiting/applications/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/messages' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"body":"Guten Tag Herr Lindner,\n\nkönnten Sie uns noch Ihr letztes Arbeitszeugnis schicken?\n\nViele Grüße\nMuster IT-Systemhaus GmbH – Personal","kind":"message","subject":"Ihre Bewerbung – Unterlagen"}'
```

## Interviews of an application (reviewers and managers of the posting)

`GET /api/hr/v1/recruiting/applications/{id}/interviews`

Module: HR · operationId: `listApplicationInterviews` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Interviews (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Interview): Interviews of the application
  - `applicantName` (string): Only in listMyInterviews
  - `applicationId` (string (uuid)): Id of the application
  - `attendees` (array of string (uuid)): Employee ids of the interviewers
  - `createdAt` (string (date-time)): When the interview was created
  - `durationMin` (integer): Length in minutes
  - `id` (string (uuid)): Id of the interview
  - `location` (string): Address for on-site interviews
  - `message` (string): Message to the applicant in the invitation
  - `mode` (string): How the interview takes place (one of `onsite`, `video`, `phone`)
  - `postingTitle` (string): Only in listMyInterviews
  - `respondedAt` (string (date-time)): When the applicant answered
  - `responseNote` (string): The applicant's note with their answer
  - `startsAt` (string (date-time)): Start of the interview
  - `state` (string): The applicant's answer or the cancellation (one of `invited`, `confirmed`, `declined`, `cancelled`)
  - `updatedAt` (string (date-time)): When the interview was last changed
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
  - `videoUrl` (string): Link of a video interview

Example 200 answer:

```json
{
  "items": [
    {
      "applicationId": "1c3e5a7c-9e1a-4c3e-9a5c-9e1a3c5e7a89",
      "attendees": [
        "9b1d3f5a-7c9e-4b1d-8f3a-5c7e9b1d3f2e",
        "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c"
      ],
      "createdAt": "2026-11-12T10:34:00Z",
      "durationMin": 90,
      "id": "5a7c9e1a-3c5e-4a7c-9e1a-3c5e7a9c1e98",
      "location": "Muster IT-Systemhaus GmbH, Industriestraße 12, 93055 Regensburg, Besprechungsraum 2",
      "mode": "onsite",
      "respondedAt": "2026-11-12T20:15:00Z",
      "startsAt": "2026-11-24T09:00:00Z",
      "state": "confirmed",
      "updatedAt": "2026-11-12T20:15:00Z",
      "version": 2
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/recruiting/applications/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/interviews' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Schedule an interview of an open application (managers of the posting)

`POST /api/hr/v1/recruiting/applications/{id}/interviews`

Module: HR · operationId: `scheduleInterview` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

With `notify` the applicant gets an invitation from the recruiting mailbox with a link to confirm or decline (valid until a week after the appointment).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `startsAt` (string (date-time), required): Start of the interview
- `attendees` (array of string (uuid)): Employees taking part
- `durationMin` (integer): Length in minutes (default `60`; max 600)
- `location` (string): Address for on-site interviews (max length 500)
- `message` (string): Added to the invitation (max length 5000)
- `mode` (string): How the interview takes place (one of `onsite`, `video`, `phone`; default `"onsite"`)
- `notify` (boolean): Mail the applicant
- `version` (integer): Version of the interview a change is based on (ignored when scheduling)
- `videoUrl` (string): https link (required for video)

Example:

```json
{
  "attendees": [
    "9b1d3f5a-7c9e-4b1d-8f3a-5c7e9b1d3f2e",
    "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c"
  ],
  "durationMin": 90,
  "location": "Muster IT-Systemhaus GmbH, Industriestraße 12, 93055 Regensburg, Besprechungsraum 2",
  "message": "Fachgespräch mit der Technik, anschließend ein kurzer Rundgang durch das Büro.",
  "mode": "onsite",
  "notify": true,
  "startsAt": "2026-11-24T09:00:00Z"
}
```

### Responses

- **201** Scheduled (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `applicantName` (string): Only in listMyInterviews
- `applicationId` (string (uuid)): Id of the application
- `attendees` (array of string (uuid)): Employee ids of the interviewers
- `createdAt` (string (date-time)): When the interview was created
- `durationMin` (integer): Length in minutes
- `id` (string (uuid)): Id of the interview
- `location` (string): Address for on-site interviews
- `message` (string): Message to the applicant in the invitation
- `mode` (string): How the interview takes place (one of `onsite`, `video`, `phone`)
- `postingTitle` (string): Only in listMyInterviews
- `respondedAt` (string (date-time)): When the applicant answered
- `responseNote` (string): The applicant's note with their answer
- `startsAt` (string (date-time)): Start of the interview
- `state` (string): The applicant's answer or the cancellation (one of `invited`, `confirmed`, `declined`, `cancelled`)
- `updatedAt` (string (date-time)): When the interview was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `videoUrl` (string): Link of a video interview

Example 201 answer:

```json
{
  "applicationId": "1c3e5a7c-9e1a-4c3e-9a5c-9e1a3c5e7a89",
  "attendees": [
    "9b1d3f5a-7c9e-4b1d-8f3a-5c7e9b1d3f2e",
    "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c"
  ],
  "createdAt": "2026-11-12T10:34:00Z",
  "durationMin": 90,
  "id": "5a7c9e1a-3c5e-4a7c-9e1a-3c5e7a9c1e98",
  "location": "Muster IT-Systemhaus GmbH, Industriestraße 12, 93055 Regensburg, Besprechungsraum 2",
  "message": "Fachgespräch mit der Technik, anschließend ein kurzer Rundgang durch das Büro.",
  "mode": "onsite",
  "respondedAt": "2026-11-12T20:15:00Z",
  "startsAt": "2026-11-24T09:00:00Z",
  "state": "confirmed",
  "updatedAt": "2026-11-12T20:15:00Z",
  "version": 2
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/recruiting/applications/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/interviews' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"attendees":["9b1d3f5a-7c9e-4b1d-8f3a-5c7e9b1d3f2e","f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c"],"durationMin":90,"location":"Muster IT-Systemhaus GmbH, Industriestraße 12, 93055 Regensburg, Besprechungsraum 2","message":"Fachgespräch mit der Technik, anschließend ein kurzer Rundgang durch das Büro.","mode":"onsite","notify":true,"startsAt":"2026-11-24T09:00:00Z"}'
```

## Reschedule or cancel an interview (managers of the posting)

`POST /api/hr/v1/recruiting/applications/{id}/interviews/{interviewId}/{action}`

Module: HR · operationId: `changeInterview` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

A reschedule is a new invitation (links of earlier ones stop working) and takes `InterviewInput`; a cancellation only needs `version` and `notify` (`InterviewCancel`, other fields are ignored).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `interviewId` | path | string (uuid) | yes |  |
| `action` | path | string | yes | (one of `reschedule`, `cancel`) |

### Request body

`application/json` (required)

- `startsAt` (string (date-time), required): Start of the interview
- `attendees` (array of string (uuid)): Employees taking part
- `durationMin` (integer): Length in minutes (default `60`; max 600)
- `location` (string): Address for on-site interviews (max length 500)
- `message` (string): Added to the invitation (max length 5000)
- `mode` (string): How the interview takes place (one of `onsite`, `video`, `phone`; default `"onsite"`)
- `notify` (boolean): Mail the applicant
- `version` (integer): Version of the interview a change is based on (ignored when scheduling)
- `videoUrl` (string): https link (required for video)
- `version` (integer, required): Version of the interview the cancellation is based on
- `notify` (boolean): Mail the applicant that the interview is cancelled

Example:

```json
{
  "attendees": [
    "9b1d3f5a-7c9e-4b1d-8f3a-5c7e9b1d3f2e",
    "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c"
  ],
  "durationMin": 90,
  "message": "Wie besprochen verlegen wir das Gespräch auf Mittwochnachmittag, per Video.",
  "mode": "video",
  "notify": true,
  "startsAt": "2026-11-25T13:00:00Z",
  "version": 2,
  "videoUrl": "https://meet.muster-it.example/fachgespraech-lindner"
}
```

### Responses

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

Fields of the 200 answer:

- `applicantName` (string): Only in listMyInterviews
- `applicationId` (string (uuid)): Id of the application
- `attendees` (array of string (uuid)): Employee ids of the interviewers
- `createdAt` (string (date-time)): When the interview was created
- `durationMin` (integer): Length in minutes
- `id` (string (uuid)): Id of the interview
- `location` (string): Address for on-site interviews
- `message` (string): Message to the applicant in the invitation
- `mode` (string): How the interview takes place (one of `onsite`, `video`, `phone`)
- `postingTitle` (string): Only in listMyInterviews
- `respondedAt` (string (date-time)): When the applicant answered
- `responseNote` (string): The applicant's note with their answer
- `startsAt` (string (date-time)): Start of the interview
- `state` (string): The applicant's answer or the cancellation (one of `invited`, `confirmed`, `declined`, `cancelled`)
- `updatedAt` (string (date-time)): When the interview was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `videoUrl` (string): Link of a video interview

Example 200 answer:

```json
{
  "applicationId": "1c3e5a7c-9e1a-4c3e-9a5c-9e1a3c5e7a89",
  "attendees": [
    "9b1d3f5a-7c9e-4b1d-8f3a-5c7e9b1d3f2e",
    "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c"
  ],
  "createdAt": "2026-11-12T10:34:00Z",
  "durationMin": 90,
  "id": "5a7c9e1a-3c5e-4a7c-9e1a-3c5e7a9c1e98",
  "location": "Muster IT-Systemhaus GmbH, Industriestraße 12, 93055 Regensburg, Besprechungsraum 2",
  "message": "Fachgespräch mit der Technik, anschließend ein kurzer Rundgang durch das Büro.",
  "mode": "onsite",
  "respondedAt": "2026-11-12T20:15:00Z",
  "startsAt": "2026-11-24T09:00:00Z",
  "state": "confirmed",
  "updatedAt": "2026-11-12T20:15:00Z",
  "version": 2
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/recruiting/applications/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/interviews/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/reschedule' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"attendees":["9b1d3f5a-7c9e-4b1d-8f3a-5c7e9b1d3f2e","f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c"],"durationMin":90,"message":"Wie besprochen verlegen wir das Gespräch auf Mittwochnachmittag, per Video.","mode":"video","notify":true,"startsAt":"2026-11-25T13:00:00Z","version":2,"videoUrl":"https://meet.muster-it.example/fachgespraech-lindner"}'
```

## Upcoming interviews the caller takes part in

`GET /api/hr/v1/recruiting/interviews/mine`

Module: HR · operationId: `listMyInterviews` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Responses

- **200** Interviews with applicant and posting (`application/json`)

Fields of the 200 answer:

- `items` (array of Interview): Upcoming interviews of the caller
  - `applicantName` (string): Only in listMyInterviews
  - `applicationId` (string (uuid)): Id of the application
  - `attendees` (array of string (uuid)): Employee ids of the interviewers
  - `createdAt` (string (date-time)): When the interview was created
  - `durationMin` (integer): Length in minutes
  - `id` (string (uuid)): Id of the interview
  - `location` (string): Address for on-site interviews
  - `message` (string): Message to the applicant in the invitation
  - `mode` (string): How the interview takes place (one of `onsite`, `video`, `phone`)
  - `postingTitle` (string): Only in listMyInterviews
  - `respondedAt` (string (date-time)): When the applicant answered
  - `responseNote` (string): The applicant's note with their answer
  - `startsAt` (string (date-time)): Start of the interview
  - `state` (string): The applicant's answer or the cancellation (one of `invited`, `confirmed`, `declined`, `cancelled`)
  - `updatedAt` (string (date-time)): When the interview was last changed
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
  - `videoUrl` (string): Link of a video interview

Example 200 answer:

```json
{
  "items": [
    {
      "applicantName": "Stefan Lindner",
      "applicationId": "1c3e5a7c-9e1a-4c3e-9a5c-9e1a3c5e7a89",
      "attendees": [
        "9b1d3f5a-7c9e-4b1d-8f3a-5c7e9b1d3f2e",
        "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c"
      ],
      "createdAt": "2026-11-12T10:34:00Z",
      "durationMin": 90,
      "id": "5a7c9e1a-3c5e-4a7c-9e1a-3c5e7a9c1e98",
      "location": "Muster IT-Systemhaus GmbH, Industriestraße 12, 93055 Regensburg, Besprechungsraum 2",
      "mode": "onsite",
      "postingTitle": "Systemadministrator:in (m/w/d) Microsoft 365",
      "startsAt": "2026-11-24T09:00:00Z",
      "state": "confirmed",
      "updatedAt": "2026-11-12T20:15:00Z",
      "version": 2
    }
  ]
}
```

### Example request

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

## Active employees by name or e-mail for access lists, contacts and interviewers (hr:recruiting:manage or managers of a posting)

`GET /api/hr/v1/recruiting/people`

Module: HR · operationId: `searchRecruitingPeople` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

At most 20 people with name and e-mail; for people who set up postings without hr:read.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `q` | query | string |  |  |

### Responses

- **200** People (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of object): Matching active employees
  - `email` (string): E-mail address of the employee
  - `id` (string (uuid)): Id of the employee
  - `name` (string): Display name of the employee

Example 200 answer:

```json
{
  "items": [
    {
      "email": "jonas.bauer@muster-it.example",
      "id": "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c",
      "name": "Jonas Bauer"
    },
    {
      "email": "julia.hagen@muster-it.example",
      "id": "0e2a4c6e-8a0c-4e2a-9c6e-8a0c2e4a6c9e",
      "name": "Julia Hagen"
    }
  ]
}
```

### Example request

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

## Received mail of the recruiting mailbox no application claimed (hr:recruiting:manage)

`GET /api/hr/v1/recruiting/unmatched-mail`

Module: HR · operationId: `listUnmatchedApplicantMail` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Responses

- **200** Mails, newest first (`application/json`)

Fields of the 200 answer:

- `items` (array of UnmatchedApplicantMail): Mails no application claimed
  - `commsMailId` (string): Id of the received mail in comms
  - `fromAddress` (string): Sender address
  - `receivedAt` (string (date-time)): When the mail arrived
  - `subject` (string): Subject of the mail

Example 200 answer:

```json
{
  "items": [
    {
      "commsMailId": "7a9c1e3a-5c7e-4a9c-9e3a-5c7e9a1c3e9f",
      "fromAddress": "k.reiter.privat@mail.example",
      "receivedAt": "2026-11-18T21:04:00Z",
      "subject": "Nachreichung Zertifikate"
    }
  ]
}
```

### Example request

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

## File an unmatched mail on an application, or drop it without applicationId (hr:recruiting:manage)

`POST /api/hr/v1/recruiting/unmatched-mail/{mailId}`

Module: HR · operationId: `assignUnmatchedApplicantMail` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `mailId` | path | string | yes |  |

### Request body

`application/json` (required)

- `applicationId` (string (uuid)): Application to file the mail on; omitted: the mail is dropped

Example:

```json
{
  "applicationId": "7e9a1c3e-5a7c-4e9a-9c1e-5a7c9e1a3c96"
}
```

### Responses

- **204** Done
- **404** Error (`application/json`)
- **503** Error (`application/json`)

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/recruiting/unmatched-mail/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"applicationId":"7e9a1c3e-5a7c-4e9a-9c1e-5a7c9e1a3c96"}'
```

# Careers

## A careers page with its open postings (public)

`GET /api/hr/v1/careers/{subdomain}`

Module: HR · operationId: `getCareerSite` · Tag: Careers · Auth: none

Needs no token. Unknown subdomains and switched-off pages answer `404`. Limited to 5 requests per second per client (bursts up to 50).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `subdomain` | path | string | yes | The tenant's subdomain, the address of its careers page (case-insensitive) |

### Responses

- **200** The page and its open postings, newest first (`application/json`)
- **404** Error (`application/json`)
- **429** Error (`application/json`)

Fields of the 200 answer:

- `postings` (array of CareerPosting): Open postings of the page
  - `employmentType` (string): Kind of employment (one of `full_time`, `part_time`, `mini_job`, `apprenticeship`, `internship`, `working_student`, `freelance`)
  - `location` (string): Place of work
  - `number` (integer): The posting number (S-4 → 4), used in the paths
  - `publishedAt` (string (date-time)): When the posting was published
  - `salaryCurrency` (string): Currency of the salary (ISO 4217)
  - `salaryMax` (integer): Upper end of the salary range
  - `salaryMin` (integer): Lower end of the salary range
  - `salaryPeriod` (string): Period the salary refers to (one of `year`, `month`, `hour`)
  - `startDate` (string (date)): Start date (YYYY-MM-DD), if given
  - `title` (string): Title of the posting
  - `validThrough` (string (date-time)): End of the publication window
  - `workplace` (string): Where the work is done (one of `onsite`, `hybrid`, `remote`)
- `site` (CareerPublicSite)
  - `color` (string): Accent colour (#rrggbb), omitted for the default
  - `company` (string): Name of the employer
  - `intro` (string): Markdown
  - `origins` (array of string): Websites that may embed the list
  - `privacyUrl` (string): Link to the privacy policy
  - `title` (string): Title of the careers page

Example 200 answer:

```json
{
  "postings": [
    {
      "employmentType": "full_time",
      "location": "Regensburg",
      "number": 2,
      "publishedAt": "2026-10-05T07:00:00Z",
      "salaryCurrency": "EUR",
      "salaryMax": 46000,
      "salaryMin": 38000,
      "salaryPeriod": "year",
      "startDate": "2026-12-01",
      "title": "Vertriebsmitarbeiter:in Innendienst (m/w/d)",
      "workplace": "onsite"
    },
    {
      "employmentType": "full_time",
      "location": "Regensburg",
      "number": 1,
      "publishedAt": "2026-10-01T07:00:00Z",
      "salaryCurrency": "EUR",
      "salaryMax": 58000,
      "salaryMin": 48000,
      "salaryPeriod": "year",
      "startDate": "2027-01-01",
      "title": "Systemadministrator:in (m/w/d) Microsoft 365",
      "workplace": "hybrid"
    }
  ],
  "site": {
    "color": "#0a7c66",
    "company": "Muster IT-Systemhaus GmbH",
    "intro": "Wir betreuen mit rund 25 Kolleginnen und Kollegen die IT von Mittelstand, Praxen und Kanzleien in Ostbayern.",
    "privacyUrl": "https://www.muster-it.example/datenschutz",
    "title": "Karriere bei Muster IT"
  }
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/careers/muster-gmbh'
```

## The open postings of a careers page (public)

`GET /api/hr/v1/careers/{subdomain}/postings`

Module: HR · operationId: `listCareerPostings` · Tag: Careers · Auth: none

Published postings inside their publication window, newest first. Needs no token.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `subdomain` | path | string | yes | The tenant's subdomain, the address of its careers page (case-insensitive) |

### Responses

- **200** The postings (`application/json`)
- **404** Error (`application/json`)
- **429** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of CareerPosting): Open postings of the page
  - `employmentType` (string): Kind of employment (one of `full_time`, `part_time`, `mini_job`, `apprenticeship`, `internship`, `working_student`, `freelance`)
  - `location` (string): Place of work
  - `number` (integer): The posting number (S-4 → 4), used in the paths
  - `publishedAt` (string (date-time)): When the posting was published
  - `salaryCurrency` (string): Currency of the salary (ISO 4217)
  - `salaryMax` (integer): Upper end of the salary range
  - `salaryMin` (integer): Lower end of the salary range
  - `salaryPeriod` (string): Period the salary refers to (one of `year`, `month`, `hour`)
  - `startDate` (string (date)): Start date (YYYY-MM-DD), if given
  - `title` (string): Title of the posting
  - `validThrough` (string (date-time)): End of the publication window
  - `workplace` (string): Where the work is done (one of `onsite`, `hybrid`, `remote`)

Example 200 answer:

```json
{
  "items": [
    {
      "employmentType": "full_time",
      "location": "Regensburg",
      "number": 2,
      "publishedAt": "2026-10-05T07:00:00Z",
      "salaryCurrency": "EUR",
      "salaryMax": 46000,
      "salaryMin": 38000,
      "salaryPeriod": "year",
      "startDate": "2026-12-01",
      "title": "Vertriebsmitarbeiter:in Innendienst (m/w/d)",
      "workplace": "onsite"
    },
    {
      "employmentType": "full_time",
      "location": "Regensburg",
      "number": 1,
      "publishedAt": "2026-10-01T07:00:00Z",
      "salaryCurrency": "EUR",
      "salaryMax": 58000,
      "salaryMin": 48000,
      "salaryPeriod": "year",
      "startDate": "2027-01-01",
      "title": "Systemadministrator:in (m/w/d) Microsoft 365",
      "workplace": "hybrid"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/careers/muster-gmbh/postings'
```

## An open posting with its application form (public)

`GET /api/hr/v1/careers/{subdomain}/postings/{number}`

Module: HR · operationId: `getCareerPosting` · Tag: Careers · Auth: none

The description (Markdown), the questions of the form after the fixed fields and the consent text applicants accept (send its `version` as `consentVersion`). Closed postings and postings outside their window answer `404`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `subdomain` | path | string | yes | The tenant's subdomain, the address of its careers page (case-insensitive) |
| `number` | path | integer | yes | The posting number (S-4 → 4) |

### Responses

- **200** The posting (`application/json`)
- **404** Error (`application/json`)
- **429** Error (`application/json`)

Fields of the 200 answer:

- `employmentType` (string): Kind of employment (one of `full_time`, `part_time`, `mini_job`, `apprenticeship`, `internship`, `working_student`, `freelance`)
- `location` (string): Place of work
- `number` (integer): The posting number (S-4 → 4), used in the paths
- `publishedAt` (string (date-time)): When the posting was published
- `salaryCurrency` (string): Currency of the salary (ISO 4217)
- `salaryMax` (integer): Upper end of the salary range
- `salaryMin` (integer): Lower end of the salary range
- `salaryPeriod` (string): Period the salary refers to (one of `year`, `month`, `hour`)
- `startDate` (string (date)): Start date (YYYY-MM-DD), if given
- `title` (string): Title of the posting
- `validThrough` (string (date-time)): End of the publication window
- `workplace` (string): Where the work is done (one of `onsite`, `hybrid`, `remote`)
- `consent` (object): The data-protection consent applicants accept
  - `privacyUrl` (string): Link to the privacy policy
  - `text` (string): Text of the consent
  - `version` (integer): Send it as consentVersion
- `contact` (string): Name of the contact person
- `description` (string): Markdown
- `form` (array of ApplicationFormField): The questions after the fixed fields
  - `key` (string, required): Lower-case letters, digits, - or _; not a core field (first_name, last_name, email, phone, cover_letter, cv, attachments)
  - `kind` (string, required): Kind of answer (one of `text`, `longtext`, `number`, `date`, `bool`, `select`, `multiselect`, `url`, `file`)
  - `label` (string, required): Question text (max length 300)
  - `help` (string): Help text shown with the question (max length 1000)
  - `options` (array of object): Choices of select and multiselect questions
    - `label` (string): Display text of the choice
    - `value` (string): Stored value of the choice
  - `required` (boolean): An answer is required
- `maxFileBytes` (integer): Largest size of one file in bytes
- `maxFiles` (integer): Most files one application may carry
- `site` (CareerPublicSite)
  - `color` (string): Accent colour (#rrggbb), omitted for the default
  - `company` (string): Name of the employer
  - `intro` (string): Markdown
  - `origins` (array of string): Websites that may embed the list
  - `privacyUrl` (string): Link to the privacy policy
  - `title` (string): Title of the careers page
- `talentPoolMonths` (integer): > 0: applicants may agree to be kept in the talent pool this long

Example 200 answer:

```json
{
  "consent": {
    "dass die Muster IT-Systemhaus GmbH meine Angaben zur Bearbeitung meiner Bewerbung speichert und verarbeitet.": "",
    "privacyUrl": "https://www.muster-it.example/datenschutz",
    "text": "Ich bin einverstanden",
    "version": 2
  },
  "contact": "Tobias Hartl",
  "description": "## Ihre Aufgaben\n- Betrieb und Weiterentwicklung der Microsoft-365-Umgebungen unserer Kunden (Exchange Online, Teams, SharePoint, Intune)\n- Migrationen von On-Premises-Servern in die Cloud",
  "employmentType": "full_time",
  "form": [
    {
      "key": "fruehester_start",
      "kind": "date",
      "label": "Ab wann können Sie bei uns starten?",
      "required": true
    },
    {
      "key": "zertifizierungen",
      "kind": "multiselect",
      "label": "Welche Microsoft-Zertifizierungen haben Sie?",
      "options": [
        {
          "label": "MS-102",
          "value": "ms_102"
        },
        {
          "label": "MD-102",
          "value": "md_102"
        },
        {
          "label": "AZ-104",
          "value": "az_104"
        }
      ],
      "required": false
    }
  ],
  "location": "Regensburg",
  "maxFileBytes": 10485760,
  "maxFiles": 10,
  "number": 1,
  "publishedAt": "2026-10-01T07:00:00Z",
  "salaryCurrency": "EUR",
  "salaryMax": 58000,
  "salaryMin": 48000,
  "salaryPeriod": "year",
  "site": {
    "color": "#0a7c66",
    "company": "Muster IT-Systemhaus GmbH",
    "privacyUrl": "https://www.muster-it.example/datenschutz",
    "title": "Karriere bei Muster IT"
  },
  "startDate": "2027-01-01",
  "talentPoolMonths": 12,
  "title": "Systemadministrator:in (m/w/d) Microsoft 365",
  "workplace": "hybrid"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/careers/muster-gmbh/postings/1'
```

## A captcha challenge for an application (public)

`GET /api/hr/v1/careers/{subdomain}/challenge`

Module: HR · operationId: `getCareerChallenge` · Tag: Careers · Auth: none

An [ALTCHA](https://altcha.org) proof-of-work challenge (SHA-256), valid for 15 minutes. Solve it with the ALTCHA widget or library and send the base64 payload as `altcha` with the application; each challenge counts once. `503 unavailable` when the platform takes no public applications.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `subdomain` | path | string | yes | The tenant's subdomain, the address of its careers page (case-insensitive) |

### Responses

- **200** The challenge (pass it to the ALTCHA widget as is) (`application/json`)
- **404** Error (`application/json`)
- **429** Error (`application/json`)
- **503** Error (`application/json`)

Example 200 answer:

```json
{
  "parameters": {
    "algorithm": "SHA-256",
    "cost": 5000,
    "expiresAt": 1795077900,
    "keyLength": 32,
    "keyPrefix": "00",
    "nonce": "EXAMPLE5f2c8a1d9e4b7",
    "salt": "EXAMPLE3b9e1f7a2c64"
  },
  "signature": "EXAMPLE0c4f8a2e6b1d5f9a3c7e"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/careers/muster-gmbh/challenge'
```

## Apply to an open posting (public)

`POST /api/hr/v1/careers/{subdomain}/postings/{number}/applications`

Module: HR · operationId: `submitCareerApplication` · Tag: Careers · Auth: none

Send JSON, or `multipart/form-data` with the part `application` (the same JSON) first and the files after it: `cv`, `attachment` and `answer.<key>` for file questions; at most 10 files of 10 MB (PDF, Word, OpenDocument, JPEG, PNG, HEIC), 101 MB in all. Files are checked for malware before anybody opens them. The answer is always `202 pending`: the applicant receives a mail with a link that confirms the application within 24 hours; unconfirmed applications are deleted with their files. Errors only report what the applicant can fix. Limited to one request per 20 seconds per client (bursts up to 5) and to a few applications per address and day.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `subdomain` | path | string | yes | The tenant's subdomain, the address of its careers page (case-insensitive) |
| `number` | path | integer | yes |  |

### Request body

`application/json` (required)

- `altcha` (string, required): The solved captcha (base64 payload of the ALTCHA widget)
- `consentVersion` (integer, required): The version of the consent text the applicant accepted – the current one
- `email` (string (email), required): Receives the confirmation link (max length 320)
- `firstName` (string, required): Applicant's first name (max length 200)
- `lastName` (string, required): Applicant's last name (max length 200)
- `answers` (object): Answers by question key; required questions must be answered (file questions with an answer.<key> part)
- `coverLetter` (string): Cover letter text (max length 20000)
- `phone` (string): Applicant's phone number (max length 100)
- `talentPool` (boolean): Agrees to the talent pool
- `website` (string): Honeypot – leave empty (filled in, the application is dropped silently)

Example:

```json
{
  "altcha": "EXAMPLEeyJhbGdvcml0aG0iOiJTSEEtMjU2In0",
  "answers": {
    "fruehester_start": "2027-01-01",
    "zertifizierungen": [
      "ms_102",
      "md_102"
    ]
  },
  "consentVersion": 2,
  "coverLetter": "Als Consultant für Microsoft 365 habe ich zuletzt Tenant-zu-Tenant-Migrationen und Intune-Rollouts geleitet.",
  "email": "katharina.reiter@mail.example",
  "firstName": "Katharina",
  "lastName": "Reiter",
  "phone": "+49 160 55501002",
  "talentPool": true,
  "website": ""
}
```

### Responses

- **202** Accepted; a confirmation mail is on its way (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)
- **413** Error (`application/json`)
- **422** Error (`application/json`)
- **429** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 202 answer:

- `status` (string): Always pending: the applicant confirms with the mailed link (one of `pending`)

Example 202 answer:

```json
{
  "status": "pending"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/careers/muster-gmbh/postings/1/applications' \
  -H 'Content-Type: application/json' \
  --data '{"altcha":"EXAMPLEeyJhbGdvcml0aG0iOiJTSEEtMjU2In0","answers":{"fruehester_start":"2027-01-01","zertifizierungen":["ms_102","md_102"]},"consentVersion":2,"coverLetter":"Als Consultant für Microsoft 365 habe ich zuletzt Tenant-zu-Tenant-Migrationen und Intune-Rollouts geleitet.","email":"katharina.reiter@mail.example","firstName":"Katharina","lastName":"Reiter","phone":"+49 160 55501002","talentPool":true,"website":""}'
```

## Confirm an application with the token of the mail's link (public)

`POST /api/hr/v1/careers/confirm`

Module: HR · operationId: `confirmCareerApplication` · Tag: Careers · Auth: none

The link of the confirmation mail points to the tenant's careers page (`https://<subdomain>.<tenant host domain>/karriere/bestaetigen#t=<token>`); the page sends the token here when the applicant presses the button (never on opening – mail scanners open links). Confirming twice answers the same; `duplicate` means an open application of the address to the posting exists already. Unknown and expired tokens answer `404`.

### Request body

`application/json` (required)

- `token` (string, required): Token of the confirmation link (max length 200)

Example:

```json
{
  "token": "EXAMPLE-confirmation-token-4f9a2c"
}
```

### Responses

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

Fields of the 200 answer:

- `postingNumber` (integer): Number of the posting
- `postingTitle` (string): Title of the posting
- `status` (string): confirmed, or duplicate when an open application to the posting exists already (one of `confirmed`, `duplicate`)

Example 200 answer:

```json
{
  "postingNumber": 1,
  "postingTitle": "Systemadministrator:in (m/w/d) Microsoft 365",
  "status": "confirmed"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/careers/confirm' \
  -H 'Content-Type: application/json' \
  --data '{"token":"EXAMPLE-confirmation-token-4f9a2c"}'
```

# Organisation

## Org units of the tenant (tenant:access)

`GET /api/hr/v1/org-units`

Module: HR · operationId: `listOrgUnits` · Tag: Organisation · Auth: access token (`Authorization: Bearer <accessToken>`)

### Responses

- **200** Units ordered by position and name (`application/json`)

Fields of the 200 answer:

- `items` (array of OrgUnit, required): Org units of the tenant
  - `name` (string, required): Name of the unit (max length 120)
  - `archived` (boolean): Archived: no longer offered for new data, kept for existing data
  - `deputyId` (string): Stands in for the head (decides while the head is away)
  - `headId` (string): Employee who leads the unit (direct manager of its members)
  - `id` (string, read-only): Id of the org unit
  - `memberCount` (integer, read-only): Active employees placed directly in the unit
  - `parentId` (string): Empty = top level
  - `sortOrder` (integer): Position in lists (ascending)
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "items": [
    {
      "archived": false,
      "headId": "5c7e9a1c-3e5a-4c7e-9a1c-5e7a9c1e3a5b",
      "id": "7c9e1a3c-5e7a-4c9e-8a3c-5e7a9c1e3a74",
      "memberCount": 2,
      "name": "Geschäftsführung",
      "sortOrder": 0,
      "version": 1
    },
    {
      "archived": false,
      "deputyId": "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c",
      "headId": "9b1d3f5a-7c9e-4b1d-8f3a-5c7e9b1d3f2e",
      "id": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
      "memberCount": 3,
      "name": "Technik",
      "parentId": "7c9e1a3c-5e7a-4c9e-8a3c-5e7a9c1e3a74",
      "sortOrder": 20,
      "version": 1
    },
    {
      "archived": false,
      "deputyId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "headId": "b2d4f6a8-0c1e-4a3b-9d5f-7e9a1c3b5d04",
      "id": "0c2e4a6c-8e0a-4c2e-9a4c-6e8a0c2e4a71",
      "memberCount": 4,
      "name": "Service Desk",
      "parentId": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
      "sortOrder": 10,
      "version": 2
    }
  ]
}
```

### Example request

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

## Create an org unit (hr:admin)

`POST /api/hr/v1/org-units`

Module: HR · operationId: `createOrgUnit` · Tag: Organisation · Auth: access token (`Authorization: Bearer <accessToken>`)

The parent must be an active unit; nesting is limited to 12 levels. Heads and deputies that would make the chain of command loop are rejected (`400`, field `headId`).

### Request body

`application/json` (required)

- `name` (string, required): Name of the unit (max length 120)
- `archived` (boolean): Archived: no longer offered for new data, kept for existing data
- `deputyId` (string): Stands in for the head (decides while the head is away)
- `headId` (string): Employee who leads the unit (direct manager of its members)
- `id` (string, read-only): Id of the org unit
- `memberCount` (integer, read-only): Active employees placed directly in the unit
- `parentId` (string): Empty = top level
- `sortOrder` (integer): Position in lists (ascending)
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example:

```json
{
  "archived": false,
  "deputyId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "headId": "b2d4f6a8-0c1e-4a3b-9d5f-7e9a1c3b5d04",
  "id": "0c2e4a6c-8e0a-4c2e-9a4c-6e8a0c2e4a71",
  "memberCount": 4,
  "name": "Service Desk",
  "parentId": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
  "sortOrder": 10,
  "version": 2
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `name` (string, required): Name of the unit (max length 120)
- `archived` (boolean): Archived: no longer offered for new data, kept for existing data
- `deputyId` (string): Stands in for the head (decides while the head is away)
- `headId` (string): Employee who leads the unit (direct manager of its members)
- `id` (string, read-only): Id of the org unit
- `memberCount` (integer, read-only): Active employees placed directly in the unit
- `parentId` (string): Empty = top level
- `sortOrder` (integer): Position in lists (ascending)
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 201 answer:

```json
{
  "archived": false,
  "deputyId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "headId": "b2d4f6a8-0c1e-4a3b-9d5f-7e9a1c3b5d04",
  "id": "0c2e4a6c-8e0a-4c2e-9a4c-6e8a0c2e4a71",
  "memberCount": 4,
  "name": "Service Desk",
  "parentId": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
  "sortOrder": 10,
  "version": 2
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/org-units' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"archived":false,"deputyId":"e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02","headId":"b2d4f6a8-0c1e-4a3b-9d5f-7e9a1c3b5d04","id":"0c2e4a6c-8e0a-4c2e-9a4c-6e8a0c2e4a71","memberCount":4,"name":"Service Desk","parentId":"2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72","sortOrder":10,"version":2}'
```

## Change, move or archive an org unit (hr:admin)

`PUT /api/hr/v1/org-units/{id}`

Module: HR · operationId: `updateOrgUnit` · Tag: Organisation · Auth: access token (`Authorization: Bearer <accessToken>`)

A unit with members or active sub-units cannot be archived (`409 in_use`). Sends the `version` read.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `name` (string, required): Name of the unit (max length 120)
- `archived` (boolean): Archived: no longer offered for new data, kept for existing data
- `deputyId` (string): Stands in for the head (decides while the head is away)
- `headId` (string): Employee who leads the unit (direct manager of its members)
- `id` (string, read-only): Id of the org unit
- `memberCount` (integer, read-only): Active employees placed directly in the unit
- `parentId` (string): Empty = top level
- `sortOrder` (integer): Position in lists (ascending)
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example:

```json
{
  "archived": false,
  "deputyId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "headId": "b2d4f6a8-0c1e-4a3b-9d5f-7e9a1c3b5d04",
  "id": "0c2e4a6c-8e0a-4c2e-9a4c-6e8a0c2e4a71",
  "memberCount": 4,
  "name": "Service Desk",
  "parentId": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
  "sortOrder": 10,
  "version": 2
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `name` (string, required): Name of the unit (max length 120)
- `archived` (boolean): Archived: no longer offered for new data, kept for existing data
- `deputyId` (string): Stands in for the head (decides while the head is away)
- `headId` (string): Employee who leads the unit (direct manager of its members)
- `id` (string, read-only): Id of the org unit
- `memberCount` (integer, read-only): Active employees placed directly in the unit
- `parentId` (string): Empty = top level
- `sortOrder` (integer): Position in lists (ascending)
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "archived": false,
  "deputyId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "headId": "b2d4f6a8-0c1e-4a3b-9d5f-7e9a1c3b5d04",
  "id": "0c2e4a6c-8e0a-4c2e-9a4c-6e8a0c2e4a71",
  "memberCount": 4,
  "name": "Service Desk",
  "parentId": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
  "sortOrder": 10,
  "version": 2
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/org-units/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"archived":false,"deputyId":"e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02","headId":"b2d4f6a8-0c1e-4a3b-9d5f-7e9a1c3b5d04","id":"0c2e4a6c-8e0a-4c2e-9a4c-6e8a0c2e4a71","memberCount":4,"name":"Service Desk","parentId":"2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72","sortOrder":10,"version":2}'
```

## Place an employee in an org unit and set or clear their manager override (hr:write)

`PUT /api/hr/v1/employees/{id}/placement`

Module: HR · operationId: `setEmployeePlacement` · Tag: Organisation · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `version` (integer, required): Version of the employee the change is based on
- `managerId` (string): Overrides the unit head as direct manager; empty clears it
- `orgUnitId` (string): Empty removes the employee from their unit

Example:

```json
{
  "managerId": "",
  "orgUnitId": "0c2e4a6c-8e0a-4c2e-9a4c-6e8a0c2e4a71",
  "version": 6
}
```

### Responses

- **200** The updated employee (`application/json`)
- **400** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `addressId` (string, read-only): Person address of the employee in masterdata (roles customer and supplier), kept by HR
- `addressUnmatched` (boolean, read-only): The masterdata address was deleted by the operator's microtech address import and the employee is not matched to a new one yet (addressId is empty; HR does not create one by itself). Omitted when false.
- `createdAt` (string (date-time)): When the employee was created
- `createdBy` (string): Who created the employee (e-mail of the caller)
- `customFields` (object): Values of the tenant-defined fields by field key; restricted fields only with hr:write
- `displayName` (string): Name built from the tenant's display fields (falls back to the e-mail)
- `email` (string): E-mail address; the sign-in identity
- `groupIds` (array of string): Ids of the groups the employee belongs to
- `id` (string): Id of the employee
- `invitationSent` (boolean): Only on create: whether the invitation mail was sent
- `lastLoginAt` (string (date-time)): Last sign-in
- `roleIds` (array of string): Ids of the directly assigned roles
- `status` (string): disabled employees cannot sign in (one of `active`, `disabled`)
- `tenantColor` (string): Only on getMe: the active tenant's colour (a portal tenant colour name such as blue), for the identity stripe of the app; omitted when masterdata does not answer
- `updatedAt` (string (date-time)): When the employee was last changed
- `updatedBy` (string): Who last changed the employee (e-mail of the caller)
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "addressId": "7e9a1c3e-5b7d-4f9a-8c1e-3b5d7f9a1c20",
  "addressUnmatched": false,
  "createdAt": "2023-10-12T09:14:00Z",
  "createdBy": "clara.becker@muster-it.example",
  "customFields": {
    "department": "service",
    "employment_type": "vollzeit",
    "entry_date": "2023-11-02",
    "first_name": "Sophie",
    "last_name": "Huber",
    "personnel_number": "1017",
    "phone": "+49 941 123450-17",
    "position": "Service Desk Agentin"
  },
  "displayName": "Sophie Huber",
  "email": "sophie.huber@muster-it.example",
  "groupIds": [
    "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91"
  ],
  "id": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "lastLoginAt": "2026-11-19T07:28:41Z",
  "roleIds": [
    "13e5a7c9-1d3f-4a5c-9e7a-9b1d3f5a7c82"
  ],
  "status": "active",
  "updatedAt": "2026-09-01T08:02:00Z",
  "updatedBy": "clara.becker@muster-it.example",
  "version": 6
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/employees/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/placement' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"managerId":"","orgUnitId":"0c2e4a6c-8e0a-4c2e-9a4c-6e8a0c2e4a71","version":6}'
```

## Chain of command of an employee (hr:read, the person themself, or their managers and deputies)

`GET /api/hr/v1/employees/{id}/chain`

Module: HR · operationId: `getEmployeeChain` · Tag: Organisation · Auth: access token (`Authorization: Bearer <accessToken>`)

Managers and deputies read the chain of the people in their chain of command; people outside their scope answer `404`. `me` is the caller.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | Employee id or `me` |

### Responses

- **200** Chain (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `chain` (array of PersonRef): Direct manager first
  - `displayName` (string): Display name of the employee
  - `email` (string): E-mail address of the employee
  - `id` (string): Id of the employee
- `employeeId` (string): Id of the employee
- `manager` (PersonRef)
  - `displayName` (string): Display name of the employee
  - `email` (string): E-mail address of the employee
  - `id` (string): Id of the employee
- `responsible` (array of PersonRef): Chain plus deputies
  - `displayName` (string): Display name of the employee
  - `email` (string): E-mail address of the employee
  - `id` (string): Id of the employee
- `unit` (OrgUnit)
  - `name` (string, required): Name of the unit (max length 120)
  - `archived` (boolean): Archived: no longer offered for new data, kept for existing data
  - `deputyId` (string): Stands in for the head (decides while the head is away)
  - `headId` (string): Employee who leads the unit (direct manager of its members)
  - `id` (string, read-only): Id of the org unit
  - `memberCount` (integer, read-only): Active employees placed directly in the unit
  - `parentId` (string): Empty = top level
  - `sortOrder` (integer): Position in lists (ascending)
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "chain": [
    {
      "displayName": "Martin Brandl",
      "email": "martin.brandl@muster-it.example",
      "id": "b2d4f6a8-0c1e-4a3b-9d5f-7e9a1c3b5d04"
    },
    {
      "displayName": "Tobias Hartl",
      "email": "tobias.hartl@muster-it.example",
      "id": "9b1d3f5a-7c9e-4b1d-8f3a-5c7e9b1d3f2e"
    },
    {
      "displayName": "Thomas Pfeiffer",
      "email": "thomas.pfeiffer@muster-it.example",
      "id": "5c7e9a1c-3e5a-4c7e-9a1c-5e7a9c1e3a5b"
    }
  ],
  "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
  "manager": {
    "displayName": "Martin Brandl",
    "email": "martin.brandl@muster-it.example",
    "id": "b2d4f6a8-0c1e-4a3b-9d5f-7e9a1c3b5d04"
  },
  "responsible": [
    {
      "displayName": "Martin Brandl",
      "email": "martin.brandl@muster-it.example",
      "id": "b2d4f6a8-0c1e-4a3b-9d5f-7e9a1c3b5d04"
    },
    {
      "displayName": "Tobias Hartl",
      "email": "tobias.hartl@muster-it.example",
      "id": "9b1d3f5a-7c9e-4b1d-8f3a-5c7e9b1d3f2e"
    },
    {
      "displayName": "Jonas Bauer",
      "email": "jonas.bauer@muster-it.example",
      "id": "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c"
    },
    {
      "displayName": "Thomas Pfeiffer",
      "email": "thomas.pfeiffer@muster-it.example",
      "id": "5c7e9a1c-3e5a-4c7e-9a1c-5e7a9c1e3a5b"
    }
  ],
  "unit": {
    "archived": false,
    "deputyId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
    "headId": "b2d4f6a8-0c1e-4a3b-9d5f-7e9a1c3b5d04",
    "id": "0c2e4a6c-8e0a-4c2e-9a4c-6e8a0c2e4a71",
    "memberCount": 4,
    "name": "Service Desk",
    "parentId": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
    "sortOrder": 10,
    "version": 2
  }
}
```

### Example request

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

## The people and units the signed-in user is responsible for

`GET /api/hr/v1/me/team`

Module: HR · operationId: `getMyTeam` · Tag: Organisation · Auth: access token (`Authorization: Bearer <accessToken>`)

### Responses

- **200** Team (`application/json`)

Fields of the 200 answer:

- `directReports` (array of string): Ids of the people whose direct manager the caller is
- `members` (array of PersonRef): People the caller is responsible for (direct and indirect)
  - `displayName` (string): Display name of the employee
  - `email` (string): E-mail address of the employee
  - `id` (string): Id of the employee
- `units` (array of OrgUnit): Units the caller heads or deputises for
  - `name` (string, required): Name of the unit (max length 120)
  - `archived` (boolean): Archived: no longer offered for new data, kept for existing data
  - `deputyId` (string): Stands in for the head (decides while the head is away)
  - `headId` (string): Employee who leads the unit (direct manager of its members)
  - `id` (string, read-only): Id of the org unit
  - `memberCount` (integer, read-only): Active employees placed directly in the unit
  - `parentId` (string): Empty = top level
  - `sortOrder` (integer): Position in lists (ascending)
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "directReports": [
    "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
    "c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06",
    "d1f3b5c7-9e1a-4d3f-8b5c-7a9e1f3b5d08",
    "0a2c4e6a-8c0e-4a2c-9e4a-6c8e0a2c4e19"
  ],
  "members": [
    {
      "displayName": "Sophie Huber",
      "email": "sophie.huber@muster-it.example",
      "id": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02"
    },
    {
      "displayName": "Elias Gruber",
      "email": "elias.gruber@muster-it.example",
      "id": "c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06"
    },
    {
      "displayName": "Hannah Lehner",
      "email": "hannah.lehner@muster-it.example",
      "id": "d1f3b5c7-9e1a-4d3f-8b5c-7a9e1f3b5d08"
    },
    {
      "displayName": "Noah Fischer",
      "email": "noah.fischer@muster-it.example",
      "id": "0a2c4e6a-8c0e-4a2c-9e4a-6c8e0a2c4e19"
    }
  ],
  "units": [
    {
      "archived": false,
      "deputyId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "headId": "b2d4f6a8-0c1e-4a3b-9d5f-7e9a1c3b5d04",
      "id": "0c2e4a6c-8e0a-4c2e-9a4c-6e8a0c2e4a71",
      "memberCount": 4,
      "name": "Service Desk",
      "parentId": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
      "sortOrder": 10,
      "version": 2
    }
  ]
}
```

### Example request

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

## The colleague directory (tenant:access)

`GET /api/hr/v1/colleagues`

Module: HR · operationId: `listColleagues` · Tag: Organisation · Auth: access token (`Authorization: Bearer <accessToken>`)

The active employees of the caller's tenant, the caller excluded, sorted by the display name: `id`, `displayName`,
`email`, the org unit and only the values of fields marked `visibleToColleagues` (never restricted or switched-off
fields). Needs no `hr:read` – but an active employee record of the caller, else `403 no_employee`. `q` matches every
word on its own (case-insensitive, part of a word) in the e-mail, the display name's fields and the text, phone
and e-mail fields colleagues see.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `q` | query | string |  | Words of the name, e-mail or a field visible to colleagues |
| `limit` | query | integer |  | 1–200; another value is a 400 invalid. (default `50`; max 200) |
| `offset` | query | integer |  | (default `0`) |

### Responses

- **200** A page of colleagues (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Colleague, required): Colleagues of this page
  - `displayName` (string, required): Display name (the e-mail when the name fields are empty)
  - `email` (string, required): E-mail address
  - `fields` (array of ColleagueField, required): Values of the fields visible to colleagues the person has, in the tenant's field order
    - `key` (string, required): Key of the field
    - `kind` (string, required): Kind of the field (FieldDef.kind) (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `url`, `phone`, `email`)
    - `label` (string, required): Label of the field
    - `value` (any, required): The value: a string for text-like, phone, e-mail, date and URL fields, a number, a boolean, the option label of a select or the list of option labels of a multiselect
  - `id` (string, required): Id of the employee
  - `unit` (object): Org unit the colleague is placed in (omitted when none)
    - `id` (string, required): Id of the org unit
    - `name` (string, required): Name of the org unit
- `total` (integer, required): Number of all matching colleagues

Example 200 answer:

```json
{
  "items": [
    {
      "displayName": "Jonas Bauer",
      "email": "jonas.bauer@muster-it.example",
      "fields": [
        {
          "key": "phone",
          "kind": "phone",
          "label": "Telefon",
          "value": "+49 941 123450-21"
        },
        {
          "key": "mobile",
          "kind": "phone",
          "label": "Mobil",
          "value": "+49 160 2230051"
        }
      ],
      "id": "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c",
      "unit": {
        "id": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
        "name": "Technik"
      }
    },
    {
      "displayName": "Sophie Huber",
      "email": "sophie.huber@muster-it.example",
      "fields": [
        {
          "key": "phone",
          "kind": "phone",
          "label": "Telefon",
          "value": "+49 941 123450-17"
        }
      ],
      "id": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "unit": {
        "id": "0c2e4a6c-8e0a-4c2e-9a4c-6e8a0c2e4a71",
        "name": "Service Desk"
      }
    }
  ],
  "total": 2
}
```

### Example request

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

# Auth

## Exchange an API key for an access token

`POST /api/hr/v1/auth/token`

Module: HR · operationId: `exchangeApiKey` · Tag: Auth · Auth: API key (`Authorization: Bearer cck_…`)

Send the API key as `Authorization: Bearer cck_…`. The answer is a token every ConnectCloud API accepts as `Authorization: Bearer <accessToken>`. It lives 15 minutes – never past the key's expiry – carries the key's permissions (personal keys: only those the owner still holds) and `authMethod: apikey`, which never opens sign-in, passkey or key management routes. Reuse it until it expires; there is no refresh. Revoking a key, disabling its owner or service account takes effect at the next exchange. Every refusal answers `401 invalid_api_key`. Rate limited per client.

### Responses

- **200** Access token (`application/json`)
- **401** Error (`application/json`)
- **429** Too many requests
- **503** Error (`application/json`)

Fields of the 200 answer:

- `accessToken` (string, required): JWT; treat it as opaque
- `expiresAt` (string (date-time), required): When the access token expires
- `expiresIn` (integer, required): Seconds
- `tokenType` (string, required): Always Bearer

Example 200 answer:

```json
{
  "accessToken": "EXAMPLE.eyJhdXRoTWV0aG9kIjoiYXBpa2V5In0.EXAMPLE-SIGNATURE",
  "expiresAt": "2026-11-19T09:45:00Z",
  "expiresIn": 900,
  "tokenType": "Bearer"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/auth/token' \
  -H "Authorization: Bearer $CONNECTCLOUD_API_KEY"
```

## Register an OAuth client (dynamic client registration, no sign-in)

`POST /api/hr/v1/oauth/register`

Module: HR · operationId: `registerOAuthClient` · Tag: Auth · Auth: none

RFC 7591 registration for MCP clients (Claude Code, ChatGPT, Cursor …), which then connect to the portal's MCP server as a person or service account. Clients are public: no secret, `token_endpoint_auth_method` is always `none`, PKCE (S256) is required. `client_name` (1–100 characters) and 1–5 `redirect_uris` are needed: `https` URIs, or `http` on `localhost`, `127.0.0.1` or `[::1]` (any port at use time, RFC 8252), never with a fragment or user info. Other metadata is ignored. Errors follow RFC 7591 (`invalid_redirect_uri`, `invalid_client_metadata`). Rate limited per client (1 per second, bursts up to 5).

### Request body

`application/json` (required)

- `client_name` (string, required): (max length 100)
- `redirect_uris` (array of string, required)

Example:

```json
{
  "client_name": "Claude Code",
  "redirect_uris": [
    "http://127.0.0.1:3333/callback"
  ]
}
```

### Responses

- **201** Registered client (`application/json`)
- **400** OAuth error (RFC 6749 §5.2, RFC 7591 §3.2.2) (`application/json`)
- **429** Too many requests

Fields of the 201 answer:

- `client_id` (string)
- `client_name` (string)
- `grant_types` (array of string)
- `redirect_uris` (array of string)
- `response_types` (array of string)
- `token_endpoint_auth_method` (string): (one of `none`)

Example 201 answer:

```json
{
  "client_id": "cco_EXAMPLEQ2xhdWRlQ29kZQ",
  "client_name": "Claude Code",
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "redirect_uris": [
    "http://127.0.0.1:3333/callback"
  ],
  "response_types": [
    "code"
  ],
  "token_endpoint_auth_method": "none"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/oauth/register' \
  -H 'Content-Type: application/json' \
  --data '{"client_name":"Claude Code","redirect_uris":["http://127.0.0.1:3333/callback"]}'
```

## Exchange an authorization code or refresh token for an access token (OAuth, no sign-in)

`POST /api/hr/v1/oauth/token`

Module: HR · operationId: `oauthToken` · Tag: Auth · Auth: none

The OAuth 2.1 token endpoint (form-encoded). `authorization_code` needs `code`, `redirect_uri` (exactly as in the authorization request), `code_verifier` (PKCE S256) and `client_id`; a code lives 60 seconds and is used once – presenting it again revokes its grant. `refresh_token` needs `refresh_token` and `client_id`; every refresh rotates the refresh token (it lives 30 days unused). A rotated refresh token presented again within 5 seconds is only refused; later it revokes the whole grant. The access token works like an exchanged API key token: 15 minutes, `authMethod: oauth`, the current permissions of the person (without `identity:admin` and `tenant:token:generate`; the person must still hold `tenant:token:generate`) or of the service account. Every refusal of a code or refresh token is `invalid_grant`. Rate limited per client address (10 per second, bursts up to 50).
For an app of a tenant (OpenID Provider, AUTH.md "OpenID Provider") the answer is OpenID Connect's: an ES256 `id_token` (pairwise `sub`, `nonce`, `auth_time`, `at_hash`; `name`, `email`, `groups` by scope), an opaque `access_token` the userinfo endpoint alone accepts (15 minutes), `scope`, and a `refresh_token` only with `offline_access`. A confidential app authenticates with `client_secret_basic` or `client_secret_post` (`401 invalid_client` otherwise); PKCE is required for every client.
The first-party mobile app is a public client like MCP (no secret). Its access token is a session token (`authMethod: mobile`, 15 minutes, with the session id `sid`) and every refresh rotates the refresh token. A refused refresh of a mobile grant revokes it and announces `hr.mobile_session.ended`.

### Request body

`application/x-www-form-urlencoded` (required)

- `client_id` (string, required)
- `grant_type` (string, required): (one of `authorization_code`, `refresh_token`)
- `client_secret` (string): A confidential app's secret (client_secret_post; or HTTP Basic)
- `code` (string)
- `code_verifier` (string)
- `redirect_uri` (string)
- `refresh_token` (string)

### Responses

- **200** Tokens (an app's answer adds id_token and scope; refresh_token only with offline_access) (`application/json`)
- **400** OAuth error (RFC 6749 §5.2, RFC 7591 §3.2.2) (`application/json`)
- **401** OAuth error (RFC 6749 §5.2, RFC 7591 §3.2.2) (`application/json`)
- **429** Too many requests
- **503** OAuth error (RFC 6749 §5.2, RFC 7591 §3.2.2) (`application/json`)

Fields of the 200 answer:

- `access_token` (string, required): JWT; treat it as opaque
- `expires_in` (integer, required): Seconds
- `refresh_token` (string, required): The next refresh token; the presented one is used up
- `token_type` (string, required)
- `id_token` (string): Apps only – the ID token (ES256)
- `scope` (string): Apps only – the granted scopes

Example 200 answer:

```json
{
  "access_token": "EXAMPLE.eyJhdXRoTWV0aG9kIjoib2F1dGgifQ.EXAMPLE-SIGNATURE",
  "expires_in": 900,
  "refresh_token": "ccr_EXAMPLE-refresh-token",
  "token_type": "Bearer"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-binary @body
```

