Employees

The Employees workspace is where you keep the payroll facts payIQ needs before payroll can be calculated: who the employees are, whether they are payroll-eligible, what they are paid, and which payroll components apply to them.

payIQ employees are payroll employment records. They are separate from any contact record in contactsIQ. A payroll employee can exist with no contactsIQ link at all, and linking one does not create, change, or synchronise a contactsIQ contact.

Note

No payroll is calculated on this screen. Compensation and components are configuration; the calculation happens in Payroll.

The employee list

The list has one row per employee:

Column	What it shows
Employee	Employee number and name. Select the employee to open their detail.
Employment	Active, Inactive, Suspended, or Terminated.
Payroll	Eligible or Not eligible for payroll calculation.
Current compensation	The current monthly salary, daily rate, or hourly rate, or “Not configured”.
contactsIQ	Linked or Unlinked reviewed reference.

The header has a Add employee button that opens and closes the create form.

Creating an employee

Select Add employee and complete:

1. Employee number — unique within the workspace.

2. First name and Last name.

3. Employment start date.

4. Default currency (a short code such as GHS).

5. Payroll eligible — tick this when the employee should be considered by payroll calculation.

6. Employment status, optional Employment end date, and Payroll status.

7. Initial compensation: pay basis, positive amount and effective date. Currency follows the employee default currency. The effective date must fall within employment dates.

Select Create employee. The employee and initial pay term save together; validation failure saves neither. The form reports staff-number/date/pay errors. Only Administrator and Payroll Operator can add/edit employees or import them. Employee identity remains readable to active workspace members. Reporter and Payment Reviewer cannot see compensation; Approver can read existing pay history but cannot change it. Creating an employee does not create a contactsIQ contact.

Employee detail

Selecting an employee opens their detail with five tabs: Overview, Compensation, Components, Payslips, and Advances.

Overview

The Overview summarises employment, payroll status, and the contactsIQ link. Select Edit employment to change:

• First name and Last name
• Employee number
• Employment status — Active, Inactive, Suspended, or Terminated.
• Payroll status — Active or Inactive.
• Employment end date
• Payroll eligible

Select Save employment to apply the change. Terminated employees require an end date. Employees are retained with their history; there is no hard-delete or archive workflow. Employment, payroll status and eligibility remain separate facts: review all three when ending employment. Finalized payroll and payslips keep their recorded snapshots after later employment/pay changes.

Note

These are independent facts, not an automatic workflow. payIQ does not force a particular order of status changes. What matters for payroll is the combination at the time you calculate: the employee must be employment-active, payroll-active, and payroll-eligible for the whole period. See Payroll for the inclusion rule.

The contactsIQ link accepts a reviewed, opaque contactsIQ identifier. Select Link contact to record it, or Deactivate link to end it. Deactivating preserves the historical link; it does not delete it, and payIQ never reads contactsIQ directly.

Compensation

Compensation terms are effective-dated. Each term has a pay basis (Monthly salary, Daily rate, or Hourly rate), an amount, a currency, and an effective period.

To add a term:

1. Choose the Pay basis.
2. Enter the Amount and Currency.
3. Set Effective from and, optionally, Effective to.
4. Select Add compensation term.

Compensation history is append-only. You add a new term for a change; you do not edit or delete an existing term. payIQ refuses overlapping effective dates for the same employee. At payroll time the term in force at the end of the period is used, so schedule a new term with the correct start date.

Caution

payIQ currently calculates payroll only for Monthly salary employees at the resident tax treatment. Daily-rate and hourly-rate terms can be recorded but are not yet supported by the calculation engine, which fails closed rather than guessing. See Payroll.

Components

The Components tab assigns this employee’s share of the workspace’s payroll component catalogue. Each assignment records a component, a configured amount or rate, a currency, and an effective date range. Select Assign component to add one.

Component assignments are also effective-dated and cannot overlap for the same component and employee. Currently only Fixed amount components are used by payroll calculation.

Payslips

The Payslips tab lists this employee’s payslips, newest first, once a payroll run containing them has been finalised. Each row links to a Printable payslip.

Advances

The Advances tab lists this employee’s advances with their outstanding, repaid, and issued amounts, and links back to the Advances workspace.

