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 tenantkey(string, required): Stable key of the typename(string, required): Display nameallowHalfDays(boolean): Half days may be requestedarchived(boolean): Archived: no longer offered for new data, kept for existing datacolor(string): Semantic colour of the type in calendars (one ofprimary,info,success,warning,error,neutral)countsAgainstVacation(boolean): Days of this type are taken from the vacation accounticon(string): Lucide icon (i-lucide-…)id(string): Id of the absence typepaid(boolean): The absence is paid timerequiresApproval(boolean): Requests start as requested and need a decision; otherwise they are approved when enteredsensitive(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 ofcredit,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 holidaysdate(string (date), required): Date (YYYY-MM-DD)fraction(number, required): 1 for a full day, 0.5 for a half day (one of0.5,1)name(string, required): Name of the holidayid(string): Id of the tenant holidayrecurring(boolean): Every year on the same dayversion(integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
employeeCount(integer): Number of employees in the tenantfederalStates(array of FederalState): German states (Bundesländer) to choose fromcode(string): ISO 3166-2 suffix of the state (BW, BY, …)name(string): Name of the state
fields(array of FieldDef): Employee field definitionskey(string, required): Stable key; the key in customFieldskind(string, required): Kind of value;phonetakes digits, spaces and+ ( ) / . -(at least 3 digits,+only first, at most 40 characters),emailthe shapelocal@domain.tld(one oftext,longtext,number,date,datetime,bool,select,multiselect,url,phone,email)label(string, required): Display namearchived(boolean): Archived: no longer offered for new data, kept for existing datadescription(string): Help text of the fieldid(string): Id of the fieldoptions(array of object): Choices of select and multiselect fieldscolor(string): Colour of the choicelabel(string): Display text of the choicevalue(string): Stored value of the choice
required(boolean): A value is requiredrestricted(boolean): Values are visible only to callers with hr:writesection(string): Group in forms; defaults to other (one ofperson,contact,employment,working_time,confidential,other)sortOrder(integer): Position within the sectionstandard(boolean, read-only): From the built-in catalogue; switched on and off with archived, key and kind are fixedversion(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 revokegroups(array of Group): Groups of the tenantname(string, required): Name of the groupdescription(string): Description of the groupid(string): Id of the groupmemberCount(integer, read-only): Number of membersroleIds(array of string, read-only): Ids of the roles the members receiveversion(integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
permissions(array of object): The permission cataloguearea(string): Module or area the permission belongs tocustomerWide(boolean): The permission applies to every tenant of the customerdescription(string): What the permission allowskey(string): Permission name, e.g. hr:readlabel(string): Display name
roles(array of Role): Roles of the tenantname(string, required): Name of the roledescription(string): Description of the roleid(string): Id of the rolekey(string, read-only): Stable key of the rolelocked(boolean, read-only): Built-in role whose permissions cannot be changedmemberCount(integer, read-only): Number of employees holding the rolepermissions(array of string): Permissions of the rolesystemKey(string, read-only): Key of a built-in role, empty for roles of the tenantversion(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 formskey(string): Key of the sectionlabel(string): Display name of the section
settings(Settings)displayFields(array of string): Field keys whose values make up the display name of employeesloginDomains(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 ofcreate_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 forautoEndAtMidnight(boolean): A clock segment nobody clocked out of is ended at 24:00 of its day (tenant time zone) and markedautoEndedfor checking. Off for tenants whose shifts run past midnight. (defaulttrue)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 modeldefaultVacationDays(number): Vacation days per year of employees without a working-time modelfederalState(string): Bundesland code (BW, BY, …); empty = nationwide holidays onlyselfEditDays(integer): Days back employees change their own time without a reasontimeZone(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"