> ## Documentation Index > Fetch the complete documentation index at: https://docs.hitaji360.com/llms.txt > Use this file to discover all available pages before exploring further. # 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ā€¦ 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](/hr/user/employees/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](/hr/user/getting-started/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](/hr/user/employees/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: 1. **Validates the dates** ā€” rejects a future/implausible date of birth or a wildly out-of-range hire date. 2. **Generates an employee number** from your numbering series. 3. **Checks for duplicates** ā€” rejects a duplicate email, duplicate national ID, or a login that's already linked to another employee. 4. **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). 5. **Creates the Employee record** as **Active**. 6. **Creates the first employment record** with the type, start date (= hire date), org unit, position and work location you entered. 7. **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](/hr/user/employees/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](/hr/user/employees/employee-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` | *** ## Related * [Employees (the people directory)](/hr/user/employees/employees) ā€” where the new employee appears * [The employee profile & its tabs](/hr/user/employees/employee-profile) ā€” fill in the rest of the detail after creating * [Employment records & contracts](/hr/user/employees/employment-and-contracts) ā€” the employment record this form creates * [Org Structure ā€” departments, seats & reporting lines](/hr/user/getting-started/org-structure) ā€” set up departments and seats * [The self-service portal](/hr/user/self-service/overview) ā€” what the new joiner sees once they have a login