> ## Documentation Index
> Fetch the complete documentation index at: https://docs.intermezzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pension

> Keep track of each employee's workplace pension.

Intermezzo assesses each employee for auto-enrolment when payroll runs, and records the pension membership when it enrols an employee automatically. You read the membership and record the employee's own decisions with these calls:

| Call | Use it to |
| - | - |
| [Get pension membership](https://docs.intermezzo.ai/api-reference/preview/great-britain/get-pension-membership.md) `GET …/employees/{employee_id}/pension/membership` | Read the current membership. Returns `404 PENSION_MEMBERSHIP_NOT_FOUND` while the employee has none. |
| [Get pension membership history](https://docs.intermezzo.ai/api-reference/preview/great-britain/get-pension-membership-history.md) `GET …/employees/{employee_id}/pension/membership/history` | Read every change to the membership |
| [Enrol employee in pension scheme](https://docs.intermezzo.ai/api-reference/preview/great-britain/enrol-employee-in-pension-scheme.md) `POST …/employees/{employee_id}/pension/enrol` | Record that the employee opted in or asked to join. Returns `409` if the employee is already a member. |
| [Record employee opt-out](https://docs.intermezzo.ai/api-reference/preview/great-britain/record-employee-opt-out.md) `POST …/employees/{employee_id}/pension/opt-out` | Record that the employee opted out. Returns `409` if the employee is not a member. |
| [Update per-employee pension rates](https://docs.intermezzo.ai/api-reference/preview/great-britain/update-per-employee-pension-rates.md) `PATCH …/employees/{employee_id}/pension/rates` | Change the employee's contribution rates and caps |
| [Get auto-enrolment assessments](https://docs.intermezzo.ai/api-reference/preview/great-britain/get-auto-enrolment-assessments.md) `GET …/employees/{employee_id}/pension/assessments` | Read the log of auto-enrolment assessments |

All paths start with `/gb/organizations/{organization_id}`.

Pension membership is not a satellite, so the rules in [Changing data](https://docs.intermezzo.ai/preview/concepts/changing-data.md) don't apply to these calls.

## What to send when

| Situation | You send | What happens |
| - | - | - |
| An eligible jobholder's earnings reach the auto-enrolment trigger | Nothing | Intermezzo enrols the employee in the organization's default scheme when the pay run is approved. The membership is `ACTIVE` with `entry_route` `AUTO_ENROLLED`. |
| A non-eligible jobholder asks to join | `POST …/pension/enrol` with `entry_route` `OPTED_IN` and the `notice_date` | Membership starts with the first pay period that begins after `notice_date` |
| An entitled worker asks to join | `POST …/pension/enrol` with `entry_route` `JOINED` and the `notice_date` | As above. The employer contributes only if the scheme is set up to pay for entitled workers. |
| The employee opts out within the one-month opt-out window | `POST …/pension/opt-out` with the `opt_out_date` | Membership becomes `OPTED_OUT` with `opt_out_route` `STATUTORY_OPT_OUT`. The contributions taken are refunded in the next pay run. |
| The employee leaves the scheme after the window | `POST …/pension/opt-out` with the `opt_out_date` | Membership becomes `OPTED_OUT` with `opt_out_route` `VOLUNTARY_CESSATION`. Nothing is refunded. |
| The employee was auto-enrolled before the payroll moved to Intermezzo | `POST …/pension/enrol` with `entry_route` `AUTO_ENROLLED`, the `enrolment_date` and the `worker_category` | Membership is recorded as `ACTIVE` from `enrolment_date`. Send it before the first pay run, so Intermezzo doesn't assess the employee again. |
| One employee's contributions differ from the scheme's, for example they agreed to pay more, or need relief at source in a salary sacrifice scheme | `PATCH …/pension/rates` with `valid_from` and the rates or `tax_treatment` that differ (with `wage_type_code` when you set `tax_treatment`) | A new membership version from `valid_from`. Fields you leave out keep their value; `null` returns a field to the scheme's default. |

## Example: an employee asks to join

A non-eligible jobholder gave notice on 10 November that they want to join the scheme.

```http Request theme={null}
POST /gb/organizations/{organization_id}/employees/{employee_id}/pension/enrol
```

```json Request body theme={null}
{
  "entry_route": "OPTED_IN",
  "notice_date": "2026-11-10"
}
```

The response is `201`. The membership is `ACTIVE` in the organization's default scheme, with the scheme's rates. Its `enrolment_date` is the start date of the employee's first pay period that begins after 10 November.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.