Module

HR & Payroll

Das HR-Modul deckt den Mitarbeiter-Lebenszyklus ab — Stammdaten, Skills, Abwesenheiten, Zertifikate, Onboarding und Offboarding. Payroll integriert sich mit DATEV LODAS.

Resources – HR

Resource	Pfad	Permission-Präfix
Mitarbeiter-Profile	`/api/v1/employee_profiles`	`employee_profile`
Zertifikate	`/api/v1/employee_certifications`	`employee_certification`
Personalakte	`/api/v1/employee_documents`	`employee_document`
Skill-Definitionen	`/api/v1/skill_definitions`	`skill_definition`
Urlaubs-Anträge	`/api/v1/vacation_requests`	`vacation_request`
Krankmeldungen	`/api/v1/sick_leaves`	`sick_leave`

Resources – Schichten & Arbeitszeit

Resource	Pfad	Permission-Präfix
Schicht-Templates	`/api/v1/shift_templates`	`shift_template`
Schicht-Zuweisungen	`/api/v1/shift_assignments`	`shift_assignment`
Schicht-Constraints	`/api/v1/shift_constraint_sets`	`shift_constraint_set`
Schicht-Präferenzen	`/api/v1/shift_preferences`	`shift_preference`
Tausch-Anfragen	`/api/v1/shift_swap_requests`	`shift_swap_request`
Fairness-Verlauf	`/api/v1/shift_fairness_records`	`shift_fairness_record`
Arbeitszeit-Modelle	`/api/v1/working_time_models`	`working_time_model`
Arbeitszeit-Zuweisungen	`/api/v1/working_time_assignments`	`working_time_assignment`

Resources – Payroll

Resource	Pfad	Permission-Präfix	Sequenz
Lohnabrechnungen	`/api/v1/payroll_records`	`payroll_record`	`PAY-`
Abrechnungs-Perioden	`/api/v1/payroll_periods`	`payroll_period`	—
Rückforderungs-Settings	`/api/v1/payroll_recovery_configs`	`payroll_recovery_config`	—
Export-Logs	`/api/v1/payroll_exports`	`payroll_export`	—
LODAS-Settings	`/api/v1/payroll_lodas_settings`	`payroll_lodas_settings`	—
Payroll-Audit	`/api/v1/payroll_audit_events`	`payroll_audit_event`	—

Schemas

Employee

employee_profiles4 Permissions

Schema for validating employee profile entities (Personalstammdaten)

userId uuid optional

User UUID (optional link to users collection)

nullable

firstName string optional

First name (Vorname) — used when no user is linked

max 200 Zeichennullable

lastName string optional

Last name (Nachname) — used when no user is linked

max 200 Zeichennullable

employeeNumber string optional

Auto-generated employee number (e.g. MA-2026-00001)

max 50 Zeichenread-onlynullable

email string optional

Work email address. Used as the matching key for telephony integrations (Starface userlist → starfaceAccountId) so employees WITHOUT a linked user account can still be attributed in call analytics. Plain string (no strict format validation) to keep imports forgiving.

max 320 Zeichennullable

orgUnitId uuid optional

Primary org unit UUID (legacy — use primaryOrgUnitId going forward, ADR 0036b)

nullable

primaryOrgUnitId uuid optional

Arbeitsrechtlich maßgebliche Org-Unit (ADR 0036b). Wird vom Working-Time-Resolver für die Hierarchie-Auflösung benutzt. Bei Matrix-Orgs: eindeutig die primäre. Falls nicht gesetzt, fällt der Resolver auf orgUnitId zurück.

nullable

managerId uuid optional

Direct manager user UUID

nullable

employmentType string erforderlich

Type of employment (Beschäftigungsart)

Werte

FULL_TIMEPART_TIMEMINI_JOBWORKING_STUDENTINTERNFREELANCER

employmentStatus string erforderlich

Current employment status

Werte

ACTIVEONBOARDINGON_LEAVEOFFBOARDINGTERMINATED

Default: "ONBOARDING"

hireDate date erforderlich

First day of employment (ISO 8601 date: YYYY-MM-DD)

probationEndDate date optional

End of probation period (Probezeit)

nullable

terminationDate date optional

Last day of employment

nullable

terminationReason string optional

Reason for termination

max 1000 Zeichennullable

vacationDaysPerYear number optional

Annual vacation entitlement in days

0 – 365nullable

vacationDaysRemaining number optional

Remaining vacation days for current year

≥ 0nullable

vacationDaysCarryOver number optional

Carried over vacation days from previous year (Resturlaub)

≥ 0nullable

weeklySchedule object[] optional

Per-weekday work schedule (Arbeitszeitplanung)

nullable

day number erforderlich

ISO weekday (1=Mon, 7=Sun)

1 – 7

startTime string erforderlich

Work start time (e.g. "08:00")

Pattern

endTime string erforderlich

Work end time (e.g. "17:00")

Pattern

breakMinutes number optional

Break duration in minutes

0 – 480Default: 0

workingTimeModelId uuid optional

Reference to working_time_model entity

nullable

skills object[] optional

Structured skill entries with levels

Default: []

skillId uuid erforderlich

UUID of the skill definition

level string erforderlich

Proficiency level. INTERESTED is a level-0 interest marker (no proficiency, no XP, never satisfies a scheduling minimum). BEGINNER..EXPERT is the legacy 4-tier enum kept in sync with currentLevel. Prefer currentXp/currentLevel for new proficiency logic.

Werte

INTERESTEDBEGINNERINTERMEDIATEADVANCEDEXPERT

currentXp integer optional

Accumulated XP for this skill. Awarded on ticket/task completion or via manual grant. Drives currentLevel.

≥ 0Default: 0nullable

currentLevel integer optional

Numeric level (1–400) across 4 tiers of 100 levels each. Derived from currentXp on XP award, but stored for efficient queries.

0 – 400Default: 0nullable

verifiedAt datetime optional

When the skill was last verified

nullable

verifiedBy uuid optional

User UUID of the person who verified the skill

nullable

source string optional

How the skill was assigned. PERFORMANCE_REVIEW marks interests carried over from a completed Mitarbeitergespräch.

Werte

SELF_ASSESSEDMANAGER_ASSIGNEDCERTIFICATIONAUTO_DETECTEDPERFORMANCE_REVIEW

Default: "SELF_ASSESSED"

addedAt datetime optional

When the skill entry was first added

nullable

updatedAt datetime optional

When the skill entry was last updated (level change, re-verification)

read-onlynullable

languageSkills object[] optional

Spoken/written languages with CEFR proficiency level, used for language-aware ticket dispatch

Default: []

code string erforderlich

ISO 639-1 language code

Werte

aaabaeafakamanarasavayazbabebgbhbibmbnbo

brbscacechcocrcscucvcydadedvdzeeeleneoeseteufafffifjfofrfygagdglgngugvhahehihohrhthuhyhziaidieigiiikioisitiujajvkakgkikjkkklkmknkokrkskukvkwkylalblglilnloltlulvmgmhmimkmlmnmrmsmtmynanbndnengnlnnnonrnvnyocojomorospapiplpsptqurmrnrorurwsascsdsesgsiskslsmsnsosqsrssstsusvswtatetgthtitktltntotrtstttwtyugukuruzvevivowawoxhyiyozazhzu

level string erforderlich

CEFR proficiency level (A1–C2) or NATIVE

Werte

A1A2B1B2C1C2NATIVE

addedAt datetime optional

nullable

updatedAt datetime optional

read-onlynullable

karma integer optional

