Entity · employee_profiles

Employee Profile Schema

Schema-ID

employee_profile

Collection

employee_profiles

Permissions

Lesenemployee_profile_view
Anlegenemployee_profile_create
Ändernemployee_profile_edit
Löschenemployee_profile_delete

Felder

Employee Profile Schema

employee_profiles4 Permissions

Schema for validating employee profile entities (Personalstammdaten)

userIduuidoptional

User UUID (optional link to users collection)

nullable

firstNamestringoptional

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

max 200 Zeichennullable

lastNamestringoptional

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

max 200 Zeichennullable

employeeNumberstringoptional

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

max 50 Zeichenread-onlynullable

emailstringoptional

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

orgUnitIduuidoptional

Primary org unit UUID (legacy — use primaryOrgUnitId going forward, ADR 0036b). Write-side it is a mirror of primaryOrgUnitId; changes to either sync the org_units member arrays server-side (ADR 0368).

nullable

primaryOrgUnitIduuidoptional

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

managerIduuidoptional

Direct manager user UUID

nullable

employmentTypestringerforderlich

Type of employment (Beschäftigungsart)

Werte

FULL_TIMEPART_TIMEMINI_JOBWORKING_STUDENTINTERNFREELANCER

employmentStatusstringerforderlich

Current employment status

Werte

ACTIVEONBOARDINGON_LEAVEOFFBOARDINGTERMINATED

Default: "ONBOARDING"

hireDatedateerforderlich

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

probationEndDatedateoptional

End of probation period (Probezeit)

nullable

terminationDatedateoptional

Last day of employment

nullable

terminationReasonstringoptional

Reason for termination

max 1000 Zeichennullable

vacationDaysPerYearnumberoptional

Annual vacation entitlement in days

0 – 365nullable

vacationDaysRemainingnumberoptional

Remaining vacation days for current year

≥ 0nullable

vacationDaysCarryOvernumberoptional

Carried over vacation days from previous year (Resturlaub)

≥ 0nullable

weeklyScheduleobject[]optional

Per-weekday work schedule (Arbeitszeitplanung)

nullable

daynumbererforderlich

ISO weekday (1=Mon, 7=Sun)

1 – 7

startTimestringerforderlich

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

Pattern

endTimestringerforderlich

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

Pattern

breakMinutesnumberoptional

Break duration in minutes

0 – 480Default: 0

workingTimeModelIduuidoptional

Reference to working_time_model entity

nullable

skillsobject[]optional

Structured skill entries with levels

Default: []

skillIduuiderforderlich

UUID of the skill definition

levelstringerforderlich

Proficiency level. INTERESTED is a legacy level-0 interest marker (no proficiency, no XP, never satisfies a scheduling minimum) — deprecated as a level value in favour of the orthogonal `interested` flag below; still read as a fallback. BEGINNER..EXPERT is the legacy 4-tier enum kept in sync with currentLevel. Prefer currentXp/currentLevel for new proficiency logic.

Werte

INTERESTEDBEGINNERINTERMEDIATEADVANCEDEXPERT

interestedbooleanoptional

Orthogonal interest flag (ADR 0223): the employee wants to develop / is interested in this skill, INDEPENDENT of proficiency. Can be true alongside any real level (e.g. EXPERT + interested). Set self-service by the employee on their own profile. Legacy entries with level==="INTERESTED" are treated as interested at read time even when this flag is absent.

nullable

interestedAtdatetimeoptional

When the interest flag was last set to true.

nullable

currentXpintegeroptional

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

≥ 0Default: 0nullable

currentLevelintegeroptional

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

verifiedAtdatetimeoptional

When the skill was last verified

nullable

verifiedByuuidoptional

User UUID of the person who verified the skill

nullable

sourcestringoptional

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"

addedAtdatetimeoptional

When the skill entry was first added

nullable

updatedAtdatetimeoptional

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

read-onlynullable

languageSkillsobject[]optional

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

Default: []

codestringerforderlich

ISO 639-1 language code

Werte

aaabaeafakamanarasavayazbabebgbhbibmbnbo

brbscacechcocrcscucvcydadedvdzeeeleneoeseteufafffifjfofrfygagdglgngugvhahehihohrhthuhyhziaidieigiiikioisitiujajvkakgkikjkkklkmknkokrkskukvkwkylalblglilnloltlulvmgmhmimkmlmnmrmsmtmynanbndnengnlnnnonrnvnyocojomorospapiplpsptqurmrnrorurwsascsdsesgsiskslsmsnsosqsrssstsusvswtatetgthtitktltntotrtstttwtyugukuruzvevivowawoxhyiyozazhzu

levelstringerforderlich

CEFR proficiency level (A1–C2) or NATIVE

Werte

A1A2B1B2C1C2NATIVE

addedAtdatetimeoptional

nullable

updatedAtdatetimeoptional

read-onlynullable

karmaintegeroptional

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

skillUpdateLogobject[]optional

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

max 100 ItemsDefault: []nullable

responseIduuidoptional

survey_response UUID that triggered this update (idempotency key)

nullable

appliedAtdatetimeerforderlich

sourcestringoptional

Werte

satisfaction-surveymanualcertificationticket-closetask-donemanual-grantsurveytraining-completednull

nullable

changesobject[]erforderlich

skillIduuiderforderlich

previousLevelstringoptional

