Skip to main content
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 in the Releases tab.
​
EmployeesDirectors

​
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 startedSend 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 for the full request shape.
​
New APIReportsBeta

​
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 startedCall 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 walks through the definition document, relative-period tokens, and the export and scheduling flows.
​
New APIPayroll 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 startedJournals 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.
​
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 startedSend 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 for the resolution rules and error responses. To link additional organisations to your existing credentials, contact hello@flowpayroll.ai.