Adding an employee

Adding an employee is how a new person enters your HR system. The form does two things in one go: it creates the durable Employee record (the person’s identity and contact details) and a first employment record (their starting role — type, department, position, manager, hire date). Optionally, it can also create a login account so the new joiner can use the self-service portal from day one. This page walks the form section by section, lists every field with its validation, and explains exactly what gets created when you save. You’ll find this at: /hr/employees/create (the Add Employee button on the Employees directory)

📷 Screenshot: Add Employee form showing the User Account, Personal Information and Employment Information cards — to be added.

Before you start

Pick the right business first. The employment record this form creates is tied to the business selected in your switcher. Adding the person while the wrong business is active places their contract under the wrong legal entity. Switch business before you start.
You need create rights. The Add Employee button only appears if your role can create employees (hr-employees:create); the create itself is authorised under hr:write.

The form

The form is three cards: User Account, Personal Information and Employment Information. Fields marked with a red asterisk (*) are required.

1. User Account

This top section decides whether the new employee also gets a login. Two modes:

Create a new account (default) — Hitaji provisions a login for the employee using the email you enter below, grants them self-service access, and emails a welcome message with temporary credentials. In this mode, email address becomes required.
Link an existing account — search for and pick a user who already has a Hitaji login. Selecting them pre-fills the personal fields (name, gender, date of birth, email, phone, address, city, country) from their account; pre-filled fields become read-only so the two records stay in sync.

If you don’t want a login created at all, switch to link mode and leave it without selecting a user.

2. Personal Information

Field	Required	Notes
First name	Yes	Leading/trailing spaces are trimmed; a blank or spaces-only name is rejected.
Last name	Yes	Same trimming/blank rule.
Other name	No	Middle/other name.
Gender	Yes	Male, Female or Other.
Date of birth	Yes (on this form)	Cannot be in the future, and must be within a plausible range. (At the API level date of birth is optional, but the web form asks for it.)
Email address	Conditionally	Required when “Create a new account” mode is on (an account can’t be created without it). Otherwise optional. Must be unique across your organisation.
Phone number	No	Validated as a real phone number; use international format, e.g. `+256 772 557 551`.
Address	No	Postal/mailing address.
City	No
Country	No

The API also accepts a residential address, marital status, national ID and passport number, but those aren’t on this quick-add form — add them afterwards via Edit on the profile. Note that national ID (like email) must be unique per organisation if you set one.

3. Employment Information

This card creates the employee’s first employment record.

Field	Required	Notes
Hire date	Yes	Defaults to today. A near-future hire date is allowed (forward-dated starts are normal); only a date more than five years out — or implausibly far in the past — is rejected. This date is also used as the employment’s start date.
Employment type	Yes	Full Time, Part Time, Contract or Intern. Defaults to Full Time.
Org Unit	No	The department/unit. You can pick an existing unit or create one inline (it’s added as a department).
Position	No	The job position. Pick from existing positions in your org structure.
Work location	No	Free text, e.g. “Main Office”.

Org units and positions come from your org structure; if the lists are empty, set them up there first (or create a unit inline).

4. Access requested (optional)

If the employee will use one of your business apps, tick “This employee needs to log in and use an app” and pick an access profile — a reviewed role like SACCO Teller or Farm Manager. Only profiles for apps this business runs appear. This does not grant access on save. It files a request that IT/Security reviews and approves — the card says so plainly. Once approved, the access is provisioned automatically as soon as the employee has a login. See Requesting and approving app access for the full flow. This card only appears for HR users who can manage employees. If the profile list is empty, IT/Security hasn’t published any access profiles for this business yet.

Saving — what gets created

When you choose Create Employee, Hitaji does the following, in order:

Validates the dates — rejects a future/implausible date of birth or a wildly out-of-range hire date.
Generates an employee number from your numbering series.
Checks for duplicates — rejects a duplicate email, duplicate national ID, or a login that’s already linked to another employee.
Optionally creates/links the login — in “create account” mode with an email, it provisions a user, grants the ERP-Employee role + ERP product, and emails the welcome message. In “link” mode, it links the chosen account and grants the same self-service access (no email, since they already have a password).
Creates the Employee record as Active.
Creates the first employment record with the type, start date (= hire date), org unit, position and work location you entered.
Files an access request, if you selected a profile in step 4 — but only after the employment record succeeds. It grants nothing; IT/Security approves it (see app access). If employment couldn’t be saved, no request is filed, and you’ll be told employment must be completed first.

On success you land on the new employee’s profile.

If account provisioning fails (for example the auth service is unreachable), the employee record is still created — only the login step is skipped. You can invite or link an account later from the profile.

Validation errors you may hit

Message	Cause
”First/Last name is required”	The name field was empty or only whitespace.
”Email is required for creating user account”	Create-account mode is on but no email was entered.
”Enter a valid phone number”	The phone number isn’t a valid international number.
”Date of birth cannot be in the future” / “implausibly far in the past”	Out-of-range date of birth.
”Hire date is implausibly far in the future / past”	Hire date more than five years ahead, or far in the past.
”An employee with this email address already exists”	Duplicate email in your organisation.
”An employee with this national ID already exists”	Duplicate national ID.
”This user is already linked to another employee”	The chosen login is attached to someone else.

Permissions

Action	Permission
See the Add Employee button	`hr-employees:create` (web button gate)
Create the employee (API)	`hr:write`

Employees (the people directory) — where the new employee appears
The employee profile & its tabs — fill in the rest of the detail after creating
Employment records & contracts — the employment record this form creates
Org Structure — departments, seats & reporting lines — set up departments and seats
The self-service portal — what the new joiner sees once they have a login

Overview

Getting Started

Employees

Recruitment

Employee Lifecycle

Leave

Attendance

Performance

Payroll

Self-Service

Reports

Settings

Before you start

The form

1. User Account

2. Personal Information

3. Employment Information

4. Access requested (optional)

Saving — what gets created

Validation errors you may hit

Permissions

​Before you start

​The form

​1. User Account

​2. Personal Information

​3. Employment Information

​4. Access requested (optional)

​Saving — what gets created

​Validation errors you may hit

​Permissions

​Related

Before you start

The form

1. User Account

2. Personal Information

3. Employment Information

4. Access requested (optional)

Saving — what gets created

Validation errors you may hit

Permissions

Related