Werte

BEGINNERINTERMEDIATEADVANCEDEXPERTnull

nullable

newLevelstringerforderlich

Werte

BEGINNERINTERMEDIATEADVANCEDEXPERT

xpDeltaintegeroptional

XP amount awarded in this change (new XP system)

nullable

reasonstringoptional

Optional human-readable reason for the change

max 500 Zeichennullable

phonestringoptional

Personal phone number

max 50 Zeichennullable

dateOfBirthdateoptional

Date of birth

nullable

emergencyContactNamestringoptional

Emergency contact name

max 200 Zeichennullable

emergencyContactPhonestringoptional

Emergency contact phone number

max 50 Zeichennullable

timeZonestringoptional

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

holidayRegionstringoptional

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

mentorUserIduuidoptional

Assigned mentor for trainees / juniors

nullable

isMentorbooleanoptional

Marked as available mentor in the picker

Default: false

isSuitableForInternsbooleanoptional

Marked as senior who can supervise intern-grade work

Default: false

defaultSubstituteUserIduuidoptional

Fallback user for sick-leave auto-reassign

nullable

isApprenticebooleanoptional

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

isAusbilderbooleanoptional

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

Default: false

ausbilderEmployeeIduuidoptional

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

nullable

legalEntityIduuidoptional

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

nullable

workLocationIduuidoptional

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

nullable

qualificationobjectoptional

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

kindstringerforderlich

Werte

ausbildunghochschule

ausbildungNamestringoptional

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

max 250 Zeichennullable

fachrichtungstringoptional

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

max 200 Zeichennullable

berufsgattungCodestringoptional

BIBB-Berufsgattung (5-stellige Nummer)

Patternnullable

kategoriestringoptional

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

Werte

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

nullable

hochschulabschlussstringoptional

Akademischer Abschlussgrad

Werte

BACHELORMASTERDIPLOMMAGISTERSTAATSEXAMENPROMOTIONHABILITATIONBERUFSAKADEMIEOTHER

nullable

fachstringoptional

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

max 200 Zeichennullable

safetyRolesobject[]optional

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

Default: []nullable

keystringerforderlich

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

1–200 Zeichen

assignedAtdateoptional

Datum der Bestellung / Beauftragung

nullable

validUntildateoptional

Gültig bis — triggert escalation_rule-Reminder vor Ablauf

nullable

notesstringoptional

max 500 Zeichennullable

educationCertificatesobject[]optional

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

Default: []nullable

_iduuidoptional

read-only

titlestringerforderlich

1–200 Zeichen

issuerstringoptional

max 200 Zeichennullable

issuedAtdateoptional

nullable

validUntildateoptional

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

nullable

documentIduuidoptional

Reference to dms_document holding the certificate file

nullable

assignedAssetIdsuuid[]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

idDocumentVerificationsobject[]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

_iduuidoptional

read-only

verifiedAtdatetimeerforderlich

Zeitpunkt der Sichtprüfung (server-issued)

verifiedByuuiderforderlich

User-UUID der prüfenden HR-Person

verifiedByNamestringoptional

Anzeigename zum Zeitpunkt der Prüfung (Snapshot)

max 200 Zeichennullable

documentTypestringoptional

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

max 64 Zeichennullable

documentCountrystringoptional

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

max 2 ZeichenPatternnullable

notesstringoptional

max 500 Zeichennullable

encryptedFieldsobjectoptional

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

starfaceAccountIdstringoptional

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

max 32 Zeichenread-onlynullable

starfaceLoginIdstringoptional

Starface LOGIN_ID (informational).

max 64 Zeichenread-onlynullable

starfaceInternalNumberstringoptional

Starface primary internal number (informational).

max 64 Zeichenread-onlynullable

starfaceExternalNumberstringoptional

Starface primary external number (informational).

max 64 Zeichenread-onlynullable

notesstringoptional

Free-text notes for HR admin

max 10000 Zeichennullable

externalReferencesobject[]optional

Cross-System-Verknüpfungen (ADR 0147 §3). Pro Fremdsystem ein Eintrag mit stabiler externer Id und den beiden Echo-Hashes. Wird ausschließlich von Sync-Pfaden geschrieben, nie über die generische CRUD-Oberfläche.

Default: []read-only

systemstringerforderlich

max 100 Zeichen

externalIdstringerforderlich

max 200 Zeichen

externalVersionstringoptional

nullable

externalNumberstringoptional

max 200 Zeichennullable

syncedAtdatetimeoptional

nullable

lastSyncCorrelationIdstringoptional

nullable

lastInboundHashstringoptional

max 64 Zeichennullable

lastOutboundHashstringoptional

max 64 Zeichennullable

Standard-Endpoints

Diese Resource folgt dem generischen CRUD-Vertrag der Plattform. Lesen Sie die Konventionen für Pagination, Idempotenz, Optimistic Locking und Audit. Die wichtigsten Endpoints:

GET /api/v1/employee_profiles — Liste, paginiert + filterbar
GET /api/v1/employee_profiles/<id> — Einzelne Entity
POST /api/v1/employee_profiles — Anlegen
PATCH /api/v1/employee_profiles/<id> — Teil-Update
DELETE /api/v1/employee_profiles/<id> — Soft-Delete
GET /api/v1/employee_profiles/<id>/timeline — Audit + Aktivitäten