ADR 0224: running karma total (engagement/fairness score). Server-managed: awarded on verified task completion when tenant.features.karmaEnabled. Audit trail in karma_ledger.

≥ 0Default: 0read-only

skillUpdateLog object[] optional

Audit trail of automatic skill-level changes triggered by survey responses or other sources

max 100 ItemsDefault: []nullable

responseId uuid optional

survey_response UUID that triggered this update (idempotency key)

nullable

appliedAt datetime erforderlich

source string optional

Werte

satisfaction-surveymanualcertificationticket-closetask-donemanual-grantsurveynull

nullable

changes object[] erforderlich

skillId uuid erforderlich

previousLevel string optional

Werte

BEGINNERINTERMEDIATEADVANCEDEXPERTnull

nullable

newLevel string erforderlich

Werte

BEGINNERINTERMEDIATEADVANCEDEXPERT

xpDelta integer optional

XP amount awarded in this change (new XP system)

nullable

reason string optional

Optional human-readable reason for the change

max 500 Zeichennullable

phone string optional

Personal phone number

max 50 Zeichennullable

dateOfBirth date optional

Date of birth

nullable

emergencyContactName string optional

Emergency contact name

max 200 Zeichennullable

emergencyContactPhone string optional

Emergency contact phone number

max 50 Zeichennullable

timeZone string optional

IANA-Zeitzone (z.B. "Europe/Berlin"). Override gegenüber org_unit.timeZone / tenant default. Wird u.a. für Zuschlag-Zeitfenster und DST-Handling genutzt.

max 64 Zeichennullable

holidayRegion string optional

ISO 3166-2 Feiertagsregion (z.B. "DE-NW"). Override gegenüber org_unit.holidayRegion / tenant.settings.defaultHolidayRegion. Relevant für MA im Homeoffice in anderem Bundesland.

Patternnullable

mentorUserId uuid optional

Assigned mentor for trainees / juniors

nullable

isMentor boolean optional

Marked as available mentor in the picker

Default: false

isSuitableForInterns boolean optional

Marked as senior who can supervise intern-grade work

Default: false

defaultSubstituteUserId uuid optional

Fallback user for sick-leave auto-reassign

nullable

isApprentice boolean optional

Auszubildender: befindet sich in der Ausbildung und hat noch keinen Abschluss. Dient als Gate für den (separat gebauten) Berichtsheft-/Ausbildungsnachweis-Bereich, der nur für Auszubildende sichtbar ist.

Default: false

isAusbilder boolean optional

Markiert den Mitarbeiter als Ausbilder (kann Auszubildende ausbilden / ist im Ausbilder-Picker eines Auszubildenden wählbar).

Default: false

ausbilderEmployeeId uuid optional

employee_profiles-UUID des diesem Auszubildenden zugewiesenen Ausbilders. Referenziert einen Mitarbeiter (nicht user), damit auch Ausbilder ohne Login zuordenbar sind.

nullable

legalEntityId uuid optional

Rechtliche Einheit (party UUID — typically the operating company, e.g. ITF or Codemeta).

nullable

workLocationId uuid optional

Primary work location (asset/site UUID; references the company address/site).

nullable

qualification object optional

Berufs- oder Studienabschluss. `kind: "ausbildung"` referenziert einen Eintrag aus dem BIBB-Verzeichnis (apps/api/src/data/ausbildungsberufe-2026.jsonl); `kind: "hochschule"` erfasst Abschlussgrad + freies Studienfach.

nullable

kind string erforderlich

Werte

ausbildunghochschule

ausbildungName string optional

Berufsbezeichnung aus dem BIBB-Verzeichnis (z. B. "Tierwirt/Tierwirtin")

max 250 Zeichennullable

fachrichtung string optional

Fachrichtung der Ausbildung, falls anwendbar (z. B. "Imkerei")

max 200 Zeichennullable

berufsgattungCode string optional

BIBB-Berufsgattung (5-stellige Nummer)

Patternnullable

kategorie string optional

Kategorie aus dem BIBB-Verzeichnis (s. Reference-Data-Endpoint)

Werte

ausbildung-bbigausbildung-ausserhalb-bbigausbildung-gesundheit-bundesrechtausbildung-gesundheit-landesrechtausbildung-zustaendige-stelleumschulung-zustaendige-stelle

nullable

hochschulabschluss string optional

Akademischer Abschlussgrad

Werte

BACHELORMASTERDIPLOMMAGISTERSTAATSEXAMENPROMOTIONHABILITATIONBERUFSAKADEMIEOTHER

nullable

fach string optional

Studienfach (Freitext, z. B. "Wirtschaftsinformatik")

max 200 Zeichennullable

safetyRoles object[] optional

Arbeitsrechtliche Sicherheitsrollen (Ersthelfer, Brandschutzhelfer, Sicherheitsbeauftragter, Datenschutzbeauftragter, ...). Mehrfachzuweisung erlaubt; freie Werte sind zugelassen, damit nicht-katalogisierte Rollen gepflegt werden können.

Default: []nullable

key string erforderlich

Stabiler Bezeichner (für Standardrollen einer aus SAFETY_ROLE_CATALOG; für Sonstige der frei eingegebene Rollenname).

1–200 Zeichen

assignedAt date optional

Datum der Bestellung / Beauftragung

nullable

validUntil date optional

Gültig bis — triggert escalation_rule-Reminder vor Ablauf

nullable

notes string optional

max 500 Zeichennullable

educationCertificates object[] optional

Studienbescheinigungen / Ausbildungsnachweise. The actual file lives in the DMS; this is metadata + expiry.

Default: []nullable

_id uuid optional

read-only

title string erforderlich

1–200 Zeichen

issuer string optional

max 200 Zeichennullable

issuedAt date optional

nullable

validUntil date optional

Ablaufdatum — when set, an escalation_rule reminder fires before expiry.

nullable

documentId uuid optional

Reference to dms_document holding the certificate file

nullable

assignedAssetIds uuid[] optional

UUIDs of assets handed out to the employee (laptop, phone, keycard, …). Asset entity carries the canonical assignment record; this is a denormalised quick-access list.

Default: []nullable

idDocumentVerifications object[] optional

Append-only Liste der HR-Sichtprüfungen des Ausweisdokuments. Jede Verifikation speichert wer und wann geprüft hat — Dokumentennummer wird DSGVO-konform nicht erfasst.

max 200 ItemsDefault: []read-onlynullable

_id uuid optional

read-only

verifiedAt datetime erforderlich

Zeitpunkt der Sichtprüfung (server-issued)

verifiedBy uuid erforderlich

User-UUID der prüfenden HR-Person

verifiedByName string optional

Anzeigename zum Zeitpunkt der Prüfung (Snapshot)

max 200 Zeichennullable

documentType string optional

Dokumenttyp zum Zeitpunkt der Prüfung (PERSONALAUSWEIS, REISEPASS, AUFENTHALTSTITEL, …) — Snapshot, damit Typänderungen die Historie nicht verfälschen.

max 64 Zeichennullable

documentCountry string optional

ISO 3166-1 alpha-2 Ausstellerstaat zum Zeitpunkt der Prüfung — Snapshot.

max 2 ZeichenPatternnullable

notes string optional

max 500 Zeichennullable

encryptedFields object optional

Map of field-name → encrypted envelope (AES-256-GCM, employee DEK). See EMPLOYEE_PROFILE_ZK_FIELDS for the registered field set and visibility category.

nullable

starfaceAccountId string optional

Starface ACCOUNT_ID this employee maps to (matched by email).

max 32 Zeichenread-onlynullable

