API Reference
The KPI Matrix exposes two read-only JSON APIs: a client (integration) API for other systems, and an end-user API for an employee's own data. Both are read-only and both hide internal columns.
????
Not for browser use — these back integrations, dashboards and mobile/SPA clients. The in-app screens
don't call them; they use their own internal endpoints. Both APIs reuse the exact same scoring
services as the web UI, so their numbers always match what you see on screen.
Client (integration) API
Machine-to-machine, read-only, for trusted external systems. Prefix /api/v1/kpi,
OAuth scope kpi:read.
| Property | Value |
|---|---|
| Auth | Bearer JWT + X-Company-Key (selects the tenant database) |
| Scope | kpi:read — “KPI Matrix (Read)” |
| Methods | GET only |
| Missing record | 404 kpi_not_found |
| OpenAPI | public/api/v1/openapi.json |
| Endpoint | Returns |
|---|---|
GET /api/v1/kpi/cycles | all review cycles |
GET /api/v1/kpi/cycles/{id} | one cycle |
GET /api/v1/kpi/templates | all templates |
GET /api/v1/kpi/templates/{id} | one template + its metrics |
GET /api/v1/kpi/results?cycle_id= | composite results for a cycle (defaults to the active cycle) |
GET /api/v1/kpi/employees/{id}/scores?cycle_id= | one employee's assignment + composite + scores by category |
GET /api/v1/kpi/salary-recommendations?cycle_id=&status= | salary recommendations, filterable |
curl -H "Authorization: Bearer $TOKEN" \
-H "X-Company-Key: $COMPANY_KEY" \
"https://your-erpat-host/api/v1/kpi/results?cycle_id=12"End-user API (self-service)
The JSON behind an employee's own KPI view — for a mobile app or SPA. Read-only and
self-only: identity comes from the authenticated employee's token, and a request can never ask
for another user's data. Prefix /v1/api/kpi.
| Property | Value |
|---|---|
| Identity | the authenticated employee (from the token — never a request parameter) |
| Guards | GET only · module module_kpi_matrix on · permit kpi_matrix |
| Module off | 404 module_unavailable (hides that it exists) |
| OpenAPI | public/v1/api/openapi.json |
| Endpoint | Returns |
|---|---|
GET /v1/api/kpi/my/scores?cycle_id= | my assignment + composite + scores by category (defaults to active cycle) |
GET /v1/api/kpi/my/history | my composite-score trend over cycles |
GET /v1/api/kpi/my/assignments | my KPI assignments |
GET /v1/api/kpi/my/salary-recommendation?cycle_id= | my salary recommendation(s) |
GET /v1/api/kpi/my/results/{cycle_id} | my finalized results for a cycle (404 if none) |
????
This end-user API is the programmatic twin of the KPIs profile tab — same
data, same self-only access model.
Generating specs & Postman collections
php erpat api:openapi --postman # client API: /api/v1/* OpenAPI spec + Postman
php erpat euapi:openapi --postman # end-user API: /v1/api/* spec + Postman⚠️
Both APIs are strictly read. There is no API to create a cycle, calculate, or approve a salary
step — those actions are deliberately kept to the authenticated, permission-checked web UI so every
change has a user and an audit trail.
????
Where next? See the access model these APIs enforce on Permissions
& Roles, or the data shapes they return on The 29 Metrics and
Scoring.