Employee Records & Organization

Employee profile

The employee and their personnel detail are created in a single atomic operation. The only required fields are first name, last name and date of birth; the remaining ~50 fields can be filled in from the detail page whenever you like.

Required corefirst name · last name · date of birth

Identity & registryregistry no · national ID · SGK no

Demographicsgender · marital status · blood type

Education & military serviceeducation level · military service status

Contract typePERMANENT · FIXED-TERM · PART-TIME · INTERN

Work locationOFFICE · REMOTE · HYBRID · FIELD

Weekly working days1 – 6

Cost centerFK link

ISCO-08 occupation code4 digits (required format)

Disability degree1 / 2 / 3 → to payroll

Atomic record — The employee and their personnel detail are written in a single transaction; if at least one detail field is present a detail record is created, and a skeleton is opened automatically for the emergency contact.
National ID (TC) — NVI Mod-11 — when entered, it is checked for 11 digits plus the algorithmic checksum; an invalid national ID means rejection in the SGK e-Bildirge declaration and an income-tax base error.KVKK art.4
Date of birth required — for the ban on employing minors under 18 and for SGK retirement/premium calculations, the date cannot be skipped.Law 4857 art.71 · 5510
ISCO-08 occupation code — defaulted from the position, customized per person; a 4-digit format is required for the SGK e-Bildirge declaration.SGK e-Bildirge
NVI civil registry fields — mother's name, father's name, place of birth, registry province/district/village, volume no, family order no, order no; a full counterpart to the national ID card for official documents.
Income Tax Law (GVK) art.31 base carry-over — if the employer changed during the year, the cumulative income-tax base carried over from the previous employer, and its year, are recorded; bracket-skipping errors are prevented.GVK art.31
IBAN → automatic bank detection — when an IBAN is entered, the bank name is determined automatically from the code.
Manager hierarchy + loop prevention — the manager is chosen from the same tenant; an employee cannot be assigned below their own subordinate, and circular assignments are rejected.
Soft-delete — a deleted employee is marked inactive (isActive=false) with deletedAt and physically preserved; search and filters (department, position, status, contract type) narrow the list.
Login account for the employee — with one click, an account with the EMPLOYEE role and a random password is created; the only permission is hr:self (their own self-service data).

You can open it, it doesn't have to arrive complete

For a fast hire you enter only first name, last name and date of birth; the person enters the system and the personnel details are completed later. Identity and financial fields can stay empty, but when entered they are validated for regulatory compliance — you never proceed with incorrect data.

KVKK field masking

Two people looking at the same employee profile don't see the same data. Sensitive fields are masked at the record level according to the user's permissions — they are never sent to an unauthorized user at all.

Masked fields

Salary · IBAN · National ID

Salary, IBAN, national ID and SGK number are hidden by role; for a user without permission these fields return null.

Applied in both single-record and list responses
Net/gross/IBAN masking on payroll line itemsKVKK

Scope

List + detail

Masking works on both the employee list and the single employee detail; allowed fields are determined by the user's permissions.

A sensitive-field set for the employee source
A separate set for payroll line items

Why

Accountability

A manager who isn't on the HR team is prevented from seeing a subordinate's salary or IBAN; data minimization is the default behavior.

No access to data you don't need to see
Permitted field ≠ every fieldKVKK art.4

Personnel documents

Every document is attached to the employee record, stored by type, and each access is written to the audit trail. Special-category documents are stamped automatically.

Document types — photo, ID, diploma, contract, resume (CV), health report and other; for each document the name, URL, MIME type, size, expiry date and a note are kept.
KVKK special-category stamp — when a health report or ID document is uploaded, isSpecialCategory is marked automatically; special-category personal data is protected separately.KVKK art.6
Full audit trail — viewing, adding, updating and deleting a document are each written to the AuditLog with the user, the record and the IP address.KVKK art.12
Soft-delete — a deleted document is physically preserved (deletedAt) and drops out of queries; the balance between a KVKK deletion request and legal retention is observed.
Access gate — personnel documents are highly sensitive; every access requires the hr:read / hr:write permission and tenant ownership verification, closing the "any logged-in user" vulnerability.
Migration to the central DMS — personnel documents can be moved to the central Document Management System with a preview → apply step and are reversible (rollback) — admin permission only.

Document expiry tracking

Driver's licence, residence permit and passport dates are gathered in a single panel; an expired residence permit for a foreign worker is an administrative-fine risk.

Tracked documents

3 official dates

Driver's licence, residence permit and passport validity are read from the personnel detail, and those due to expire or already expired are listed.

Foreign-worker residence permit riskLaw 6458 art.99
Read-only — no schema migration

Status & threshold

OK · WARNING · EXPIRED

Days remaining are calculated against an adjustable warningDays threshold (1–180 days), and each document falls into a status.

Days remaining < 0 → EXPIRED
Within threshold → WARNING, outside → OK

Output

Panel + CSV

The list is sorted by days remaining and a summary counter is returned; export to CSV for renewal planning.

Registry no, name, document, date, days remaining
Certificate expiry is a separate channel