starfaceLoginId string optional

Starface LOGIN_ID (informational).

max 64 Zeichenread-onlynullable

starfaceInternalNumber string optional

Starface primary internal number (informational).

max 64 Zeichenread-onlynullable

starfaceExternalNumber string optional

Starface primary external number (informational).

max 64 Zeichenread-onlynullable

notes string optional

Free-text notes for HR admin

max 10000 Zeichennullable

Certification

employee_certifications4 Permissions

Tracks formal certifications and qualifications for scheduling (Zertifikate)

employeeId uuid erforderlich

userId uuid erforderlich

skillId uuid erforderlich

UUID of the skill_definition this certification validates

issuedAt date erforderlich

Certification issue date

expiresAt date optional

Expiry date. Null = does not expire

nullable

certifyingBody string optional

Issuing authority (e.g. "DGUV", "Ärztekammer Berlin")

max 500 Zeichen

certificationNumber string optional

Certificate ID/number

max 200 Zeichennullable

documentId uuid optional

UUID of the DMS document with the certificate scan

nullable

status string optional

Werte

VALIDEXPIRING_SOONEXPIREDREVOKED

Default: "VALID"

notes string optional

max 2000 Zeichennullable

Document

employee_documents4 Permissions

Schema for validating employee document entities (Personalakte-Dokumente)

employeeId uuid erforderlich

UUID of the employee profile

userId uuid erforderlich

User UUID of the employee

title string erforderlich

Document title

1–500 Zeichen

category string erforderlich

Document category for the personnel file

Werte

CONTRACTCERTIFICATESICK_NOTEEVALUATIONTRAININGID_DOCUMENTOTHER

fileId uuid erforderlich

UUID of the uploaded file

fileName string erforderlich

Original file name

max 500 Zeichen

mimeType string erforderlich

MIME type of the file

max 200 Zeichen

validFrom date optional

Document validity start date

nullable

validUntil date optional

Document expiry date (for certification tracking)

nullable

isConfidential boolean optional

Whether only HR admins can access this document

Default: false

notes string optional

Additional notes

max 2000 Zeichennullable

Skill

skill_definitions4 Permissions

Schema for validating skill definition entities (Skill-Katalog)

name string erforderlich

Display name of the skill (e.g. "Windows Server", "Netzwerktechnik")

1–200 Zeichen

slug string erforderlich

URL-safe slug, also used as tag value for dispatch compatibility

max 200 ZeichenPattern

parentId uuid optional

Parent skill UUID for tree nesting. Null = root node. Arbitrary depth allowed.

nullable

category string optional

Legacy flat category. Prefer parentId hierarchy. Auto-computed from root ancestor name.

max 200 Zeichennullable

description string optional

Detailed description of the skill

max 2000 Zeichennullable

isActive boolean optional

Whether this skill is currently active and selectable

Default: true

relatedCourseIds uuid[] optional

UUIDs of academy courses that teach this skill

Default: []

schedulingCategory string optional

Category for scheduling qualification matching

Werte

TECHNICALSOFTCERTIFICATIONLANGUAGEOTHERnull

nullable

requiresCertification boolean optional

If true, valid employee_certifications entry required for scheduling

Default: false

requiredForScheduling boolean optional

If true, this skill can be required in shift template position slots

Default: false

minimumLevelForScheduling string optional

Minimum proficiency level required when used in scheduling

Werte

BEGINNERINTERMEDIATEADVANCEDEXPERTnull

nullable

isBinary boolean optional

If true, skill is presence-only (have it or not) — e.g. formal qualifications like Rettungssanitäter. No XP/level tracked; auto-XP awards skip this skill.

Default: false

impliedSkillIds uuid[] optional

Skills that are automatically covered when an employee holds this skill. Example: Notfallsanitäter implies Rettungssanitäter. Only meaningful for isBinary=true; targets must also be isBinary. Cycles are rejected. Resolved transitively by the solver and replacement search.

Default: []

aiManaged boolean optional

If true, automatic XP awards from ticket/task completion and survey-driven level steps are applied to this skill. If false, the skill level is curated manually only (certifications, manager assignment, self-assessment). Ignored when isBinary is true.

Default: false

assetMatchRules object[] optional

Rules that auto-derive this skill as a ticket requirement from a customer's assets (CMDB). When a ticket is dispatched, the customer's assets are matched against these rules; each match adds this skill to the ticket's requiredSkills (source ASSET_DERIVED), so dispatch prefers technicians who hold it. Empty = the skill is never asset-derived. Example: a "WatchGuard" skill with a rule { manufacturers: ["WatchGuard"], assetSchemaPatterns: ["asset.network.firewall"] }.

Default: []

manufacturers string[] optional

Manufacturer names matched case-insensitively (substring) against the asset manufacturer (or its asset_template manufacturer). Empty = any manufacturer.

Default: []

assetSchemaPatterns string[] optional

Asset schema prefixes matched via prefix against the asset schema, e.g. "asset.network.firewall" or "asset.network" (all network assets). Empty = any asset type.

Default: []

minimumLevel string optional

Minimum proficiency the derived requirement demands when this rule matches. Null = any level.

Werte

BEGINNERINTERMEDIATEADVANCEDEXPERTnull

nullable

Vacation

vacation_requests4 Permissions

Schema for validating vacation request entities (Abwesenheitsanträge)

employeeId uuid erforderlich

ADR 0123 — employee_profile._id der freistellungsbedürftigen Person. Kanonischer Schlüssel, funktioniert auch ohne verknüpften Login.

requesterId uuid optional

User UUID des Antragstellers — denormalisiert für Self-Service-Reads. Null bei HR-erfassten Anträgen für Mitarbeitende ohne Login-Account.

nullable

approverId uuid optional

User UUID of the designated approver

nullable

substituteId uuid optional

User UUID of the substitute during leave (Vertretung)

nullable

startDate date erforderlich

First day of leave (ISO 8601 date: YYYY-MM-DD)

endDate date erforderlich

Last day of leave (ISO 8601 date: YYYY-MM-DD)

daysRequested number erforderlich

Number of working days requested (0.5 for half-day)

≥ 0.5

halfDayStart boolean optional

Whether the first day is a half day (afternoon only)

Default: false

halfDayEnd boolean optional

Whether the last day is a half day (morning only)

Default: false

leaveType string erforderlich

Abwesenheitsart. Nur VACATION zieht vom Jahresurlaub ab. ADR 0036b: TIME_IN_LIEU (Gleitzeit, FLEX), OVERTIME_COMPENSATION (Überstunden, OVERTIME), LONG_TERM_WITHDRAWAL (Langzeitkonto). Gesetzliche Freistellungen: VOCATIONAL_SCHOOL, EDUCATION_LEAVE, QUARANTINE, PAID_RELEASE, CARE_LEAVE.

Werte

VACATIONSPECIAL_LEAVECOMPENSATORYUNPAIDOTHERTIME_IN_LIEUOVERTIME_COMPENSATIONLONG_TERM_WITHDRAWALVOCATIONAL_SCHOOLEDUCATION_LEAVEQUARANTINEPAID_RELEASECARE_LEAVE

specialLeaveReason string optional

Anlass für SPECIAL_LEAVE: WEDDING (Hochzeit), BEREAVEMENT (Todesfall naher Angehöriger), CHILD_BIRTH (Geburt eigenes Kind), RELOCATION (Umzug), JUBILEE (Dienstjubiläum), OTHER (sonstiger Anlass).

Werte

nullWEDDINGBEREAVEMENTCHILD_BIRTHRELOCATIONJUBILEEOTHER

