> ## 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. # Remove an employee from their pension > The single removal surface. optOutDate (or today) becomes the membership end date. processRefund=true refunds every settled member contribution from enrolment to that date on the next payslip, and is REFUSED when that date falls outside the statutory opt-out period unless refundOutsideOptOutPeriodReason says why. Use GET /employee-pension/{employeeId}/refund-preview first to show the operator what would be refunded. Returns the membership end reason and the refunded amounts per period. ## OpenAPI ````yaml /api-reference/specs/pension-v2.json delete /employee-pension/{employeeId} openapi: 3.0.4 info: title: FlowPayroll Pension API version: v2 servers: - url: https://api.sandbox.flowpayroll.ai/v2/pension security: [] tags: - name: Pension providers description: >- Look up the pension providers available to your organisation. Providers are set up in the product, so the API exposes them read-only. - name: Pension schemes description: >- Your organisation's arrangements with providers. Scheme endpoints use the /pension-schema path. - name: Pension groups description: >- Contribution rule sets within a scheme: pension type, contribution basis, and employee and employer factors. - name: Employee enrolment description: >- Associate employees with pension groups, remove associations, and send enrolment letters. - name: Pension information description: >- An employee's full pension picture in one call: composition, latest assessment, and postponement. - name: Auto-enrolment description: >- Assessment results per pay run, employees with outstanding or no auto-enrolment, and a stateless assessment preview. - name: Postponement description: Defer auto-enrolment per employee, overriding the organisation defaults. - name: Organisation defaults description: >- The organisation's default pension group, postponement definitions, and auto-enrolment mode. - name: Pension calculations description: >- Per-period contribution amounts, the contributions CSV, and provider export files. - name: Provider submissions description: >- Send a completed pay run to its connected pension provider, approve the payment, and read back what the provider reported: opt-outs, stopped contributions, refunds and schedules. paths: /employee-pension/{employeeId}: delete: tags: - Employee enrolment summary: Remove an employee from their pension description: >- The single removal surface. optOutDate (or today) becomes the membership end date. processRefund=true refunds every settled member contribution from enrolment to that date on the next payslip, and is REFUSED when that date falls outside the statutory opt-out period unless refundOutsideOptOutPeriodReason says why. Use GET /employee-pension/{employeeId}/refund-preview first to show the operator what would be refunded. Returns the membership end reason and the refunded amounts per period. operationId: DeleteEmployeePensionAssociation parameters: - name: employeeId in: path required: true schema: type: string - name: optOutDate in: query description: >- The date the member left the scheme. Defaults to today. Supplying it asserts an opt-out, so the ending is recorded as OptOut unless reason says otherwise. Must not be earlier than the employee's enrolment date. schema: type: string description: >- The date the member left the scheme. Defaults to today. Supplying it asserts an opt-out, so the ending is recorded as OptOut unless reason says otherwise. Must not be earlier than the employee's enrolment date. format: date - name: processRefund in: query description: >- The employer's decision to refund the member's contributions through payroll: every settled member contribution from enrolment to the opt-out date, on the next payslip. Defaults to false. Whether the opt-out is inside the statutory opt-out period is the employer's assessment (The Pensions Regulator's detailed guidance 7); the employer holds the notice and the evidence. schema: type: boolean description: >- The employer's decision to refund the member's contributions through payroll: every settled member contribution from enrolment to the opt-out date, on the next payslip. Defaults to false. Whether the opt-out is inside the statutory opt-out period is the employer's assessment (The Pensions Regulator's detailed guidance 7); the employer holds the notice and the evidence. - name: reason in: query description: >- Why the membership ended, as the employer asserts it: OptOut, MembershipCeased or AdministrativeRemoval. Defaults to OptOut when an optOutDate is supplied or processRefund=true, and to AdministrativeRemoval for a bare removal with neither. Only OptOut and MembershipCeased suppress re-enrolment until the scheme's next 3-yearly cyclical re-enrolment date. schema: enum: - OptOut - MembershipCeased - AdministrativeRemoval type: string description: >- Why the membership ended, as the employer asserts it: OptOut, MembershipCeased or AdministrativeRemoval. Defaults to OptOut when an optOutDate is supplied or processRefund=true, and to AdministrativeRemoval for a bare removal with neither. Only OptOut and MembershipCeased suppress re-enrolment until the scheme's next 3-yearly cyclical re-enrolment date. - name: refundOutsideOptOutPeriodReason in: query description: >- Why a refund is being made even though the membership ended OUTSIDE the statutory opt-out period. Required in that case and rejected in any other. Outside the period a defined-contribution scheme owes no refund (The Pensions Regulator's detailed guidance 7, paras 25 and 55-57); the employer may still choose to pay one, and this records that it was a deliberate decision and who made it. Call GET /employee-pension/{employeeId}/refund-preview to find out whether the date is inside the period. schema: type: string description: >- Why a refund is being made even though the membership ended OUTSIDE the statutory opt-out period. Required in that case and rejected in any other. Outside the period a defined-contribution scheme owes no refund (The Pensions Regulator's detailed guidance 7, paras 25 and 55-57); the employer may still choose to pay one, and this records that it was a deliberate decision and who made it. Call GET /employee-pension/{employeeId}/refund-preview to find out whether the date is inside the period. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/EmployeePensionOptOutModelResponseBody' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ObjectResponseBody' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ObjectResponseBody' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ObjectResponseBody' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ObjectResponseBody' components: schemas: EmployeePensionOptOutModelResponseBody: required: - message type: object properties: message: $ref: '#/components/schemas/MessageWithTokenResponse' content: $ref: '#/components/schemas/EmployeePensionOptOutModelContentResponse' validationIssues: type: array items: $ref: '#/components/schemas/ValidationIssue' nullable: true errors: type: array items: $ref: '#/components/schemas/Error' description: >- Deprecated: the same issues as `validationIssues` (`reasonText` is `reason`, `reasonId` is `reasonToken`, `reasonParameters` is `reasonTokenArguments`). Read `validationIssues`; this will be removed. nullable: true readOnly: true deprecated: true metadata: allOf: - $ref: '#/components/schemas/ContentMetadataResponse' description: >- Deprecated: the same values as `content.metadata`. Read that; this will be removed. deprecated: true additionalProperties: false description: >- The response envelope every FlowPayroll API answers with: a `message`, the `content`, and any `validationIssues`. `errors` and the top-level `metadata` are deprecated copies of `validationIssues` and `content.metadata`, and will be removed. ObjectResponseBody: required: - message type: object properties: message: $ref: '#/components/schemas/MessageWithTokenResponse' content: $ref: '#/components/schemas/ObjectContentResponse' validationIssues: type: array items: $ref: '#/components/schemas/ValidationIssue' nullable: true errors: type: array items: $ref: '#/components/schemas/Error' description: >- Deprecated: the same issues as `validationIssues` (`reasonText` is `reason`, `reasonId` is `reasonToken`, `reasonParameters` is `reasonTokenArguments`). Read `validationIssues`; this will be removed. nullable: true readOnly: true deprecated: true metadata: allOf: - $ref: '#/components/schemas/ContentMetadataResponse' description: >- Deprecated: the same values as `content.metadata`. Read that; this will be removed. deprecated: true additionalProperties: false description: >- The response envelope every FlowPayroll API answers with: a `message`, the `content`, and any `validationIssues`. `errors` and the top-level `metadata` are deprecated copies of `validationIssues` and `content.metadata`, and will be removed. MessageWithTokenResponse: required: - token type: object properties: text: type: string nullable: true token: type: string description: >- Stable snake_case key for the message, for clients that translate it. nullable: true tokenArguments: type: array items: $ref: '#/components/schemas/ValidationIssueArgument' nullable: true textId: type: string description: >- Deprecated: the same value as `token`. Read that; this will be removed. nullable: true readOnly: true deprecated: true textParameters: type: array items: $ref: '#/components/schemas/Pair' description: >- Deprecated: the same values as `tokenArguments`. Read that; this will be removed. nullable: true readOnly: true deprecated: true additionalProperties: false description: >- What happened, as English `text` and a stable `token` to translate from. `textId` and `textParameters` are deprecated copies of `token` and `tokenArguments`. EmployeePensionOptOutModelContentResponse: type: object properties: data: $ref: '#/components/schemas/EmployeePensionOptOutModel' metadata: $ref: '#/components/schemas/ContentMetadataResponse' additionalProperties: false ValidationIssue: type: object properties: field: type: string nullable: true reason: type: string nullable: true reasonToken: type: string nullable: true reasonTokenArguments: type: array items: $ref: '#/components/schemas/ValidationIssueArgument' nullable: true additionalProperties: false Error: type: object properties: field: type: string nullable: true reasonText: type: string nullable: true reasonId: type: string nullable: true reasonParameters: type: array items: $ref: '#/components/schemas/Pair' nullable: true additionalProperties: false description: >- Deprecated: an entry of the old `errors` list. Read `validationIssues` instead. deprecated: true ContentMetadataResponse: type: object properties: dateFormat: type: string nullable: true dateTimeFormat: type: string nullable: true paginationToken: type: string nullable: true additionalProperties: false ObjectContentResponse: type: object properties: data: nullable: true metadata: $ref: '#/components/schemas/ContentMetadataResponse' additionalProperties: false ValidationIssueArgument: type: object properties: name: type: string nullable: true value: nullable: true additionalProperties: false Pair: type: object properties: key: type: string nullable: true value: type: string nullable: true additionalProperties: false description: >- Deprecated: a key and value of the old `textParameters` and `reasonParameters`. deprecated: true EmployeePensionOptOutModel: required: - employerRefundTotal - membershipEndReason - refundTotal - refundedPeriods type: object properties: membershipEndReason: enum: - OptOut - MembershipCeased - AdministrativeRemoval type: string description: |- Why the membership ended (or would end, on a preview): "OptOut" (the employer processed an opt-out), "MembershipCeased" (the member left outside the opt-out period) or "AdministrativeRemoval" (a data correction with no statutory event). nullable: true refundTotal: type: number description: |- Member contributions refunded (or, on a preview, refundable) to the employee on their next payslip. Includes additional voluntary contributions deducted from pay. format: double employerRefundTotal: type: number description: >- Employer contributions for the refunded periods. The provider returns these to the employer directly; they never appear on the payslip. Reported so the employer can reconcile the provider's refund. format: double enrolmentDate: type: string description: >- The date the member was enrolled. Shown so a reader can see what the opt-out period below was counted from. Null when it cannot be resolved. format: date nullable: true optOutPeriodEndDate: type: string description: >- The last day an opt-out counted from the enrolment date would still carry a refund (TPR DG7: one month beginning with that date). INDICATIVE, not authoritative. The statutory period runs from the LATER of becoming an active member and receiving the enrolment information, and the platform does not hold the date the enrolment letter reached the worker. So this is the EARLIEST the period can end: a leaving date on or before it is certainly inside, one after it may still be inside if the letter went out later. Whether a refund is due remains the employer's assessment, against what the provider confirms. format: date nullable: true enrolmentInformationSentDate: type: string description: >- The day the member was given their enrolment information, where the platform can evidence it. The window runs from the later of this and the enrolment date, so without it the end date reads as bad arithmetic: enrolled on the 25th, period ending on the 27th of the next month. Null when we hold no evidence, in which case the window is counted from the enrolment date. format: date nullable: true withinOptOutPeriod: type: boolean description: >- Whether the date given falls on or before `optOutPeriodEndDate`. Null when the enrolment date is unknown, which is the one case nobody can answer. Read it with the caveat on `optOutPeriodEndDate`: false does not prove a refund is not due. nullable: true optOutWindowBasis: type: string description: >- Which test the window came from, because they are not interchangeable: "StatutoryOptOutPeriod" is the one month an automatically enrolled jobholder or an opt-in holds by right (TPR DG7 §7-8, §17-18); "SchemeRulesCessation" is the 30 days from active membership that a contractually enrolled worker or an entitled worker gets instead, and only where the scheme rules provide a refund (§9, §57-58); "Unknown" means the enrolment route could not be determined, so no test is asserted and the employer should not read the dates as an answer. nullable: true refundedPeriods: type: array items: $ref: '#/components/schemas/RefundedPensionPeriodModel' description: |- The settled pay periods whose contributions make up the refund, one entry per pay run. Empty when nothing was refunded through payroll. nullable: true additionalProperties: false description: |- The result of removing an employee from their pension (or of a refund preview). Whether a removal is a statutory opt-out inside The Pensions Regulator's opt-out period is the employer's assessment; the platform records the assertion and processes the refund when asked to. RefundedPensionPeriodModel: required: - amount - employerAmount - period - taxYear type: object properties: taxYear: type: integer description: The tax year the pay period belongs to (e.g. 2026 for 2026/27). format: int32 period: type: integer description: The pay period number within the tax year. format: int32 amount: type: number description: Member contributions refunded for this pay period, via the payslip. format: double employerAmount: type: number description: >- Employer contributions for this pay period, returned by the provider to the employer. format: double additionalProperties: false description: One settled pay period inside a refund. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.