> ## 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.

# Applying for & Approving Leave

> A leave request (also called a leave application) is when someone asks for specific dates off.

A **leave request** (also called a leave application) is when someone asks for specific dates off. It is the heart of the leave module: the request moves through a short workflow, and when it is approved the days are taken from the employee's balance. Requests can be raised by an employee through self-service, or by HR on an employee's behalf.

This page covers the HR-side experience — the leave requests list, raising a request for someone, reviewing the queue, approving or rejecting, and what happens to the balance at each step.

**You'll find this at:** `/hr/leave` (the list) and `/hr/leave-requests/:id` (a single request)

> Requests, approvals, and balances are all **per business**. The list and calendar show only the active business's requests, and an approver cannot action a request whose contract belongs to another business. Confirm the business switcher before you work the queue.

> 📷 *Screenshot: the Leave Management list with the row checkboxes and the bulk Approve / Reject / Cancel action bar — to be added.*

***

## The list

The leave requests page is titled **Leave Management**. Four tabs sit across the top:

* **All** — every request.
* **Pending** — submitted requests awaiting a decision (the queue badge shows the count).
* **Approved**
* **Rejected**

Each row shows the **Employee**, **Leave Type** (the policy name), the **Duration** (date range), the number of **Days**, and the **Status**. You can search by employee, and filter by **Leave Type** and a **Start Date** range. Click any row to open the request's detail page. On a phone the list becomes a set of cards.

***

## Raising a request on behalf of an employee

If you hold **`hr:write`**, a **New Request** button appears. (There is no separate "create leave" permission — the create and cancel actions are governed by the coarse `hr:write`.)

> 📷 *Screenshot: the New Leave Request modal — employee picker, leave type, From/To dates, reason, and the "Submit for approval now" checkbox — to be added.*

In the **New Leave Request** form:

| Field                       | Required | Notes                                                                                                               |
| --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| **Employee**                | Yes      | Pick the employee (hidden when raising from a specific employee's profile).                                         |
| **Leave type**              | Yes      | The leave policy to draw against.                                                                                   |
| **From / To**               | Yes      | The start and end dates. *To* cannot be before *From* — the picker enforces it.                                     |
| **Reason**                  | No       | Context for the approver.                                                                                           |
| **Submit for approval now** | —        | On by default. When on, the request goes straight into the approval workflow; when off, it is saved as a **Draft**. |

The form shows the inclusive **Duration** in days as you pick the dates. On save you get either "submitted for approval" or "saved as draft", and you're taken to the new request.

***

## The statuses

| Status (on screen)   | Internal name     | Meaning                                  |
| -------------------- | ----------------- | ---------------------------------------- |
| **Draft**            | `Draft`           | Saved, not yet submitted.                |
| **Pending Approval** | `PendingApproval` | Submitted, awaiting an approver.         |
| **Approved**         | `Approved`        | Cleared — the balance has been deducted. |
| **Rejected**         | `Rejected`        | Turned down.                             |
| **Cancelled**        | `Cancelled`       | Withdrawn.                               |

***

## What approval does to the balance

This is the single most important thing to understand:

> **Leave is deducted on approval — never on submission.** A request sitting in *Pending Approval* has taken **nothing** from the balance. The deduction (a negative *LeaveApplication* ledger entry plus an increment to the balance's *Used* days) is written only when the request becomes **Approved**.

A direct consequence: there is **no provisional hold** to release. If a pending request is rejected or cancelled, there is no deduction to refund — because none was ever made. (The only refund case is cancelling a request that had *already been approved*; see below.)

When a policy **does not require approval**, submitting **auto-approves** the request immediately — so the deduction happens right then, on submit.

***

## Approving and rejecting

Reviewing the queue needs **`hr-leave:approve`**. A dedicated approver role typically holds `hr-leave:approve` and `hr-leave:read` (so it can see and action the queue) without the wider HR permissions.

**One at a time —** open a *Pending Approval* request and use the **Approve** or **Reject** buttons in the header.

* *Approve* asks you to confirm, then advances the request and deducts the balance.
* *Reject* opens a box for a **reason** (required) — the submitter is notified — and turns the request down. Rejecting also closes any open approval task so nothing is left dangling.

**In bulk —** tick rows in the list to reveal an action bar with **Approve** and **Reject** (and **Cancel**). Only *Pending Approval* rows are eligible for approve/reject; the bulk reject prompts once for a shared reason. Each row is processed independently, so you're told how many succeeded and how many couldn't.

The recorded approver is resolved from *you* (the signed-in person), so the audit trail always reflects who actually decided.

***

## Half-day leave

A request can mark **one** day inside its range as a half-day, deducting 0.5 instead of a full day. On the self-service apply form, ticking **Half day** (and, for multi-day ranges, picking *which* day is half) reduces the computed duration by half a day. A half-day cannot land on a holiday.

> The HR-side *New Leave Request* form does not currently expose the half-day option — raise half-day requests from the [self-service portal](/hr/user/self-service/my-leave), or set the dates to a single day there. (Flagged below.)

***

## Validations you may hit

When a request is created or submitted, Hitaji checks it against the leave type and policy rules. Common refusals:

* **Insufficient balance** — the request exceeds available days (unless the type has *Allow Negative Balance* on). The message states what's available versus requested.
* **Max leaves allowed / max continuous days / min days between applications** — limits set on the leave type.
* **Probation gate** — the type's *Applicable After* days have not yet elapsed since the contract start.
* **Backdated** — a past start date is refused unless the policy permits it (or your role is allowed to bypass).
* **Attendance already marked** — if the type has *Validate Attendance* on, a request overlapping a Present / Work-From-Home day is refused.
* **Block list / overlap** — the dates fall in a block-listed window, or overlap an existing leave.

***

## Cancelling or withdrawing

Cancelling needs **`hr:write`**. From a request's detail page (or the bulk action bar) use **Cancel Request**.

* Cancelling a **Draft** or **Pending Approval** request simply withdraws it — nothing was deducted, so nothing changes on the balance.
* Cancelling an **already-Approved** request **refunds** the deducted days: Hitaji writes a positive reversal to the ledger and restores the balance.

> ⚠️ **Current state:** The server *will* cancel an already-approved request (and refund it), **but the HR web screens only show the Cancel button for Draft and Pending-Approval requests** — the button is hidden once a request is Approved. So today there is no UI path to cancel an approved leave from the HR pages even though the backend supports it. (Flagged for the team.)
>
> Note the guard that does exist: cancelling an approved leave is **blocked** if a submitted payslip already covers the same period — you must cancel and amend the payslip first, so payroll never silently desyncs from the leave ledger.

***

## The request detail page

Opening a request shows three tabs:

* **Overview** — employee, leave type, start/end dates, duration, status, reason, approver, and approval time; a rejected request shows its rejection reason in a red callout. The header carries the Approve / Reject / Cancel actions when they apply.
* **Activity** — the timeline of changes plus a comment thread.
* **Workflow** — the approval workflow history.

***

## Permissions

| Action                                   | Permission                     |
| ---------------------------------------- | ------------------------------ |
| View the list / a request / the calendar | `hr-leave:read` (or `hr:read`) |
| Raise a request for an employee          | `hr:write`                     |
| Cancel a request                         | `hr:write`                     |
| Approve / reject a request               | `hr-leave:approve`             |

***

## Related

* [Leave overview](/hr/user/leave/overview) — the end-to-end model
* [My leave (self-service)](/hr/user/self-service/my-leave) — how employees apply for themselves
* [Leave calendar](/hr/user/leave/leave-calendar) — see approved leave on a calendar
* [Leave allocations (control panel)](/hr/user/leave/leave-allocations) — where the balances come from
* [Leave reports (balance & ledger)](/hr/user/leave/leave-reports) — audit deductions and refunds
* [Holiday lists](/hr/user/leave/holiday-lists) — how holidays affect day counts