Employees

Both endpoints need Employee Management: View. Pay is included only when the key also has Payroll: View; without it, salary is left out.

Two fields are easy to confuse: id is KalHR's id for the employee record, which you use to call the API, and employeeId is your own employee number, such as ACM-0042.

One person can have a record in each company of your organisation they work for. Each record has its own id.

List employees

GET/v1/employee/listKey needs Employee Management: View

Returns your organisation's employees, a page at a time, most recently added first.

Query parameters

Parameter	Type	Default	Description
`PageNumber`	integer	1	The page to return
`PageSize`	integer	25	Employees per page
`Status`	name or integer		Only employees with this status, such as `Active`. See statuses.
`SearchTerm`	string		Matches first, last or full name, email, phone or employee number
`Companies`	uuid, repeated		Only these companies: `Companies=…&Companies=…`. Ids come from Companies.
`DepartmentId`	uuid		Only this department
`JobRoleId`	uuid		Only this job role
`WorkMode`	name or integer		`Remote` (0), `Onsite` (1) or `Hybrid` (2)
`OrderColumn`	integer	1	Sort by `0` the date they joined, or `1` the date they were added to KalHR
`OrderBy`	integer	1	`0` ascending, `1` descending

GET v1/employee/list

curl "https://api.kalhr.com/v1/employee/list?Status=Active&PageNumber=1&PageSize=25" \
  -H "Authorization: Bearer $KALHR_API_KEY"

Response

