> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowpayroll.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Holiday & leave API overview

> Configure holiday accrual schemes, carry in opening balances, record leave taken, and read back accrual history and 52-week average holiday pay rates.

The Holiday & leave API manages holiday accrual and leave for your employees. You set an accrual scheme for the organisation, give individual employees their own configuration where needed, carry in opening balances, and record each period of holiday taken. You can then read back a full accrual history and the 52-week average rate used for holiday pay. For the product view of these features, see [Holiday and leave](/guides/holiday/holiday-and-leave).

All endpoint paths on this page are relative to the service base path `/v1/holiday`, appended to the gateway base URLs listed in the [API reference introduction](/api-reference/introduction).

## Key concepts

* **Accrual scheme** — how holiday builds up, set by `holidayAccrualType`. With `PercentageOfTime`, holiday accrues as a percentage of time worked (`accrualRatePercentage`) and is drawn down when leave is taken. With `RolledUp`, holiday pay is rolled up as a percentage of pay (`payRatePercentage`) instead of being banked.
* **Organisation configuration** — the organisation-wide accrual scheme. There is one per organisation, holding the accrual type, its rate, and the accrual reset date.
* **Employee configuration** — a per-employee accrual scheme with the same shape as the organisation configuration, for employees whose holiday arrangement is set individually.
* **Accrual reset date** — the day and month (`accrualResetDay`, `accrualResetMonth`) on which the leave year starts. Holiday history is summarised per leave year between reset dates.
* **Opening balance** — an employee's starting position when you join Flow Payroll mid-year. For percentage-of-time schemes it captures the weeks already counted (`weeksCount`), the base hours, and the base gross pay carried in.
* **Holiday taken record** — a single period of leave for an employee: a date, a description, the hours taken, and an optional pay rate.
* **52-week average rate** — the average holiday pay rate calculated from the last 104 weeks of accruals, returned with the number of weeks that made it into the average.

## API structure

### Organisation configuration

Manage the organisation-wide accrual scheme at `/organisation`. Create it with `POST /organisation`, then read, replace, or remove it with `GET`, `PUT`, and `DELETE` on the same path.

### Employee configuration

Manage a per-employee scheme at `/employees/{employeeId}`. The same four operations apply: `POST` to create, `GET` to retrieve, `PUT` to update, and `DELETE` to remove the employee's configuration.

### Opening balances

Carry in an employee's existing accrual at `/employees/{employeeId}/opening-balance`. Create, retrieve, update, and delete the opening balance with `POST`, `GET`, `PUT`, and `DELETE`.

### Holiday taken

Record leave with `POST /employees/{employeeId}/taken`. Work with an individual record at `/employees/{employeeId}/taken/{id}` — retrieve it with `GET`, correct it with `PUT`, or remove it with `DELETE`.

### History and average rate

Read an employee's accrual history with `GET /employees/{employeeId}/history`, optionally filtered with the `fromDate` and `toDate` query parameters. The response pairs per-leave-year summaries (opening balance, accrued, taken, and closing balance in hours and value) with the underlying transaction list. Get the current 52-week average rate with `GET /employees/{employeeId}/average-rate`.

## Typical workflow

1. Create the organisation configuration with `POST /organisation`, choosing the accrual type, its rate, and the accrual reset date.
2. Create an employee configuration with `POST /employees/{employeeId}` for any employee whose scheme is set individually.
3. If you are migrating mid-year, create an opening balance for each affected employee with `POST /employees/{employeeId}/opening-balance`.
4. Record leave as it is taken with `POST /employees/{employeeId}/taken`, supplying the date, hours, and optionally a rate.
5. Before paying holiday, check the employee's rate with `GET /employees/{employeeId}/average-rate`.
6. Reconcile balances at any point with `GET /employees/{employeeId}/history`, filtering by date range where useful.

Accrued hours and value appear in the history as pay is processed — see [Running a pay run](/guides/pay-runs/running-a-pay-run) for how pay runs work in the product.

## Notes and best practices

<Note>
  Configurations and opening balances are singleton resources. Each organisation has at most one configuration, and each employee has at most one configuration and one opening balance — use `PUT` to change them rather than creating duplicates.
</Note>

* The 52-week average rate is calculated from the last 104 weeks of accruals, and the response includes `weeksInAverage` so you can see how many weeks were available.
* Opening balances with a `percentageOfTime` section count towards the average through `weeksCount`, `baseHours`, and `baseGross` — set them accurately when migrating.
* The `rate` on a holiday taken record is optional; supply it only when you want to fix the rate for that record.
* History transactions carry running balances (`balanceHours`, `balanceValue`), so the transaction list doubles as a ledger you can reconcile against.

## Authentication

Every request needs an `X-Auth-Token` header, and credentials with access to more than one organisation also send `X-Org-Id` — see [Authentication](/api-reference/authentication). Responses use the shared envelope described in [Response format](/api-reference/response-format).