nullable

accountTransactionId uuid optional

UUID der time_account_transaction, die bei Genehmigung des Freizeitausgleichs gebucht wurde. Nur bei leaveType ∈ {TIME_IN_LIEU, OVERTIME_COMPENSATION, LONG_TERM_WITHDRAWAL}.

nullable

status string optional

Current request status

Werte

PENDINGAPPROVEDREJECTEDWITHDRAWN

Default: "PENDING"

reason string optional

Reason for the leave request

max 1000 Zeichennullable

approverComment string optional

Approver comment on approval or rejection

max 1000 Zeichennullable

eventId uuid optional

UUID of the CalendarEvent created on approval

nullable

Sick-Leave

sick_leaves4 Permissions

Schema for validating sick leave entities (Krankmeldungen)

employeeId uuid erforderlich

UUID of the employee profile (ADR 0123 — kanonisch)

userId uuid optional

User UUID des erkrankten Mitarbeitenden — denormalisiert. Null bei Mitarbeitenden ohne Login-Account (HR erfasst dann manuell).

nullable

startDate date erforderlich

First day of sick leave (ISO 8601 date: YYYY-MM-DD)

endDate date optional

Last day of sick leave (null = open-ended)

nullable

status string optional

Current sick leave status

Werte

REPORTEDCERTIFICATE_RECEIVEDEAU_CONFIRMEDCLOSED

Default: "REPORTED"

type string erforderlich

Type of sick leave

Werte

ILLNESSCHILD_SICKWORK_ACCIDENTREHABILITATION

certificateFileId uuid optional

UUID of the uploaded AU certificate file

nullable

eauReference string optional

Reference from electronic AU system (eAU)

max 100 Zeichennullable

reportedAt datetime optional

When the sick leave was reported

reportedBy uuid optional

User UUID of the person who reported the sick leave (self or manager)

workingDaysLost number optional

Calculated number of working days lost

≥ 0nullable

eventId uuid optional

UUID of the calendar event created for this sick leave

nullable

notes string optional

Additional notes

max 2000 Zeichennullable

autoReassignProcessedAt datetime optional

When sick-leave auto-reassign of open tickets was processed

nullable

autoReassignedTicketCount integer optional

How many tickets were auto-reassigned from the sick employee

≥ 0nullable

Shift-Assignment

shift_assignments4 Permissions

A concrete staffing entry: one employee occupies one role-slot of one coverage-demand using one shift-block on one date. Together with the coverage-demand.coverageWindow, the set of assignments determines whether the demand is fully covered.

employeeId uuid erforderlich

UUID of the employee profile — canonical key (ADR 0122). Shifts can be planned for employees without a linked user account (Aushilfen, Subunternehmer, Azubis ohne IT-Konto).

userId uuid optional

Linked user UUID (denormalised from `employee_profile.userId` for fast personal-calendar lookups). `null` when the employee has no login. Writers must keep it in sync.

nullable

shiftBlockId uuid erforderlich

UUID of the shift-block (time bucket). Required — the time + ArbZG semantics of the assignment come from this block.

coverageDemandId uuid optional

UUID of the coverage-demand this assignment fills. Null for ad-hoc shifts that do not belong to any demand (e.g. Springer, training time blocked off as a shift).

nullable

roleSlotId string optional

When coverageDemandId is set, this is the slotId of the role within coverage-demand.roles[] that the employee occupies. Null when coverageDemandId is null.

max 100 Zeichennullable

date date erforderlich

Date of the shift (YYYY-MM-DD)

startTimeOverride string optional

Override start time for this specific assignment

Patternnullable

endTimeOverride string optional

Override end time for this specific assignment

Patternnullable

status string optional

Assignment status

Werte

PLANNEDCONFIRMEDSWAPPEDCANCELLEDOPEN

Default: "PLANNED"

swappedWithUserId uuid optional

User UUID if this shift was swapped

nullable

notes string optional

max 2000 Zeichennullable

schedulePeriodId uuid optional

UUID of the schedule period this assignment belongs to

nullable

solverGenerated boolean optional

True if generated by the scheduling solver (CP-SAT / greedy fallback). Manually-created or manually-edited assignments stay false.

Default: false

aiExplanation string optional

LLM-rendered German-language explanation of why the solver made this assignment (generated post-solve by schedule-evaluation.service via Claude).

max 2000 Zeichennullable

preferenceScore number optional

Normalised employee preference for this employee × shift-block combination, in [-1, 1]. Mapping: LOVE=1.0, PREFER=0.7, NEUTRAL=0.5, AVOID=0.1, NEVER=-1.0. NEVER is a soft penalty, not a veto — the solver may still assign a NEVER block when no feasible alternative exists (such cases are reported in qualityReport.neverViolations).

-1 – 1nullable

confirmedByEmployee boolean optional

Default: false

confirmedAt datetime optional

nullable

Constraints

shift_constraint_sets4 Permissions

Configurable labor law constraint sets (Tarifverträge)

name string erforderlich

E.g. "TVöD 2024", "TV-Ärzte 2024", "Haustarif Muster GmbH"

1–200 Zeichen

description string optional

max 5000 Zeichennullable

orgUnitId uuid optional

Null = applies to all org units in this tenant

nullable

maxDailyHours number optional

Max working hours per day (ArbZG § 3 default: 10)

1 – 24Default: 10

maxWeeklyHours number optional

Max working hours per week (ArbZG default: 48)

1 – 168Default: 48

minRestHours number optional

Min rest between shifts in hours (ArbZG § 5 default: 11)

1 – 24Default: 11

maxConsecutiveDays number optional

Max consecutive working days

1 – 14nullable

nightShiftCompensationRule object optional

Night shift compensation configuration

nullable

holidayCompensationRule object optional

Holiday shift compensation configuration

nullable

onCallRatio number optional

On-call attendance time ratio (Bereitschaftsdienst Anrechnungsquote, e.g. 0.25)

0 – 1nullable

isActive boolean optional

Default: true

extraRules string[] optional

Additional free-text rules, LLM-interpretable for conflict detection

Default: []

Preference

shift_preferences4 Permissions

Schema for employee shift preferences (Wunschzettel)

schedulePeriodId uuid erforderlich

employeeId uuid erforderlich

userId uuid erforderlich

status string optional

Werte

DRAFTSUBMITTEDLOCKED

Default: "DRAFT"

submittedBy uuid optional

nullable

llmParseConfirmedBy uuid optional

nullable

availability object[] optional

Default: []

startDate date erforderlich

endDate date erforderlich

type string erforderlich

Werte

AVAILABLEUNAVAILABLEPREFERREDAVOID

note string optional

max 500 Zeichennullable

shiftPreferences object[] optional

Default: []

shiftBlockId uuid erforderlich

preference string erforderlich

Werte

LOVEPREFERNEUTRALAVOIDNEVER

weight number optional

Importance weight

1 – 5Default: 3

colleaguePreferences object[] optional

References target employees by employeeId (not userId) so colleagues without a user account can be picked.

Default: []

employeeId uuid erforderlich

type string erforderlich

Werte

PREFER_WITHPREFER_NOT_WITH

note string optional

max 500 Zeichennullable

timePreferences object optional

nullable

preferMornings boolean optional

Default: false

preferEvenings boolean optional

Default: false

preferNights boolean optional

Default: false

preferWeekends boolean optional

Default: false

avoidWeekends boolean optional

Default: false

maxShiftsPerWeek number optional

0 – 7nullable

preferBlocks boolean optional

Prefer consecutive shift blocks

