All four endpoints need Leave: View.
Leave statuses
A request's status is a number in leaveStatusId and a name in leaveStatus. To filter, send either:
LeaveStatus=Approved or LeaveStatus=2.
leaveStatusId | leaveStatus | Meaning |
|---|---|---|
| 0 | Submitted | Asked for, no decision yet |
| 1 | Pending | Approved by some approvers, waiting for the rest |
| 2 | Approved | Approved |
| 3 | Rejected | Rejected |
| 4 | Abandoned | Withdrawn by the employee or HR |
| 5 | Expired | Not decided in time |
List leave requests
GET/v1/leaverequest/listKey needs Leave: ViewReturns your organisation's leave requests, a page at a time, newest first.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
PageNumber | integer | 1 | The page to return |
PageSize | integer | 25 | Requests per page |
CompanyId | uuid | Only this company's employees. Ids come from Companies. | |
DepartmentId | uuid | Only employees in this department | |
LeaveTypeId | uuid | Only this leave type | |
LeaveStatus | name or integer | Only this status, such as Approved | |
StartDate, EndDate | date | Only leave starting between these dates, as YYYY-MM-DD. Send both. | |
SearchTerm | string | Matches the employee's name or email, or the leave type's name | |
OrderBy | integer | 1 | 0 oldest first, 1 newest first |
GET v1/leaverequest/list
curl "https://api.kalhr.com/v1/leaverequest/list?LeaveStatus=Approved&StartDate=2026-11-01&EndDate=2026-11-30" \
-H "Authorization: Bearer $KALHR_API_KEY"Response
{
"isSuccessful": true,
"code": "00",
"message": "Success",
"data": {
"data": [
{
"id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"employeeId": "4b9d2c1e-7a3f-4e8b-9c21-5d6e7f8a9b0c",
"employeeName": "Ada Okafor",
"leaveTypeName": "Annual leave",
"startDate": "2026-11-02T00:00:00",
"endDate": "2026-11-06T00:00:00",
"leaveStatusId": 2,
"leaveStatus": "Approved",
"comments": "Family trip",
"requestedOn": "2026-10-14T08:02:55.381",
"days": 5
}
],
"pageNumber": 1,
"pageSize": 25,
"totalRecords": 1,
"totalPages": 1
}
}
| Field | Type | Description |
|---|---|---|
id | uuid | The leave request's id |
employeeId, employeeName | uuid, string | Who asked |
leaveTypeName | string | The leave type |
startDate, endDate | date | First and last day off (calendar dates) |
days | integer | Working days requested: weekends, the employee's days off and holidays aren't counted |
leaveStatusId, leaveStatus | integer, string | See the table above |
comments | string | The employee's note |
requestedOn | datetime | When it was asked for (UTC) |
Get a leave request
GET/v1/leaverequest/details/{id}Key needs Leave: ViewReturns one request with the employee's role and department, supporting documents and relievers.
GET v1/leaverequest/details/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
curl "https://api.kalhr.com/v1/leaverequest/details/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" \
-H "Authorization: Bearer $KALHR_API_KEY"Response
{
"isSuccessful": true,
"code": "00",
"message": "Success",
"data": {
"id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"employeeId": "4b9d2c1e-7a3f-4e8b-9c21-5d6e7f8a9b0c",
"firstName": "Ada",
"lastName": "Okafor",
"employeeName": "Ada Okafor",
"workMode": "Hybrid",
"jobRoles": ["Payroll Officer"],
"department": ["Finance"],
"leaveTypeName": "Annual leave",
"startDate": "2026-11-02T00:00:00",
"endDate": "2026-11-06T00:00:00",
"leaveStatusId": 2,
"leaveStatus": "Approved",
"comments": "Family trip",
"requestedOn": "2026-10-14T08:02:55.381",
"days": 5,
"documents": [],
"relievers": [{ "id": "7e21a9c0-…", "fullName": "Tunde Bello", "email": "tunde.bello@acme.ng" }],
"handoffNote": "Payroll inputs are in the shared drive."
}
}
Besides the list's fields:
| Field | Type | Description |
|---|---|---|
firstName, lastName | string | The employee's name |
workMode | string | Remote, Onsite or Hybrid (a name here, not a number) |
jobRoles | string array | Job role titles |
department | string array | Department names |
documents | array | Supporting documents: id, name, mime and document. document is a link when storage is 0; when it is 1 the file is private and opens only in KalHR. |
relievers | array | Colleagues covering: id, fullName, email |
handoffNote | string | The employee's handover note |
Get a leave balance
GET/v1/leavebalance/get-leave-balanceKey needs Leave: ViewHow many days of one leave type an employee has, has taken and has left this year.
| Parameter | Type | Description |
|---|---|---|
EmployeeId | uuid | Required. The employee's id |
LeaveTypeId | uuid | Required. The leave type's id, from List leave types |
GET v1/leavebalance/get-leave-balance
curl "https://api.kalhr.com/v1/leavebalance/get-leave-balance?EmployeeId=4b9d2c1e-7a3f-4e8b-9c21-5d6e7f8a9b0c&LeaveTypeId=c0ffee00-1234-4abc-9def-0123456789ab" \
-H "Authorization: Bearer $KALHR_API_KEY"Response
{
"isSuccessful": true,
"code": "00",
"message": "Success",
"data": {
"totalDays": 20,
"daysTaken": 5,
"daysRemaining": 15,
"leavePending": 3,
"leaveRejected": 0
}
}
| Field | Type | Description |
|---|---|---|
totalDays | integer | Days allowed this year |
daysTaken | integer | Days of approved leave deducted |
daysRemaining | integer | Days left to request |
leavePending | integer | Working days in this year's requests still waiting for a decision |
leaveRejected | integer | Working days in rejected requests this year |
An employee who has never had this leave type's balance set up gets the type's full allowance, with nothing taken.
An employee or leave type outside your organisation answers isSuccessful: false.
List leave types
GET/v1/leavetype/listKey needs Leave: ViewQuery parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
PageNumber | integer | 1 | The page to return |
PageSize | integer | 25 | Leave types per page |
CompanyId | uuid | Only this company's | |
SearchTerm | string | Part of the name | |
IsActive | boolean | Only active (true) or inactive (false) types | |
EligibilityCriteria | integer | 0 organisation, 1 company, 2 department, 3 unit, 4 named employees |
GET v1/leavetype/list
curl "https://api.kalhr.com/v1/leavetype/list?IsActive=true" \
-H "Authorization: Bearer $KALHR_API_KEY"Response
{
"isSuccessful": true,
"code": "00",
"message": "Success",
"data": {
"data": [
{
"id": "c0ffee00-1234-4abc-9def-0123456789ab",
"name": "Annual leave",
"description": "Paid annual leave",
"maxLeaveDays": 20,
"carryForward": { "maxCarryForwardLimit": 5, "expirationDate": 2 },
"eligibilityCriteria": 0,
"requiresDocument": false,
"requiredDocument": [],
"isActive": true,
"created": "2025-01-06T10:00:00"
}
],
"pageNumber": 1,
"pageSize": 25,
"totalRecords": 4,
"totalPages": 1
}
}
| Field | Type | Description |
|---|---|---|
id, name, description | uuid, string, string | The leave type |
maxLeaveDays | integer | Days a year |
carryForward | object | maxCarryForwardLimit days, carried days expiring in expirationDate (month: 0 January … 11 December) |
eligibilityCriteria | integer | Who it covers (see the parameter above) |
requiresDocument, requiredDocument | boolean, array | Whether a document must be attached, and its templates (id, name, document) |
isActive | boolean | Whether it can be requested |
created, lastModified | datetime | UTC |
Related
- Event catalogue:
leave.requested,leave.approved,leave.rejected,leave.cancelled
