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

# Pensions API overview

> Manage workplace pensions end to end — providers, schemes, contribution groups, employee enrolment, auto-enrolment assessment, postponement, and per-period calculation exports.

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](/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.

<Note>
  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.
</Note>

### 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](/guides/setup/pension-defaults).
4. Enrol employees with `POST /employee-pension`, sending enrolment letters where required.
5. [Run your pay run](/guides/pay-runs/running-a-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.

<Tip>
  For the product-side view of assessment outcomes, postponement, and letters, see the [auto-enrolment guide](/guides/pensions/auto-enrolment).
</Tip>

## 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](/api-reference/authentication). Responses use the shared envelope described in [Response format](/api-reference/response-format).