Default: false

avoidShortChangeovers boolean optional

Avoid late-then-early sequences beyond the legal ArbZG §5 minimum

Default: false

tradeoffs object[] optional

Conditional wishes (if-then tradeoffs)

max 10 ItemsDefault: []

ifCondition string erforderlich

max 500 Zeichen

thenAccept string erforderlich

max 500 Zeichen

customWishes string optional

Free-text wishes, parsed by LLM

max 3000 Zeichennullable

preferenceWeights object optional

Relative importance of each preference dimension (1-10)

nullable

availability number optional

1 – 10Default: 5

shiftType number optional

1 – 10Default: 5

colleague number optional

1 – 10Default: 3

time number optional

1 – 10Default: 4

submittedAt datetime optional

nullable

lockedAt datetime optional

read-onlynullable

lockedBy uuid optional

read-onlynullable

llmParseResult object optional

Parsed structured constraints from customWishes

nullable

llmParseConfirmedAt datetime optional

When employee confirmed the LLM parse result

nullable

Swap

shift_swap_requests4 Permissions

Schema for shift exchange requests between employees (Schichttausch)

requesterId uuid erforderlich

User UUID of requesting employee

requesterAssignmentId uuid erforderlich

UUID of the shift assignment to swap away

targetUserId uuid optional

Target employee UUID. Null = open marketplace request

nullable

targetAssignmentId uuid optional

Target assignment UUID. Null until counterpart selects a shift

nullable

status string optional

Werte

PENDING_MATCHPENDING_TARGET_ACCEPTPENDING_APPROVALAPPROVEDREJECTEDCANCELLEDEXPIRED

Default: "PENDING_MATCH"

requesterNote string optional

max 2000 Zeichennullable

managerNote string optional

max 2000 Zeichennullable

approvedById uuid optional

nullable

approvedAt datetime optional

nullable

rejectedReason string optional

max 2000 Zeichennullable

expiresAt datetime optional

When the open request expires automatically

nullable

Fairness

shift_fairness_records4 Permissions

Per-period fairness tracking for an employee (Fairness-Ledger)

schedulePeriodId uuid erforderlich

employeeId uuid erforderlich

userId uuid erforderlich

orgUnitId uuid erforderlich

periodStartDate date optional

periodEndDate date optional

schedulePeriodName string optional

max 200 Zeichennullable

generatedBy uuid optional

nullable

totalShiftsAssigned number optional

≥ 0Default: 0

desirableShiftCount number optional

≥ 0Default: 0

undesirableShiftCount number optional

≥ 0Default: 0

neutralShiftCount number optional

≥ 0Default: 0

weekendShiftCount number optional

≥ 0Default: 0

holidayShiftCount number optional

≥ 0Default: 0

nightShiftCount number optional

≥ 0Default: 0

onCallShiftCount number optional

≥ 0Default: 0

totalScheduledHours number optional

≥ 0Default: 0

contractualHours number optional

≥ 0Default: 0

overtimeHours number optional

Positive = overtime, negative = undertime

Default: 0

preferenceScore number optional

How well preferences were satisfied (0-100)

0 – 100nullable

fairnessScore number optional

Composite fairness score (0-100, higher = more fairly treated)

0 – 100nullable

neverViolationCount number optional

≥ 0Default: 0

colleaguePreferenceSatisfied number optional

≥ 0Default: 0

colleaguePreferenceViolated number optional

≥ 0Default: 0

qualificationUtilization number optional

How often qualified for assigned shifts (0-100)

0 – 100nullable

WT-Model

working_time_models4 Permissions

Policy-Vorlage für Arbeitszeitberechnung (ADR 0036b)

name string erforderlich

1–200 Zeichen

modelType string erforderlich

Basistyp. TRUST entfernt (BAG 2022 / EuGH CCOO — Zeiterfassungspflicht).

Werte

FIXEDFLEXTIMESHIFTANNUAL_HOURSKAPOVAZPROJECT_BASED

isDefault boolean optional

Default: false

isActive boolean optional

Default: true

workingDays number[] erforderlich

unique items

defaultWorkingHoursPerDay number optional

0 – 24nullable

weeklyHoursTarget number optional

