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

# What's new in the API

> New services, endpoints, headers, and behaviour changes in the Flow Payroll API — updated as they ship.

Every change to the Flow Payroll API lands here, newest first: new services and endpoints, new request headers, and any change in behaviour your integration should know about. Use the tags to filter by area, or subscribe to the RSS feed to hear about changes as they ship. For product-wide release notes, see [What's new](/releases/whats-new) in the Releases tab.

<Update label="9 August 2026" tags={["Employees", "Directors"]}>
  ## Split opening balances for directors

  Opening balances now describe a director's year in the detail HMRC needs, so you can migrate a director to Flow Payroll part-way through a tax year — including the awkward cases, where someone is a director for only part of the year or changes NI category letter mid-year.

  **What's new**

  * `openingBalanceDirector.{year}` gains `niBandResult`, a map keyed by NI category letter carrying the NI-able gross and contributions accrued while the director basis applied, with optional band splits.
  * Earnings are now split by where they were assessed: `openingBalance` covers the employment as a regular employee, `openingBalanceDirector` covers the director stretch from appointment onwards. Each keeps its own band splits.
  * The flat totals on `openingBalanceDirector` (`grossForEmployeeNi`, `grossForEmployerNi`, `ni`, `employerNi`) are **deprecated as input** — they cannot express more than one NI letter in a year. They still work, and we still return them as the sum across letters.
  * Opening balance updates return specific validation issues (unknown NI letter, negative values, band splits exceeding the letter's gross) instead of one generic message.

  **Get started**

  Send `niBandResult` on `PUT /employees/{employeeId}/opening-balance` rather than the flat totals. For a director on the **annual** basis appointed before the tax year began, leave `bandResults` out of `openingBalance` — the annualised calculation derives the band split itself. For the **alternative** basis, include `bandResults` inside each `openingBalanceDirector` letter. See the [Pay API overview](/api-reference/pay-api/overview) for the full request shape.
</Update>

<Update label="28 July 2026" tags={["New API", "Reports", "Beta"]}>
  ## Reports API (Beta)

  You can now query your payroll data programmatically. The new **Reports** service takes a single JSON report definition — dataset, columns, filters, grouping, aggregation, sorting — and runs it synchronously, exports it at scale, or delivers it on a schedule. It ships in **beta**: build against it, and expect refinements before general availability.

  **What's new**

  * A new **Reports** group in the sidebar (badged Beta), served under `/v1/report`.
  * Dataset discovery endpoints: list the queryable datasets and inspect each field catalog — types, filterability, groupability, aggregations, and sensitivity.
  * `POST /reports/run` for synchronous runs of inline definitions (10,000-row cap), plus saved report definitions you can re-run by ID.
  * Asynchronous exports to CSV or JSONL for up to 5,000,000 rows, downloaded via presigned URLs.
  * Cron schedules on saved definitions, delivering exports by HMAC-signed webhook or email.
  * A run history endpoint that doubles as an audit trail, recording access to sensitive fields.

  **Get started**

  Call `GET /v1/report/datasets` to see what you can query, then iterate on a definition with `POST /v1/report/reports/run`. The [Reports API overview](/api-reference/reports/overview) walks through the definition document, relative-period tokens, and the export and scheduling flows.
</Update>

<Update label="8 July 2026" tags={["New API", "Payroll journals"]}>
  ## Payroll journals API

  You can now drive payroll journals entirely over the API. A new **Payroll journals** service turns every finalised pay run into a balanced double-entry journal — mapped to your chart of accounts, split by department or cost centre, and exportable to Xero or any other accounting system — without touching the Flow Payroll UI.

  **What's new**

  * A new **Payroll journals** group in the sidebar, served under `/v1/journal`.
  * Template endpoints to define how journals are built: create, clone, and update templates, manage pay-element and control-account mappings, configure split dimensions, and import mappings from systems such as Sage, Xero, Staffology, and IRIS.
  * Preview endpoints to render a template against a pay run before you rely on it, including CSV and PDF preview exports.
  * Journal endpoints to list journals, fetch the latest version for a pay run, download exports (Xero Manual Journal CSV, generic CSV, or PDF) via presigned URLs, and rebuild or reissue a journal after corrections.
  * Organisation-wide defaults via `GET`/`PUT /org-journal-settings`, plus export-option lookups for presets, date formats, and narration and reference tokens.

  **Get started**

  Journals are generated automatically as soon as payslips are calculated — start by creating a template with `POST /v1/journal/templates`, then browse the **Payroll journals** group in the sidebar for the full surface. For how templates, mappings, and splits behave in the product, read the [Payroll journals guide](/guides/pay-runs/payroll-journals).
</Update>

<Update label="2 July 2026" tags={["Authentication"]}>
  ## One set of credentials, many organisations

  Your API credentials are no longer tied to a single organisation. The platform now separates **who you are** from **which organisation you're acting on**: your token (sent as `X-Auth-Token`) proves your identity exactly as before, and the new `X-Org-Id` request header states which organisation the request applies to. One `client_id`/`client_secret` pair can now be granted access to many organisations — useful for bureaus, accountants, and group companies.

  **What's new**

  * A new `X-Org-Id` request header, accepted on every endpoint, naming the organisation the request is for. Switching organisation is just sending a different value on the next request — the same token stays valid across all your organisations, with no re-authentication.
  * A new **Authentication API** group in the sidebar. Call `GET /v1/authentication/my-organisations` to list every organisation your credentials can act on — it works before an organisation is selected, so you can use it to build an organisation picker.
  * Nothing breaks for existing integrations: if your credentials access exactly one organisation, requests without `X-Org-Id` resolve to it automatically. With access to more than one, omitting the header falls back to your configured default organisation; with no default set, the request is rejected with `403` so you choose explicitly.

  **Get started**

  Send `X-Org-Id` explicitly on every request, even while your credentials access only one organisation — your integration then keeps working unchanged the day a second organisation is granted. See [Authentication → Choosing an organisation](/api-reference/authentication#choosing-an-organisation) for the resolution rules and error responses. To link additional organisations to your existing credentials, contact [hello@flowpayroll.ai](mailto:hello@flowpayroll.ai).
</Update>