ConnectCloud Developers

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:

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

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

View as Markdown · Interactive reference · OpenAPI