Payroll component catalogue

Below the employee list is the Payroll component catalogue — the typed, reusable definitions that employees can be assigned. Components have:

• a Code (uppercase) and Name,
• a Category — Earning, Employee deduction, or Employer cost,
• a Value mode — Fixed amount, Rate, or Quantity rate,
• a Taxable flag.

Select Add component to create one. Components are definitions only: they contain no formulas and no statutory rules.

What you can and cannot change

You can: create employees, edit the employment fields above, add compensation terms, assign components, link or deactivate a contactsIQ reference, and add payroll components.

You cannot: edit or delete a historical compensation term, delete a deactivated contactsIQ link, change a finalised payslip, or calculate payroll here. Compensation changes never alter a payslip that has already been issued.

Who can do what here

Action	Roles
View the employee list and basic employee detail	Any active member
Create an employee; edit employment fields	Any active member
View compensation, component assignments, and the component catalogue	Payroll Operator, Approver, Administrator
Add compensation, assign components, add payroll components	Payroll Operator, Administrator
Link or deactivate a contactsIQ reference	Any active member
View an employee’s payslips and advances	Payroll Operator, Approver, Administrator

A member without a payroll role sees the directory but not compensation, payroll configuration, payslips, or advances. See Roles & access.

Importing a workforce

1. Select Download template. Replace its example row with your employees.
2. Select Import employees and choose UTF-8 CSV or a single-sheet XLSX.
3. Select Validate & preview. Uploading creates no employees.
4. Review total, valid, invalid, duplicate and warning counts. Preview shows 25 rows per page, normalized pay, physical spreadsheet row numbers, and column-specific messages.
5. Correct every invalid row and upload again. An invalid row blocks the entire file. Matching names warn; they do not prevent distinct employees being added.
6. Select Continue to confirmation, then Confirm import. All employees and initial pay terms save together. If a conflict appears after preview, none of the rows save. Review the result before uploading again.

The mode is create new employees only. Existing employees are never silently updated. Use the employee editor and effective-dated compensation form for changes. A preview expires after 30 minutes and belongs to the user and workspace that created it. Switching workspace clears the preview. Recent import history shows actor, filename, status, counts and date, with no retained source file or row data.

Exact template format

Required columns: employee_number, first_name, last_name, employment_start_date, pay_basis, amount, currency, effective_from.

Optional columns: employment_status, payroll_status, payroll_eligible, tax_treatment, employment_end_date.

Field	Format
employee_number	Unique per workspace; 1–64 letters/digits plus dot, underscore, slash or hyphen. Start with a letter/digit; case-sensitive. Use spreadsheet text to preserve leading zeroes.
Dates	YYYY-MM-DD; XLSX date cells are supported. End must not precede start. Initial compensation must begin within employment.
pay_basis	monthly_salary, daily_rate or hourly_rate. Current payroll calculates monthly_salary only.
amount	Positive decimal, e.g. 2500.00. Zero and negative pay are rejected.
currency	Uppercase three-letter code; current payroll calculates GHS only.
employment_status	active, inactive, suspended, terminated. Blank defaults to active. Terminated requires employment_end_date.
payroll_status	active or inactive; blank defaults to active.
payroll_eligible	true or false; blank defaults to true.
tax_treatment	resident_monthly or unsupported; blank defaults to resident_monthly. Current payroll requires resident_monthly.

Do not add password, bank-detail, internal ID or unsupported HR columns. Blank rows are skipped but count toward the row limit. Duplicate staff numbers within the file or already in the workspace are definite errors. Identical names only warn. CSV/XLSX formulas are rejected rather than evaluated; use ordinary values.

Import limits and errors

Maximum 2 MiB, 1,000 rows including blank rows, 20 columns and 255 characters per cell. XLSX must have one worksheet; macro-enabled workbooks and XLSM are refused. Expanded workbook content is bounded to 20 MiB and 200 ZIP members. Unsupported columns, malformed files, formulas and oversized files return readable errors. The reported row number includes the header (first data row is row 2). Correct the named column and upload again. A later conflict or expired preview also requires a new upload. Files and previews are not retained for reopening from history.