> ## 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. # Transfers > A transfer moves an employee who is already on the books into a new department (org unit), position, manager, work location, or employment type β€” without… A transfer moves an employee who is already on the books into a new **department (org unit)**, **position**, **manager**, **work location**, or **employment type** β€” without re-hiring them. It always operates on an existing **active** employment, ends the current contract, and opens a fresh one carrying the new details forward. Because a transfer is a no-pay-change event, the employee's salary structure assignment is carried across automatically so payroll keeps running uninterrupted. This page covers the "Transfer" action on the employee profile, the fields you fill in, the effective date, and how a completed transfer shows up in the employee's Work History. **You'll find this at:** `/hr/employees/:id` (the **Transfer** button in the employee profile header) > πŸ“· *Screenshot: Employee profile header showing the Transfer button next to Edit β€” to be added.* > Hitaji 360 is **multi-business**. A transfer belongs to the same business as the employee's source contract, and it cannot move someone across businesses (see *Cross-business* below). Make sure the correct business is selected in the switcher before you start. *** ## Two transfer paths (important) Behind the scenes the system has **two** transfer mechanisms, and it helps to know which one you are using: 1. **The Transfer button on the employee profile (what most people use).** This calls the original, immediate transfer path. It ends the current employment and creates a new active one **straight away** β€” there is no scheduling and no approval step. The change takes effect on the date you choose. 2. **The Employee Transfer doctype (`/api/hr/employee-transfers`).** This is a newer, fuller transfer record that supports a draft β†’ submit β†’ apply lifecycle, scheduling for a future effective date, a status trail, and per-field before/after history. It is currently **API-only**. > ⚠️ **Current state:** These two paths are **not yet joined up**. The Transfer button uses path 1 (immediate). The richer Employee Transfer doctype (path 2, which feeds the Work History timeline) is only reachable via the API today β€” there is no screen for drafting, scheduling, or approving a transfer. As a result, a transfer done from the button **applies immediately** and **does not currently appear as a "Transferred" event in Work History** (the timeline reads from the doctype records, which the button doesn't write). The profile page also checks for a pending **Employee Transfer** approval, but the button's path never raises one, so that approval state will not appear for button-driven transfers. Both behaviours are flagged for the team. The rest of this page describes the **Transfer button** flow first, then the **Employee Transfer doctype** for completeness. *** ## Transferring an employee (the Transfer button) The **Transfer** button appears in the employee profile header only when: * you hold the **`hr:write`** permission, **and** * the employee's status is **ACTIVE**, **and** * the employee has an **active employment** record. If any of those are false, the button is hidden β€” there is nothing to transfer from. Click **Transfer** to open the *Transfer Employee* dialog. > πŸ“· *Screenshot: Transfer Employee dialog with the New Org Unit, New Position, New Manager and Effective Date fields β€” to be added.* ### Fields | Field | Required | Notes | | ----------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | **New Org Unit** | At least one of the three change fields | The target department. You can pick an existing org unit or quick-create one inline. The current org unit is shown beneath as a hint. | | **New Position** | (see above) | The target position. Current position shown as a hint. | | **New Manager** | (see above) | The new direct manager. You cannot pick the employee themselves as their own manager. Current manager shown as a hint. | | **Effective Date** | Yes | The date the transfer takes effect. Defaults to today. The current contract is end-dated the **day before** this date, and the new one starts on it. | | **Reason for Transfer** | No | Free text describing why the move is happening. | The dialog reminds you up front that **at least one of org unit, position, or manager must change** to make a meaningful transfer. ### What happens on submit When you confirm, the system: 1. Ends the employee's **current active employment** (end-dated the day before the effective date). 2. Creates a **new active employment** carrying the new org unit / position / manager forward, and copying over the unchanged details (employment type, country, pay currency, payroll calendar). 3. Seeds leave entitlement for the new employment. The change is immediate β€” you'll see a success toast. There is no approval queue on this path today. > The dialog contains a "submitted for approval" message that only shows if the API reports an approval is required. The current immediate path never reports this, so in practice you will always see "Employee transferred successfully". *** ## The Employee Transfer doctype (API-only) The newer **Employee Transfer** record (`/api/hr/employee-transfers`) is the enterprise-grade version of a transfer. It is not yet surfaced in the web app, but it is worth understanding because it drives the Work History timeline and supports scheduling. A transfer record is created as a **Draft**, then **submitted**. On submit: * if the **effective date is today or earlier**, it is **applied immediately**; * if the effective date is **in the future**, it is marked **Scheduled** and a daily job (runs at 04:00 UTC) applies it on the day it falls due. When it applies, it ends the source contract, creates the successor contract, **carries the active salary structure assignment forward** (so payroll doesn't silently skip the employee), and writes a before/after history row per changed field. ### Fields (Employee Transfer doctype) | Field | Required | Notes | | ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------- | | **businessId** | Yes | Must match the source contract's business **and** the active `X-Business-Id` context. | | **employeeId** | Yes | The employee being transferred. | | **employmentContractId** | Yes | The source (current) contract to transfer from. Must belong to the employee, and must still be active at submit/apply. | | **effectiveDate** | Yes | `YYYY-MM-DD`. Drives the immediate-vs-scheduled decision. | | **newOrgUnitId** | No | Target department. | | **newOrgPositionId** | No | Target position. | | **newManagerEmployeeId** | No | New direct manager. | | **newWorkLocation** | No | New work location (free text, up to 255 chars). | | **newEmploymentType** | No | New employment type. | | **reason** | No | Free text. | Only the fields that actually change are recorded as before/after pairs β€” a department-only transfer leaves position, manager, etc. untouched. ### Status values (Employee Transfer doctype) | Status | Meaning | | ------------- | ------------------------------------------------------------------------------------------------------ | | **Draft** | Created but not submitted. Editable; can be cancelled. | | **Scheduled** | Submitted with a future effective date; waiting for the daily job to apply it. Can still be cancelled. | | **Applied** | The contract change has been written. **Cannot be cancelled** β€” reverse it with a counter-transfer. | | **Failed** | The apply step raised an error; the record carries the error detail for manual remediation. | | **Cancelled** | Cancelled before it applied. | ### Cancelling A transfer can be cancelled only **before** it applies (while it is Draft or Scheduled). Once it is **Applied** the new contract already exists, so you must issue a fresh transfer in the opposite direction rather than cancelling. *** ## Cross-business transfers Transfers stay **within one business**. If you point a transfer at an org unit that belongs to a different business, the system stops you with a clear error and asks you to create a new contract in the target business manually instead. Full cross-business transfer (ending the contract in business A and opening one in business B) is **not yet supported**. *** ## How a transfer shows up in Work History The employee profile's **Work History** timeline builds its events from **applied** Employee Transfer doctype records (plus contracts and promotions). A transfer appears as a **"Transferred"** entry on the effective date, with an expandable **Details** section listing each changed field as *from β†’ to* (for example, *orgUnitId: Sales β†’ Marketing*). > ⚠️ **Current state:** Because the **Transfer button** uses the older immediate path (which does not write an Employee Transfer doctype record), button-driven transfers will **not** currently produce a "Transferred" timeline entry. Only transfers created through the Employee Transfer doctype API appear in Work History today. Flagged for the team. *** ## Permissions | Action | Permission | | --------------------------------------------------------------- | ---------- | | See and use the Transfer button | `hr:write` | | Create / submit / cancel / apply an Employee Transfer (doctype) | `hr:write` | | View an Employee Transfer record | `hr:read` | *** ## Related * [The employee profile & its tabs](/hr/user/employees/employee-profile) β€” where the Transfer button and Work History live * [Employment records & contracts](/hr/user/employees/employment-and-contracts) β€” what a transfer ends and recreates * [Promotions](/hr/user/employees/promotions) β€” the salary-bumping sibling of a transfer * [Org Structure β€” departments, seats & reporting lines](/hr/user/getting-started/org-structure) β€” the departments and seats a transfer targets * [Salary structures](/hr/user/payroll/salary-structures) β€” the assignment carried forward on transfer