Modell-Wochensoll (Stunden). Genutzt, wenn das Modell direkt in Wochenstunden definiert ist (z. B. „30h/Woche, Verteilung egal"). Wird durch `working_time_assignment.weeklyHours` pro Mitarbeiter übersteuerbar.

0 – 168nullable

monthlyHoursTarget number optional

Modell-Monatssoll (Stunden). Genutzt für Mitarbeiter, deren Vertrag in Monatsstunden geführt wird (z. B. Minijob mit „40h/Monat"). Sollberechnung skaliert linear über die Periodenlänge.

0 – 744nullable

dailyHoursTargets object[] optional

Tagesindividuelles Stundensoll pro ISO-Wochentag (1=Mo..7=So). Fehlende Tage gelten als frei. Wenn gesetzt, überschreibt dieses Feld `defaultWorkingHoursPerDay` für den jeweiligen Tag und liefert das Wochensoll (Σ hours). Orthogonal zu `fixedSchedule` (das zusätzlich Start/Endzeit vorgibt).

max 7 Itemsnullable

day number erforderlich

1 – 7

hours number erforderlich

0 – 24

planningDeadline object optional

nullable

dayOfWeek number optional

1 – 7

weekOffset number optional

time string optional

Pattern

notes string optional

max 2000 Zeichennullable

flexWindow object optional

nullable

startTime string optional

Pattern

endTime string optional

Pattern

coreHours object optional

nullable

startTime string optional

Pattern

endTime string optional

Pattern

breakWindow object optional

nullable

startTime string optional

Pattern

endTime string optional

Pattern

fixedSchedule object[] optional

Tagesfester Plan (nur bei modelType FIXED). Pro ISO-Wochentag.

nullable

day number erforderlich

1 – 7

startTime string erforderlich

Pattern

endTime string erforderlich

Pattern

breakMinutes number optional

≥ 0Default: 0

breakStartTime string optional

Patternnullable

breakEndTime string optional

Patternnullable

shiftTypes object[] optional

Schichttypen (nur bei modelType SHIFT).

nullable

id string erforderlich

1–32 Zeichen

name string erforderlich

1–100 Zeichen

startTime string erforderlich

Pattern

endTime string erforderlich

Pattern

breakMinutes number optional

≥ 0Default: 0

breakStartTime string optional

Patternnullable

breakEndTime string optional

Patternnullable

prepTimeMinutes number optional

Rüst-/Umkleidezeit (BAG-Rspr.), zählt als Arbeitszeit

≥ 0Default: 0

surchargePercent number optional

≥ 0Default: 0

crossesMidnight boolean optional

Default: false

shiftRotation object optional

Rotationsmuster für SHIFT-Modelle.

nullable

pattern string[] optional

Sequenz von shiftTypes[].id oder "OFF"

cycleWeeks number optional

≥ 1Default: 1

annualHours object optional

Jahresarbeitszeitkonto (nur bei modelType ANNUAL_HOURS).

nullable

targetHours number erforderlich

Jahressoll in Stunden (z.B. 1720)

≥ 0

monthlyBandwidth object optional

nullable

minHours number optional

≥ 0

maxHours number optional

≥ 0

quarterlyBalancingRequired boolean optional

Default: false

kappiRules object optional

KAPOVAZ-Regeln (Abrufarbeit, § 12 TzBfG).

nullable

minWeeklyHours number erforderlich

§ 12 TzBfG: mind. 10h wenn nicht vereinbart

≥ 10

maxWeeklyHours number erforderlich

≥ 0

callInNoticePeriodHours number optional

§ 12 TzBfG: mind. 4 Tage Vorlauf

≥ 96Default: 96

minConsecutiveHours number optional

§ 12 TzBfG: mind. 3h pro Einsatz

≥ 3Default: 3

projectRules object optional

Projektbasierte Arbeitszeit.

nullable

maxDailyHours number optional

0 – 10Default: 10

maxWeeklyHours number optional

0 – 48Default: 48

requiresProjectRef boolean optional

Zeitbuchung braucht Projekt-Referenz

Default: true

overtimeRules object optional

nullable

flexOvertimeAutoCredit boolean optional

Default: true

outsideFlexRequiresApproval boolean optional

Default: true

outsideFlexMultiplier number optional

≥ 1Default: 1

weekendMultiplier number optional

≥ 1Default: 1

holidayMultiplier number optional

≥ 1Default: 1

overtimeSurchargePercent number optional

Zuschlag auf Mehrarbeit über Soll (ADDITIVE oben drauf)

≥ 0

maxFlexBalanceMinutes number optional

≥ 0nullable

monthlyCarryOverLimitMinutes number optional

≥ 0nullable

breakRules object erforderlich

Pausenregeln (ArbZG § 4). Gilt auf allen Modelltypen.

after6HoursMinutes number optional

Pflichtpause bei >6h Arbeit (ArbZG: ≥30 Min)

≥ 0Default: 30

after9HoursMinutes number optional

Pflichtpause bei >9h Arbeit (ArbZG: ≥45 Min)

≥ 0Default: 45

minSegmentMinutes number optional

Mindestdauer einer einzelnen Pause (ArbZG: 15 Min)

≥ 0Default: 15

maxConsecutiveWorkMinutes number optional

Max. ununterbrochene Arbeit ohne Pause (ArbZG: 6h = 360 Min)

≥ 0Default: 360

restPeriod object erforderlich

Ruhezeit zwischen Schichten (ArbZG § 5). Gilt für alle Modelle.

minHoursBetweenShifts number optional

Reguläre Mindestruhezeit in Stunden (ArbZG § 5 Abs. 1)

≥ 0Default: 11

reducedToHours number optional

Reduzierte Ruhezeit (ArbZG § 5 Abs. 2: bestimmte Branchen)

≥ 0Default: 10

reducedAllowed boolean optional

Ob reduzierte Ruhezeit (z.B. Gastgewerbe, Krankenhäuser) erlaubt ist

Default: false

maxWorkHours object erforderlich

Höchstarbeitszeit (ArbZG § 3). Gilt für alle Modelle.

maxDailyHours number optional

Tageshöchstarbeitszeit (ArbZG: 8h regulär, 10h max)

0 – 10Default: 10

maxWeeklyHoursAveraged number optional

Wochenhöchstarbeitszeit im Durchschnitt (ArbZG: 48h)

0 – 48Default: 48

averagingPeriodMonths number optional

Ausgleichszeitraum für Wochendurchschnitt (ArbZG: 6 Monate)

1 – 12Default: 6

nightWorkLimits object optional

Nachtarbeitsgrenzen (ArbZG § 6). Nur bei Modellen mit Nachtschicht.

nullable

maxHoursPerNight number optional

Max. Stunden pro Nachtschicht (ArbZG § 6 Abs. 2)

0 – 10Default: 8

averagingPeriodMonths number optional

≥ 1Default: 1

nightWindowStart string optional

Beginn Nachtzeitfenster (ArbZG § 2 Abs. 3)

PatternDefault: "23:00"

nightWindowEnd string optional

PatternDefault: "06:00"

medicalExamRequired boolean optional

Arbeitsmedizinische Untersuchungspflicht (§ 6 Abs. 3)

Default: false

partTime object optional

Teilzeit-Modifier. Konkreter Prozentsatz auf dem Assignment.

nullable

distributionMode string optional

Werte

FEWER_HOURSFEWER_DAYSCUSTOM

Default: "FEWER_HOURS"

compressedWeek object optional

Komprimierte Woche (z.B. 4×10h). Exklusiv zu partTime.

nullable

workDaysPerWeek number erforderlich

1 – 6

dailyHoursTarget number erforderlich

0 – 12

onCall object optional

Rufbereitschaft. Exklusiv zu standby.

nullable

compensationMode string erforderlich

Werte

FLAT_RATEPER_HOUR

flatRateAmountCents number optional

≥ 0nullable

perHourAmountCents number optional

≥ 0nullable

responseTimeMinutes number erforderlich

≥ 0

nightSurchargePercent number optional

≥ 0Default: 0

weekendSurchargePercent number optional

≥ 0Default: 0

holidaySurchargePercent number optional

≥ 0Default: 0

activationCountsAsWork boolean optional

Default: true

standby object optional

Bereitschaftsdienst (am AG-bestimmten Ort). Exklusiv zu onCall.

nullable

countAsWorkPercent number erforderlich

z.B. 50 = halbe Stunde pro Stunde Bereitschaft

0 – 100

locationRequired boolean optional

Default: true

surchargePercent number optional

≥ 0Default: 0

jobSharing object optional

Zwei MA teilen eine Vollzeitstelle. Partner-Zuordnung auf Assignment-Ebene.

nullable

splitMode string optional

Werte

WEEKLY_ALTERNATINGDAILY_SPLITCUSTOM

Default: "WEEKLY_ALTERNATING"

bandwidth object optional

Variable Wochenstunden innerhalb Min/Max-Korridor.

nullable

minWeeklyHours number erforderlich

≥ 0

maxWeeklyHours number erforderlich

≥ 0

referencePeriodWeeks number erforderlich

≥ 1Default: 26

travelTimeRules object optional

Reisezeit-Regeln (BAG 17.10.2018 – 5 AZR 553/17). MSP-relevant.

nullable

defaultCountAsWorkPercent number optional

0 – 100Default: 100

excludeCommute boolean optional

Weg Wohnung↔Hauptarbeitsort zählt nicht als Arbeitszeit

Default: true

customerTripCountsFromDoor boolean optional

Anfahrt Kunde ab Haustür/Homeoffice (MSP-Praxis)

Default: true

maxDailyTravelMinutes number optional

Optionale ArbZG-Anrechnungs-Obergrenze

≥ 0nullable

surchargeStackingMode string optional

Wie Zeit-Zuschläge (Nacht/Wochenende/Feiertag) kombinieren. MAX = Maximum gewinnt (TV-Praxis); ADDITIVE = alle addieren.

Werte

MAXADDITIVE

Default: "MAX"

approvalState string optional

Werte

DRAFTPENDING_WORKS_COUNCILAPPROVEDREJECTED

Default: "DRAFT"

submittedForApprovalAt datetime optional

nullable

submittedBy string optional

max 64 Zeichennullable

approvedAt datetime optional

nullable

approvedBy string optional

max 64 Zeichennullable

worksCouncilCaseRef string optional

max 200 Zeichennullable

rejectionReason string optional

max 4000 Zeichennullable

WT-Assignment

working_time_assignments4 Permissions

Hierarchische Zuweisung eines Arbeitszeitmodells an einen Scope mit Gültigkeit

scope string erforderlich

Auflösungs-Ebene: Tenant (Fallback), Org-Unit (Vererbung), Employee (Override)

Werte

TENANTORG_UNITEMPLOYEE

scopeId string erforderlich

Ziel-ID passend zum Scope: tenantId | org_unit._id | employee_profile._id. Für EMPLOYEE-Scope ist `employee_profile._id` der kanonische Schlüssel (ADR 0036b, Folge-Update 2026-05). Damit lassen sich Arbeitszeitmodelle auch Mitarbeitern ohne verknüpften User-Account zuweisen.

1–64 Zeichen

workingTimeModelId string erforderlich

Referenz auf working_time_models._id

1–64 Zeichen

validFrom string erforderlich

ISO 8601 Beginn der Zuweisung

Pattern

validTo string erforderlich

ISO 8601 Ende; "9999-12-31" = unbefristet (Sentinel)

Pattern

weeklyHours number optional

Individuelle Wochenstunden (Instanz-Parameter). Nicht gesetzt = Modell-Default.

0 – 80nullable

partTimePercent number optional

Teilzeit-Prozentsatz auf dem partTime-Modifier des Modells. Nur sinnvoll, wenn Model partTime definiert.

0 – 100nullable

collectiveAgreementId string optional

Optionale Tarifvertragsbindung (collective_agreements._id)

max 64 Zeichennullable

approvalState string optional

Freigabestatus. Resolver berücksichtigt nur APPROVED für scope ∈ {TENANT, ORG_UNIT}.

Werte

DRAFTPENDING_WORKS_COUNCILAPPROVEDREJECTED

Default: "DRAFT"read-only

submittedForApprovalAt datetime optional

Zeitpunkt der BR-Vorlage

read-onlynullable

submittedBy string optional

userId der Person, die die Freigabe angefragt hat

max 64 Zeichenread-onlynullable

approvedAt datetime optional

Zeitpunkt der BR-Freigabe oder Ablehnung

read-onlynullable

approvedBy string optional

userId des freigebenden BR-Mitglieds (muss != submittedBy sein)

max 64 Zeichenread-onlynullable

worksCouncilCaseRef string optional

BR-Beschluss-Referenz (Nummer/Datum), frei formatiert

max 200 Zeichennullable

rejectionReason string optional

Begründung bei approvalState === "REJECTED"

max 4000 Zeichennullable

notes string optional

Zusätzliche Notizen zur Zuweisung

max 4000 Zeichennullable

Payroll-Record

payroll_records4 Permissions

Per-employee encrypted master data for payroll preparation (Lohnstammdaten). Tier 1 zero-knowledge.

employeeProfileId uuid erforderlich

UUID of the linked employee_profile

ciphertext string erforderlich

Base64-encoded AES-256-GCM ciphertext of the payload JSON

max 65536 Zeichen

iv string erforderlich

Base64-encoded 12-byte random IV

max 32 Zeichen

alg string erforderlich

Symmetric encryption algorithm identifier

Werte

AES-256-GCM

keyId string erforderlich

Identifier of the payroll group key version that encrypted this record. Used to detect re-encryption needs after key rotation.

max 64 Zeichenread-only

completionStatus string optional

Whether all mandatory fields are filled. Cleartext flag, computed on save by the HR client.

Werte

DRAFTCOMPLETENEEDS_REVIEW

Default: "DRAFT"

lastEditedBy uuid optional

User UUID of the HR member who last edited this record

nullable

lastEditedAt datetime optional

When the encrypted payload was last updated

nullable

Payroll-Period

payroll_periods4 Permissions

Per-employee, per-month encrypted variable payroll data. Tier 1 zero-knowledge.

employeeProfileId uuid erforderlich

UUID of the linked employee_profile

period string erforderlich

Payroll period in YYYY-MM format (e.g. "2026-04")

Pattern

status string erforderlich

DRAFT: in preparation. READY: HR marked it complete. EXPORTED: at least one DATEV export ran. LOCKED: no further edits without correction workflow.

Werte

DRAFTREADYEXPORTEDLOCKED

Default: "DRAFT"

lockedAt datetime optional

When this period was locked

read-onlynullable

lockedBy uuid optional

User UUID of the HR member who locked the period

read-onlynullable

ciphertext string erforderlich

Base64-encoded AES-256-GCM ciphertext of the payload JSON

max 65536 Zeichen

iv string erforderlich

Base64-encoded 12-byte random IV

max 32 Zeichen

alg string erforderlich

Symmetric encryption algorithm identifier

Werte

AES-256-GCM

keyId string erforderlich

Identifier of the group key version used for encryption

max 64 Zeichenread-only

timeTrackingSyncedAt datetime optional

When this period last imported hours from the time-tracking module. Used to detect stale data.

nullable

lastEditedBy uuid optional

nullable

lastEditedAt datetime optional

nullable

Recovery

payroll_recovery_configs4 Permissions

Tenant-level payroll module configuration and recovery metadata.

activated boolean erforderlich

Whether the payroll module has been activated for this tenant

Default: false

activatedAt datetime optional

When the activation wizard was completed

read-onlynullable

activatedBy uuid optional

User UUID of the GF/Owner who activated the module

read-onlynullable

currentKeyId string erforderlich

Current group key version identifier (e.g. UUID v7)

max 64 Zeichenread-only

keyRotatedAt datetime optional

When the group key was last rotated

nullable

checksumPepper string optional

Tenant-specific HMAC pepper (32 random bytes, base64url) for shareChecksum. Generated at activation; absent for tenants activated before the pepper rollout (legacy SHA-256 path).

max 64 Zeichennullable

hrMembers object[] optional

HR team members with access to payroll data

Default: []

userId uuid erforderlich

wrappedGroupKey string erforderlich

Base64url-encoded payroll group key wrapped with this user ECDH public key. AES-KW of a 32-byte key produces 40 bytes → ~54 base64url chars; 128 leaves headroom but blocks DoS payloads.

max 128 Zeichen

ephemeralPublicKey string optional

Sender ephemeral ECDH public key used during ECDH-ES wrap

max 256 Zeichen

keyId string optional

Group key version this wrapped key corresponds to

max 64 Zeichen

addedAt datetime erforderlich

addedBy uuid optional

nullable

removedAt datetime optional

When this member was removed (kept for audit)

nullable

shamirConfig object optional

nullable

n integer erforderlich

Total number of shares generated

2 – 7

threshold integer erforderlich

Minimum number of shares required for reconstruction

2 – 7

shares object[] erforderlich

Per-share metadata. The actual share values are NEVER stored — only this metadata.

shareId string erforderlich

Share identifier (also printed on the token sheet)

max 64 Zeichen

index integer optional

GF(256) x-coordinate of the Shamir share (the first byte of the raw share, also printed on the token sheet as "Index"). Required to reconstruct the share during recovery — the BIP-39 mnemonic alone only encodes the 32 secret bytes.

1 – 255

recipientLabel string erforderlich

Free-text label of the share recipient (e.g. "Maximilian M.")

max 200 Zeichen

recipientUserId uuid optional

Optional link to a user (if recipient is a Codemeta user)

nullable

checksum string optional

Short checksum for share validation during recovery

max 32 Zeichen

generatedAt datetime erforderlich

acknowledgedAt datetime optional

When the GF confirmed the token was printed and handed over

nullable

invalidatedAt datetime optional

When this share was invalidated (e.g. token rotation, member change, recovery completed)

nullable

steuerberater object optional

nullable

firmName string optional

max 200 Zeichen

contactName string optional

max 200 Zeichen

email email optional

max 200 Zeichen

phone string optional

max 50 Zeichennullable

datevAdvisorNumber string optional

DATEV-Berater-Nummer

max 20 Zeichennullable

datevClientNumber string optional

DATEV-Mandanten-Nummer

max 20 Zeichennullable

recoveryHistory object[] optional

Audit trail of recovery events (cleartext, no secrets)

max 50 ItemsDefault: []read-only

recoveredAt datetime erforderlich

recoveredBy uuid erforderlich

shareIdsUsed string[] optional

Share IDs of the tokens used for reconstruction

newKeyId string optional

max 64 Zeichen

reason string optional

max 500 Zeichennullable

Export

payroll_exports4 Permissions

Audit log entry for a payroll period export to the Steuerberater.

period string erforderlich

Exported payroll period (YYYY-MM)

Pattern

format string erforderlich

Export format used

Werte

DATEV_LODAS_CSVDATEV_ASCIIDATEV_XML

employeeCount integer erforderlich

Number of employees included in the export

≥ 0

sha256 string erforderlich

SHA-256 hash of the generated file (lowercase hex)

Patternread-only

fileSize integer optional

Size of the generated file in bytes

≥ 0read-onlynullable

exportedBy uuid erforderlich

User UUID of the HR member who triggered the export

read-only

exportedAt datetime erforderlich

read-only

deliveryMethod string optional

How the file left the browser

Werte

DOWNLOADEMAIL

recipientEmail email optional

Steuerberater email address (only for EMAIL deliveries)

max 200 Zeichennullable

notes string optional

Optional notes attached to the export

max 1000 Zeichennullable

LODAS

payroll_lodas_settings4 Permissions

Tenant-level LODAS code mapping and format options.

datumsformat string optional

Date format used in the LODAS file. Day/month always 2-digit, year 4-digit.

Werte

TT.MM.JJJJTT/MM/JJJJJJJJ-MM-TTJJJJ/MM/TT

Default: "TT.MM.JJJJ"

stringbegrenzer string optional

String delimiter character (LODAS: " ` allowed).

Werte

"'`

Default: "\""

feldtrennzeichen string optional

Field separator. LODAS allows ; * | \ ~ $ &.

Werte

;*|\~$&

Default: ";"

zahlenkomma string optional

Decimal separator (German comma by default).

Werte

,.

Default: ","

versionSst string optional

LODAS-Schnittstellenversion (Version_SST).

max 16 ZeichenDefault: "1.0"

lohnartMapping object optional

Maps internal payroll fields to mandant-specific Lohnart codes.

grossSalary string optional

Bruttogehalt (Festbezug)

max 8 Zeichen

hourlyWage string optional

Stundenlohn

max 8 Zeichen

overtime string optional

Überstunden

max 8 Zeichen

bonus string optional

Boni / Einmalzahlungen

max 8 Zeichen

commission string optional

Provisionen

max 8 Zeichen

expensesTaxFree string optional

Spesen steuerfrei

max 8 Zeichen

expensesTaxable string optional

Spesen steuerpflichtig

max 8 Zeichen

jobTicket string optional

Jobticket

max 8 Zeichen

mealVoucher string optional

Essensgutschein

max 8 Zeichen

sachbezug string optional

Sachbezug Sonstige

max 8 Zeichen

vwl string optional

VWL-Betrag

max 8 Zeichen

bavEmployee string optional

BAV-AN-Anteil

max 8 Zeichen

bavEmployer string optional

BAV-AG-Zuschuss

max 8 Zeichen

pfaendung string optional

Pfändungs-Summe

max 8 Zeichen

bsMapping object optional

Bearbeitungsschlüssel codes for u_lod_bwd_buchung_standard.bs_nr.

brutto string optional

BS für Bruttobezüge (DATEV-default: 02)

max 4 Zeichen

stunden string optional

BS für Stundenbuchungen (DATEV-default: 01)

max 4 Zeichen

sachbezug string optional

BS für Sachbezüge (DATEV-default: 50)

max 4 Zeichen

netto string optional

BS für Nettobezüge/-abzüge (DATEV-default: 70)

max 4 Zeichen

defaultTaetigkeitsschluessel string optional

Default Tätigkeitsschlüssel applied when the employee has none set.

max 16 Zeichennullable

notes string optional

Free-text notes about the mapping (e.g. StB conventions, special cases).

max 2000 Zeichennullable

lastValidatedAt datetime optional

When the mapping was last confirmed against the StB-Mandant.

nullable

lastValidatedBy uuid optional

User who last validated the mapping with the StB.

nullable

Payroll-Audit

payroll_audit_events4 Permissions

Append-only audit log of payroll data access events.

action string erforderlich

Type of action performed

Werte

DECRYPT_RECORDDECRYPT_PERIODENCRYPT_RECORDENCRYPT_PERIODEXPORT_DATEVMEMBER_ADDEDMEMBER_REMOVEDKEY_ROTATEDRECOVERY_PERFORMEDPERIOD_LOCKEDUNLOCK_SESSION

read-only

actorUserId uuid erforderlich

User UUID of the HR member who performed the action

read-only

targetType string optional

Kind of resource the action targeted

Werte

employee_profilepayroll_recordpayroll_periodpayroll_exporttenant_membertenant_confignull

nullable

targetId string optional

UUID of the affected resource (record/period/user/export)

max 64 Zeichennullable

targetEmployeeProfileId uuid optional

When the action concerns a specific employee, their profile UUID — supports per-employee audit queries (DSGVO-Auskunftsrecht).

nullable

period string optional

YYYY-MM payroll period if the action is period-scoped

Patternnullable

occurredAt datetime erforderlich

When the action happened (client clock — server stores its own createdAt)

read-only

sourceIp string optional

Client IP captured by the server (filled by route handler, not client)

max 45 Zeichenread-onlynullable

userAgent string optional

User-Agent header captured by the server

max 500 Zeichenread-onlynullable

notes string optional

Free-text context (e.g. recovery reason, export filename hash, member-removal justification)

max 1000 Zeichennullable

Custom-Endpoints (`/api/v1/hr/...`)

Über CRUD hinaus gibt es dedizierte HR-Endpoints. Auszug:

Operation	Hinweis
`POST /api/v1/hr/employees/<id>/onboard`	Onboarding-Workflow starten
`POST /api/v1/hr/employees/<id>/offboard`	Offboarding-Workflow starten
`GET /api/v1/hr/vacation-balance/<userId>`	Aktuelle Urlaubsstände
`POST /api/v1/vacation_requests/<id>/approve`	Urlaubs-Antrag genehmigen

Abwesenheiten

Urlaub und Krankmeldung laufen über zwei getrennte Entities. Anträge haben typischerweise Status requested, approved, rejected, cancelled. Vorlauf-, Vertretungs- und Approver-Regeln liegen pro Mandant als typisierte Konfiguration am working_time_model.

POST /api/v1/vacation_requests
{
  "employeeProfileId": "0193…",
  "startDate": "2026-07-01",
  "endDate": "2026-07-14",
  "reason": "Familienurlaub"
}

Payroll-Export

Der LODAS-Export läuft über einen async Job:

POST /api/v1/payroll_exports
{ "periodId": "0193…", "format": "lodas" }

Ergebnis wird als File-Storage-Pointer im payroll_export-Datensatz hinterlegt. Aktuelle Konfiguration kommt aus payroll_lodas_settings.

Verwandt

Konventionen
LMS — Pflicht-Schulungen verbinden sich mit Zertifikaten
Compliance / GRC — Schulungs-Nachweise als Evidence

HR & Payroll

Resources – HR

Resources – Schichten & Arbeitszeit

Resources – Payroll

Schemas

Custom-Endpoints (/api/v1/hr/...)

Abwesenheiten

Payroll-Export

Verwandt

Custom-Endpoints (`/api/v1/hr/...`)