HR Management

Overview

The HR API (hr-api) manages workforce operations: employee records, scheduling, time tracking, absences, and labor law compliance.

Base URL: https://rkyywwxpkzzkvopnobvt.supabase.co/functions/v1/hr-api/v1

Persons (Employees)

GET /persons?search={name}&department={id}&_count={limit}&_offset={offset}
POST /persons
GET /persons/{id}
PUT /persons/{id}

Create Person

{
  "firstName": "Maria",
  "lastName": "Kovac",
  "email": "maria.kovac@hospital.com",
  "departmentId": "dept-uuid",
  "positionId": "pos-uuid",
  "hireDate": "2025-01-15"
}

Departments

GET /departments?search={name}&_count={limit}&_offset={offset}
POST /departments
GET /departments/{id}
PUT /departments/{id}

Positions

GET /positions?search={name}&department={id}&_count={limit}&_offset={offset}
POST /positions
GET /positions/{id}
PUT /positions/{id}

Schedules

GET /schedules?person={id}&department={id}&date_from={date}&date_to={date}
POST /schedules
GET /schedules/{id}
PUT /schedules/{id}

Shifts

GET /shifts?person={id}&schedule={id}&date={date}
POST /shifts
GET /shifts/{id}
PUT /shifts/{id}

Validate Shift

Check a shift against labor rules before creating:

POST /validate-shift
Content-Type: application/json

{
  "personId": "person-uuid",
  "startTime": "2026-03-03T07:00:00Z",
  "endTime": "2026-03-03T19:00:00Z"
}

Returns validation result with any labor rule violations.

Shift Templates

Reusable shift patterns:

GET /shift-templates?_count={limit}&_offset={offset}
POST /shift-templates
GET /shift-templates/{id}
PUT /shift-templates/{id}

Time Clock

POST /timeclock/clock-in
POST /timeclock/clock-out
POST /timeclock/start-break
POST /timeclock/end-break
GET /timeclock/status?person={id}

Clock In

{
  "personId": "person-uuid",
  "shiftId": "shift-uuid"
}

Timecards

GET /timecards?person={id}&status={status}&date_from={date}&date_to={date}
POST /timecards/{id}/approve
POST /timecards/{id}/reject

Absences

GET /absences?person={id}&type={type}&date_from={date}&date_to={date}
POST /absences
GET /absences/{id}
PUT /absences/{id}
GET /absences/balances?person={id}&year={year}

HR Roles

GET /roles?person={id}
POST /roles
PUT /roles/{id}

HR Permission Hierarchy

hr_admin > hr_manager > scheduler > employee

With FHIR role fallback — admin maps to hr_admin, doctor/manager get employee level.

Labor Rules

JSON-configurable per country/organization:

GET /labor-rules?country={code}&org_id={orgId}

Rules include: max shift hours, minimum rest between shifts, overtime thresholds, break requirements.

Holidays

GET /holidays?year={year}&country={code}

Returns holidays with multi-language names (JSON names field).

Response Formats

HR search functions return wrapped responses:

Function Pattern	Response Shape
`search_*`	`{ data: [...], total, limit, offset }`
`get_holidays`	`{ year, holidays: [...] }`
`get_absence_balances`	`{ year, balances: [...] }`
`get_user_hr_roles`	`{ hrRoles: [...], implicitRole }`

Notes

Served by the hr-api service; every route is scoped to the organization in your token, and tenant isolation is enforced in the data layer rather than in application code.
Labor rules are configuration, not code — they resolve per country and organization by priority, so a new jurisdiction does not require a release.