Skip to content

API — Employees, skills & certifications

Purpose

Read access to employee profiles, the production skills surface, certifications, employee groups, and the Excel bulk-import pipeline that is the only write path for people and skills.

Auth & roles

Area Base Reads / writes
Employees /api/employees employee.view (read-only)
Skills (production) /api/skills skill.view / skill.edit
Certifications /api/employees/{id}/certifications certifications.read / certifications.manage
Employee groups /api/employee-groups employee_group.read / employee_group.write
Imports /api/imports imports.run

Endpoints

Employees — /api/employees · employee.view · GET only

Method Path Purpose
GET /api/employees List employees
GET /api/employees/my The caller's own employee record
GET /api/employees/{id} Employee detail

Skills (production) — /api/skills

Method Path Purpose Gate
GET /api/skills List skills skill.view
GET /api/skills/{id}/employees Employees with a skill skill.view
GET / POST / DELETE /api/skills/{id}/certification-requirements … Manage cert requirements skill.view / skill.edit
PUT /api/skills/{id}/requires-certification Toggle cert requirement skill.edit

Certifications

Method Path Purpose Gate
GET /api/certifications/expiring Expiring certifications certifications.read
GET /api/employees/me/certifications Own certifications [Authorize]
GET / POST /api/employees/{id}/certifications List / add a cert manage
PUT /api/employees/{id}/certifications/{certId} (+ /status) Update a cert / its status certifications.manage

Employee groups — /api/employee-groups · read employee_group.read, write employee_group.write: full CRUD plus GET/POST/DELETE …/{id}/members[/{employeeId}] for membership.

Imports — /api/imports · imports.run (SYS_ADMIN + HR_ADMIN + PLANNER)

Method Path Purpose
POST /api/imports/employees Upload an .xlsx → async import job
GET /api/imports/template · /export-current Download blank template / current data
GET /api/imports/jobs · /jobs/{id} Job list / detail
GET /api/imports/jobs/{id}/error-report Download the per-row error .xlsx
DELETE /api/imports/jobs/{id} Cancel a job (SuperAdmin + imports.view_history)

Shapes & errors

Import upload is validated synchronously (≤10 MB, .xlsx, schema) then runs as a Hangfire fire-and-forget job (see Background jobs); the file is in-memory only, SHA-256 hashed. Standard ProblemDetails; a duplicate file within 24h returns 201 with a warning, not a block.

Gotchas

  • Employees and skills are import-only / read-only via the API. There is no create/edit employee endpoint (Employees is GET-only) — people enter via Excel import or seed (sheet 03). The skill catalog CRUD is the admin surface (/api/admin/skills), not these production routes.
  • /api/skills (production) coexists with /api/admin/skills (admin CRUD) — the coexistence pattern.
  • Certifications have no automatic expiry sweep — "expiring" is computed on read; there is no scheduled job (sheet 04; see Diagnostics for the manual trigger).
  • Import cancel needs SuperAdmin + imports.view_history, and cancels cooperatively between rows.