Organization

Department tree, position fill rates and an org chart; master data is normalized automatically, and an empty tenant starts with common positions.

Department tree — departments are linked hierarchically via parentId; parent/child department, department manager and code-name fields are kept.
Position & fill rate — each position belongs to a department and has an ISCO-08 code; the fill rate (filled / total / vacant) is calculated from the headcount.
Org chart — a recursive organization chart is derived from the manager hierarchy.
Master-data normalization — department/position names are converted to Turkish Title Case; the code field is transliterated to ASCII, spaces become underscores, and only A-Z 0-9 _ - remain.
12 default positions — for an empty tenant, 12 common positions (General Manager, HR, Accounting Specialist…) are seeded idempotently with ISCO-08 codes; existing ones are not re-added.

Sub-tables

Seven sub-records that extend the employee profile; all are attached to the personnel detail and tenant ownership is verified on every operation — you cannot reach another tenant's record.

Address

Residence · Contact · Birth

Type (RESIDENCE / CONTACT / BIRTH), country, province, district, neighborhood, full address, postal code.

One primary address per type
A new primary demotes the old one

Family / Dependents

For tax allowance & SGK

Spouse, child, parent, sibling; national ID, date of birth, gender, dependency status.

NVI Mod-11 on the family member's national ID tooKVKK art.4
Tax-allowance and e-Bildirge link

Education

Primary school → Doctorate

Level, school, department, graduation and GPA; certificate/diploma URL.

7-level education ladder
Document link

Certificate

Expiry channel

Name, issuing body, expiry date, document URL; those that have expired are listed separately.

Upcoming-expiry query
Renewal planning

Foreign language

A1 – C2 / NATIVE

Language, level (A1, A2, B1, B2, C1, C2, NATIVE), whether certified, certificate name.

An input for the competency map

Asset assignment

Laptop · Phone · Vehicle

Type (LAPTOP / PHONE / CAR / KEY / CARD), name, serial no, assignment and return date.

Assignment and return tracking
Attached to the personnel detail

Emergency contacts

Up to 10 people

Name, relationship (mother/father/spouse/sibling…), phone, email, address, primary flag.

The single contact is preserved retroactively
OHS emergency plan6331 OHS

Birthday & work anniversary

A classic HR practice for employee engagement: upcoming birthdays and work anniversaries in a single panel — a list for a congratulatory message or a small celebration.

Upcoming birthdays — those with a birthday within the window (1–90 days) are listed along with the age they'll turn and the days remaining.
Work anniversaries — those with a hire anniversary in the same window are shown with which year it is.
Sorting — both lists are sorted by days remaining; the manager sees the nearest one at the top.
CSV export — for engagement planning, a CSV is downloaded broken down by type, date, days remaining and year/age.

Document requests & official services

Employment and income certificates are generated as PDFs and pass through a state machine; online national-ID verification and KEP configuration establish the official integration layer.

Document request

PDF + state machine

The employment certificate and income certificate are generated as PDFs and uploaded to Azure Blob; the income certificate is fed from the last 3 payroll line items.

PENDING → PROCESSING → READY
→ DELIVERED / REJECTED
E-signature / wet / manual signature method

NVI national-ID verification

Mod-11 + KPS SOAP

First the offline Mod-11 algorithm, then a SOAP request to the NVI KPS Public service (national ID + first name + last name + year of birth).

Turkish-locale uppercase conversion
Rate limit of 10/min per user
AuditLog with masked national IDKVKK art.5/2

KEP configuration

PTT · TNB · TÜRKKEP

The KEP (registered electronic mail) provider, sender address, username and password are kept in tenant settings; the connection test sends a TLS ping to the provider's server.

Password encrypted at rest with AES-256-GCM
Provider IMAPS host:port test
Test/sandbox mode

An honest boundary

Real KEP send/receive integration is currently on the roadmap — today the configuration record and the TLS connection test to the server work fully, while the actual sending of a KEP message (PTT/TNB API) is the next step. Online NVI verification requires a KPS Real subscription agreement; when the service is closed to anonymous access, the system reports this clearly. The offline Mod-11 algorithm check always works.

Employee self-service portal

The employee logs in with a magic link sent to their email; they view their own payslips, leave, advances and documents, and update their personal information within a restricted whitelist.

Login — magic link + JWT — HR sends a login link to the employee's email; the link is valid for 15 minutes, and once consumed returns a JWT session (1 hour). Identity is always read from the JWT, and identity fields in the body are ignored.
Their own payslips — past payslips are listed by year and page, and a single payslip is downloaded.
Leave & advances — the employee creates their own leave and salary-advance requests from the portal and tracks their status.
Document requests — they request official documents such as employment/income certificates from the portal.
Personal-info updates — whitelist — only email, phone, emergency contact, blood type, marital status and address can be updated.KVKK art.11/d
Unchangeable fields — national ID, IBAN, salary, SGK number and contract type cannot be changed via this path; official/financial fields change only through the HR detail-editing flow, with an audit and approval chain.

One employee profile, the entire personnel file.