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