Skip to main content
The Pensions API manages everything Flow Payroll needs to run workplace pensions: the providers and schemes your organisation uses, the contribution groups employees belong to, each employee’s enrolment and postponement, the auto-enrolment (AE) assessments produced by pay runs, and the per-period calculation files you send to your provider. Use it to set up pensions before your first pay run, keep enrolments in sync with your HR system, and collect contribution data after each period. The service lives at /v2/pension relative to the gateway base URLs on the API reference introduction — for example, https://api.sandbox.flowpayroll.ai/v2/pension in sandbox.

​
Key concepts

  • Pension provider — the pension company itself. A provider has a name, a URL-friendly slug, and a flag indicating whether schemes with it require a payment source.
  • Pension scheme — your organisation’s arrangement with a provider. A scheme records its payment source, duty start date, last re-enrolment date, and an optional external reference. Scheme endpoints use the /pension-schema path.
  • Pension group — a set of contribution rules within a scheme: the pension type (relief at source, salary sacrifice, or net pay arrangement), the contribution basis, employee and employer factors, a National Insurance savings factor, and an optional external reference. One group can be marked as the organisation’s default.
  • Employee pension association — the link between an employee and a pension group, with an enrolment date and an option to send enrolment letters.
  • Auto-enrolment assessment — the AE result a pay run produces for each employee: the assessment outcome, worker age, earnings, and effective assessment date.
  • Postponement — a deferral of auto-enrolment, defined as a start-date definition and an eligibility-date definition (a value plus a frequency). Defaults are set at organisation level and can be overridden per employee.
  • Pension calculation — an employee’s contribution amounts for a specific period, retrievable per month or per provider and exportable as a CSV or provider-format file.

​
API structure

​
Pension providers

Manage providers with POST /pension-provider, PUT /pension-provider/{id}, GET /pension-provider/{id}, and DELETE /pension-provider/{id}. List them with GET /pension-provider, or look one up by its slug with GET /pension-provider/slug/{slug}.

​
Pension schemes

Create, update, retrieve, and delete schemes at /pension-schema and /pension-schema/{id}. GET /pension-schema/organisation returns every scheme in your organisation, each with its provider and groups embedded.

​
Pension groups

Manage contribution groups at /pension-group and /pension-group/{id}. Before creating a group, call GET /pension-group/allowed-bases to see the contribution bases the service accepts. Set externalReferenceId on a group to record the identifier your provider uses for it — a worker group or category code, for example. It is optional, and it is returned on every group, including the groups embedded in GET /pension-schema/organisation, so you can map our groups onto yours without a second lookup.
A group’s externalReferenceId is stored and returned for your own reconciliation. It is the scheme-level externalReferenceId that provider export files use as the employer reference.

​
Employee enrolment

POST /employee-pension associates an employee with a pension group, and GET /employee-pension/{employeeId} or DELETE /employee-pension/{employeeId} reads or removes the association. GET /employee-pension/batch fetches several employees at once via repeated employeeId query parameters. POST /employee-pension/{employeeId}/enrolment-letter triggers an enrolment letter for an employee.

​
Auto-enrolment

GET /auto-enrolment/assessments/payrun/{payrollConfigId}/{year}/{frequency}/{period} returns the assessments a pay run produced, and GET /auto-enrolment/complete/payrun/{payrollConfigId}/{year}/{frequency}/{period} lists employees whose enrolment is complete for that pay run. GET /auto-enrolment/not-complete and GET /auto-enrolment/not-auto-enrolments list employees with outstanding or no auto-enrolment, optionally including employee details.

​
Postponement

PUT /postponement sets an employee’s postponement, GET /postponement/{employeeId} reads it, and DELETE /postponement/{employeeId} removes it.

​
Organisation defaults

GET /organisation returns your organisation’s pension defaults: the default pension group, default postponement definitions, and the auto-enrolment mode. Update them with PUT /organisation/pension-default/postponement-settings and PUT /organisation/pension-default/auto-enrolment-settings.

​
Pension calculations and exports

Read calculations with GET /pension-calculation/by-year/{year}/by-month/{month}, or narrow to one provider with GET /pension-calculation/pension-provider/{pensionProviderId}/by-year/{year}/by-month/{month}. POST /pension-calculation records a calculation for an employee and period. For a pay period, fetch a CSV via GET /pension-calculation/csv/year/{year}/period/{period}/frequency/{frequency}/payroll-config/{payrollConfigId}, or request provider export files with POST /pension-calculation/export and list the generated files — including their file paths — through GET /pension-calculation/export/year/{year}/period/{period}/frequency/{frequency}/payroll-config/{payrollConfigId} or the equivalent /export-file-retrieval/pension-calculation/... endpoint.

​
Employee pension information

GET /pension-information/{employeeId} returns a single employee’s full pension picture in one call: their pension composition, latest auto-enrolment determination, and any postponement.

​
Typical workflow

  1. Create or look up your provider (GET /pension-provider/slug/{slug}), then create a scheme with POST /pension-schema.
  2. Check GET /pension-group/allowed-bases, then add one or more groups with POST /pension-group, marking one as the default.
  3. Set your organisation’s postponement and auto-enrolment defaults via the /organisation/pension-default endpoints — see the pension defaults guide.
  4. Enrol employees with POST /employee-pension, sending enrolment letters where required.
  5. Run your pay run, then read its AE results with GET /auto-enrolment/assessments/payrun/... and follow up on anyone listed by GET /auto-enrolment/not-complete.
  6. After the period, download the contribution CSV or request an export with POST /pension-calculation/export and retrieve the generated files for your provider.
For the product-side view of assessment outcomes, postponement, and letters, see the auto-enrolment guide.

​
Notes and best practices

  • Scheme endpoints use the path segment pension-schema (singular), not pension-scheme — copy paths exactly as documented.
  • Assessments, CSVs, and exports are addressed by payroll configuration, tax year, frequency, and period, so keep those identifiers from your pay run to hand.
  • Provider export files are described by records with a file path, provider slug, export group, and file type — generate them with the export POST, then list them with either retrieval endpoint.
  • Postponement definitions are a value plus a frequency at both organisation and employee level; an employee-level definition set via PUT /postponement takes the place of the defaults for that employee.

​
Authentication

Every request needs an X-Auth-Token header, and multi-organisation credentials also send X-Org-Id — see Authentication. Responses use the shared envelope described in Response format.