Skip to main content
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. 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.

​
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 for how pay runs work in the product.

​
Notes and best practices

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.
  • 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. Responses use the shared envelope described in Response format.