{
  "isSuccessful": true,
  "code": "00",
  "message": "Success",
  "data": {
    "data": [
      {
        "id": "4b9d2c1e-7a3f-4e8b-9c21-5d6e7f8a9b0c",
        "employeeId": "ACM-0042",
        "companyId": "1f2e3d4c-5b6a-4987-8a6b-5c4d3e2f1a0b",
        "firstName": "Ada",
        "lastName": "Okafor",
        "email": "ada.okafor@acme.ng",
        "phoneNumber": "08031234567",
        "workMode": 2,
        "status": "Active",
        "nationality": "Nigeria",
        "nationalityId": 160,
        "employmentType": "Full time",
        "employmentTypeId": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
        "jobRoles": [
          {
            "id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
            "title": "Payroll Officer",
            "gradingSystem": { "id": "3a4b5c6d-7e8f-4a9b-8c7d-6e5f4a3b2c1d", "name": "Grade 6", "minimum": 500000, "maximum": 800000 }
          }
        ],
        "departments": [{ "id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "name": "Finance" }],
        "salary": {
          "id": "7d6c5b4a-3f2e-4d1c-9b0a-8f7e6d5c4b3a",
          "employeeId": "4b9d2c1e-7a3f-4e8b-9c21-5d6e7f8a9b0c",
          "companyId": "1f2e3d4c-5b6a-4987-8a6b-5c4d3e2f1a0b",
          "organizationId": "8c1d0e2f-4a6b-4c8d-9e0f-1a2b3c4d5e6f",
          "grossSalary": 650000,
          "netSalary": 512340.5,
          "salary": 512340.5
        }
      }
    ],
    "pageNumber": 1,
    "pageSize": 25,
    "totalRecords": 134,
    "totalPages": 6
  }
}

Employee fields

Field	Type	Description
`id`	uuid	KalHR's id for this employee record. Use it with Get an employee.
`employeeId`	string	Your employee number, as entered in KalHR
`companyId`	uuid	The company this record belongs to
`firstName`, `lastName`	string	Name
`email`	string	Work email
`phoneNumber`	string	Phone number
`photoUrl`	string	Link to their profile photo, when they have one
`workMode`	integer	`0` Remote, `1` Onsite, `2` Hybrid
`status`	string	See statuses
`nationality`, `nationalityId`	string, integer	The country's name and KalHR's id for it
`employmentType`, `employmentTypeId`	string, uuid	Such as Full time or Contract
`jobRoles`	array	Each `id`, `title`, and `gradingSystem`: the grade's `id`, `name`, and and the `minimum` and `maximum` pay set for that grade
`departments`	array	Each `id` and `name`
`salary`	object	Their current pay, with Payroll: View, when they have a salary in KalHR (below)

The list's salary:

Field	Type	Description
`id`	uuid	The salary record
`employeeId`, `companyId`, `organizationId`	uuid	Who and where it belongs to
`grossSalary`	number	Monthly gross pay, in naira
`netSalary`	number	Monthly take-home pay, after deductions, pension and PAYE
`salary`	number	The same as `netSalary`

For the breakdown (allowances, deductions, PAYE, pension), get the employee.

Employee statuses

`status`	Number	Meaning
`InActive`	0	Not active
`Active`	1	Working
`OnLeave`	2	On leave
`Resigned`	3	Left by resigning
`Retired`	4	Retired
`LaidOff`	5	Made redundant
`Terminated`	6	Dismissed
`Suspended`	7	Suspended
`Furloughed`	8	Furloughed

To filter, send the name or the number: Status=Active or Status=1.

Get an employee

GET/v1/employee/{id}Key needs Employee Management: View

Returns one employee's full record: everything in the list, plus personal and statutory details, addresses, referees, guarantors and their line manager.

Path parameter	Type	Description
`id`	uuid	The employee's `id` from the list (not their employee number)

GET v1/employee/4b9d2c1e-7a3f-4e8b-9c21-5d6e7f8a9b0c

curl "https://api.kalhr.com/v1/employee/4b9d2c1e-7a3f-4e8b-9c21-5d6e7f8a9b0c" \
  -H "Authorization: Bearer $KALHR_API_KEY"

Response

{
  "isSuccessful": true,
  "code": "00",
  "message": "Success",
  "data": {
    "id": "4b9d2c1e-7a3f-4e8b-9c21-5d6e7f8a9b0c",
    "employeeId": "ACM-0042",
    "firstName": "Ada",
    "middleName": "Ngozi",
    "lastName": "Okafor",
    "email": "ada.okafor@acme.ng",
    "phoneNumber": "08031234567",
    "workMode": 2,
    "maritalStatus": 1,
    "gender": "Female",
    "genderId": 1,
    "dateOfBirth": "1991-04-12T00:00:00Z",
    "dateJoined": "2023-02-01T00:00:00Z",
    "status": "Active",
    "nationalityId": 160,
    "nationality": "Nigeria",
    "taxAccountNumber": "12345678-0001",
    "pensionAccountNumber": "PEN100123456789",
    "pensionProvider": "Example Pensions Ltd",
    "nhfNumber": "",
    "nhisNumber": "",
    "nin": "12345678901",
    "driverLicenseNumber": "",
    "officeLocation": "12 Admiralty Way, Lekki, Lagos",
    "officeLocationId": "5e4d3c2b-1a0f-4e9d-8c7b-6a5f4e3d2c1b",
    "employmentType": "Full time",
    "employmentTypeId": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
    "workingDays": [1, 2, 3, 4, 5],
    "company": { "id": "1f2e3d4c-5b6a-4987-8a6b-5c4d3e2f1a0b", "name": "Acme Nigeria Ltd" },
    "addresses": [{ "street": "4 Bode Thomas Street", "state": "Lagos", "stateId": 25, "country": "Nigeria", "countryId": 160 }],
    "references": [],
    "guarantors": [],
    "jobRoles": [{ "id": "…", "title": "Payroll Officer", "gradingSystem": { "id": "…", "name": "Grade 6", "minimum": 500000, "maximum": 800000 } }],
    "departments": [{ "id": "…", "name": "Finance", "leaders": [{ "id": "…", "fullName": "Tunde Bello", "email": "tunde.bello@acme.ng" }] }],
    "lineManager": { "id": "…", "fullName": "Tunde Bello", "email": "tunde.bello@acme.ng" }
  }
}

Fields

Everything in the list, plus:

Field	Type	Description
`middleName`	string	Middle name
`maritalStatus`	integer	`0` Single, `1` Married, `2` Divorced
`gender`, `genderId`	string, integer	`0` Male, `1` Female, `2` Other
`dateOfBirth`, `dateJoined`	date	Calendar dates: use the date part
`taxAccountNumber`, `pensionAccountNumber`, `pensionProvider`, `nhfNumber`, `nhisNumber`, `nin`, `driverLicenseNumber`	string	Statutory numbers. Empty text when not recorded.
`officeLocation`, `officeLocationId`	string, uuid	Their office: one of their company's addresses
`workingDays`	integer array	The days they work: `0` Sunday … `6` Saturday
`company`	object	`id`, `name`
`addresses`	array	Home addresses: `street`, `zipCode`, `state`, `stateId`, `country`, `countryId`
`references`	array	Referees: `firstName`, `lastName`, `phoneNumber`, `email`, `organization`, `position`
`guarantors`	array	`firstName`, `lastName`, `phoneNumber`, `email`, `address`, `occupation`
`departments`	array	As in the list, with each department's `leaders`: `id`, `fullName`, `email`
`lineManager`	object	`id`, `fullName`, `email`
`salary`	object	Their full pay set-up, with Payroll: View (below)

Here salary has the full breakdown:

Field	Description
`grossSalary`, `netSalary`, `monthlyAllowance`, `monthlyDeduction`, `payePerMonth`, `pensionPerMonth`	Monthly figures, in naira
`grossAnnual`, `netAnnual`, `totalAnnualAllowance`, `totalAnnualDeduction`, `payeAnnual`, `pensionAnnual`	Annual figures
`allowances`, `deductions`	Each `id`, `name`, `type` (`{ "id": 0, "name": "Percentage" }` or `1` FixedAmount) and `amount` (an array holding one number)
`payCycle`	`id`, `name` (`Monthly`, `SemiMonthly` or `Weekly`), `payPeriod`, `payDayOfMonth`
`payType`	`{ "id": 0, "name": "NetPay" }` or `1` GrossPay
`level`	`id`, `name`
`payeTaxType`	How PAYE is worked out

An id that isn't one of your organisation's employees answers isSuccessful: false with Employee not found.

Companies and Departments: ids to filter by
Event catalogue: employee.created, employee.updated, employee.terminated

List employees

Query parameters

Response

Employee fields

Employee statuses

Get an employee

Response

Fields

Quick Links

Resources

Developers

Features

List employees

Query parameters

Response

Employee fields

Employee statuses

Get an employee

Response

Fields

Related

Quick Links

Resources

Developers

Features