The employees module manages the people on your payroll. PII (email, phone, BVN, NIN, bank account number) is encrypted at rest and decrypted when returned by the API.

List employees

GET/v1/employees

Returns employees, optionally filtered by status.

Query parameters

Field	Type	Required	Notes
`businessId`	string	yes
`status`	string	no	`active`, `inactive`, `terminated`.
`limit`	integer	no	Default 50, max 100.

Get a single employee

GET/v1/employees/{id}

Create an employee

POST/v1/employees

Adds an employee to the directory. Does not run payroll.

Body

Field	Type	Required	Notes
`firstName`, `lastName`	string	yes
`email`	string	yes	Encrypted at rest.
`phone`	string	no	Encrypted at rest.
`employeeNumber`	string	no	Auto-generated if omitted.
`dateOfBirth`	ISO 8601	no
`hireDate`	ISO 8601	no	Defaults to today.
`department`	string	no
`position`	string	no
`grossSalary`	number	yes	Monthly gross in naira.
`bankAccountNumber`	string	no	Encrypted. For salary disbursement.
`bankName`	string	no
`bvn`	string	no	Encrypted.
`nin`	string	no	Encrypted.
`pensionPFA`, `pensionRSA`	string	no
`nhfNumber`	string	no
`taxId`	string	no	TIN.

Update an employee

PUT/v1/employees/{id}

Edits employee fields. Changes apply to the next payroll run.

Deactivate / activate

POST/v1/employees/{id}/deactivate

Marks an employee inactive. They're excluded from future payroll runs, but historical payslips remain.

POST/v1/employees/{id}/activate

Re-activates an inactive employee.

Body (for deactivate)

Field	Type	Required	Notes
`reason`	string	no	Shown in the audit trail.
`effectiveDate`	ISO 8601	no	Defaults to today.

Related endpoints

Payroll & Payslips

Employees