Both endpoints need Employee Management: View. A department belongs to one company.
List departments
GET/v1/department/listKey needs Employee Management: ViewReturns your organisation's departments, a page at a time.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
PageNumber | integer | 1 | The page to return |
PageSize | integer | 25 | Departments per page |
SearchTerm | string | Part of the department's name | |
Companies | uuid, repeated | Only these companies: Companies=…&Companies=… | |
OrderBy | integer | 1 | 0 oldest first, 1 newest first |
GET v1/department/list
curl "https://api.kalhr.com/v1/department/list?PageNumber=1&PageSize=25" \
-H "Authorization: Bearer $KALHR_API_KEY"Response
{
"isSuccessful": true,
"code": "00",
"message": "Success",
"data": {
"data": [
{
"id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
"name": "Finance",
"created": "2025-03-14T09:21:07.512",
"status": "Active",
"leads": [{ "id": "7e21a9c0-…", "name": "Tunde" }],
"unitsCount": 2,
"membersCount": 14
}
],
"pageNumber": 1,
"pageSize": 25,
"totalRecords": 9,
"totalPages": 1
}
}
| Field | Type | Description |
|---|---|---|
id | uuid | The department's id |
name | string | Name |
created | datetime | When it was added (UTC) |
status | string | Active or InActive |
leads | array | Department heads: id, and name (their first name only; get the department for full names) |
unitsCount | integer | Units in the department |
membersCount | integer | Employees in the department |
Get a department
GET/v1/department/{id}Key needs Employee Management: ViewGET v1/department/2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f
curl "https://api.kalhr.com/v1/department/2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f" \
-H "Authorization: Bearer $KALHR_API_KEY"Response
{
"isSuccessful": true,
"code": "00",
"message": "Success",
"data": {
"id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
"name": "Finance",
"description": "Payroll, accounts and audit",
"status": "Active",
"created": "2025-03-14T09:21:07.512",
"companyId": "1f2e3d4c-5b6a-4987-8a6b-5c4d3e2f1a0b",
"unitsCount": 2,
"membersCount": 14,
"leaders": [{ "id": "7e21a9c0-…", "name": "Tunde Bello" }]
}
}
Besides the list's fields:
| Field | Type | Description |
|---|---|---|
description | string | What the department does |
companyId | uuid | The company it belongs to |
leaders | array | Department heads: id and full name |
An id that isn't one of your organisation's departments answers isSuccessful: false.
