The public API reads your organisation's people, leave, attendance and payroll. Each page in this reference describes one kind of record: its endpoints, their filters, an example answer, and what every field means.
Endpoints
| Endpoint | Returns | Key needs |
|---|---|---|
GET v1/integrations/api-keys/me | The key, its organisation and its permissions | Any key |
GET v1/company/list | Your organisation's companies | Employee Management: View |
GET v1/employee/list | Employees, a page at a time | Employee Management: View |
GET v1/employee/{id} | One employee's full record | Employee Management: View |
GET v1/department/list | Departments, a page at a time | Employee Management: View |
GET v1/department/{id} | One department | Employee Management: View |
GET v1/leaverequest/list | Leave requests, a page at a time | Leave: View |
GET v1/leaverequest/details/{id} | One leave request | Leave: View |
GET v1/leavebalance/get-leave-balance | One employee's balance of one leave type | Leave: View |
GET v1/leavetype/list | Leave types, a page at a time | Leave: View |
GET v1/attendance/list | Attendance records, a page at a time | Attendance: View |
GET v1/attendance/report/{id} | One day's absence report totals | Attendance: View |
GET v1/attendance/exceptions | Excused days, a page at a time | Attendance: View |
GET v1/attendance/exceptions/{id} | One excused day or range | Attendance: View |
GET v1/attendance/holidays | Your organisation's own holidays for a year | Attendance: View |
GET v1/attendance/holidays/public | Public holidays for a year | Attendance: View |
GET v1/payroll/schedule/list | A company's payroll runs | Payroll: View |
GET v1/payroll/schedule/{id} | One payroll run and its totals | Payroll: View |
GET v1/payroll/schedule/{id}/salaries | Each employee's pay in a run | Payroll: View |
"Key needs" is the access an administrator gives the key when creating it. See Authentication.
Any other KalHR endpoint answers 403 to a key. More are being added; the changelog says
when.
Conventions
Every endpoint follows the same rules, described once in Requests and responses:
- Requests go to
https://api.kalhr.com/with the key inAuthorization: Bearer …. - Every answer is the envelope
isSuccessful,code,message,data. CheckisSuccessful. - Fields with no value are left out.
- Lists are paged with
PageNumberandPageSize, and answer withtotalPages. - Times are UTC; calendar dates come as midnight.
- A key only ever sees its own organisation's records.
The examples in this reference show the whole answer, envelope included. Ids in them are made up.
Stability
Within v1, new endpoints, new fields and new filters are added without notice; your code should ignore fields it
doesn't know. Removing or renaming a field, or changing what it means, is announced in the
changelog before it happens.
