> ## 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. # Enrol employee in pension scheme > Records an employee's enrolment in the workplace pension scheme. Use this to record auto-enrolment triggered by eligibility assessment, voluntary opt-in by a non-eligible jobholder, or a worker choosing to join. If a membership record does not yet exist, one is created automatically. Returns 409 if the employee is already actively enrolled — use the opt-out endpoint first if re-enrolment is needed after a status change. ## OpenAPI ````yaml /api-reference/preview.json post /gb/organizations/{organization_id}/employees/{employee_id}/pension/enrol openapi: 3.1.0 info: title: FastAPI version: 0.1.0 servers: [] security: [] paths: /gb/organizations/{organization_id}/employees/{employee_id}/pension/enrol: post: tags: - Great Britain - Pension summary: Enrol employee in pension scheme description: >- Records an employee's enrolment in the workplace pension scheme. Use this to record auto-enrolment triggered by eligibility assessment, voluntary opt-in by a non-eligible jobholder, or a worker choosing to join. If a membership record does not yet exist, one is created automatically. Returns 409 if the employee is already actively enrolled — use the opt-out endpoint first if re-enrolment is needed after a status change. operationId: >- enrol_employee_gb_organizations__organization_id__employees__employee_id__pension_enrol_post parameters: - name: organization_id in: path required: true schema: anyOf: - type: string - type: string format: uuid title: Organization Id - name: employee_id in: path required: true schema: anyOf: - type: string - type: string format: uuid title: Employee Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PensionEnrolRequest' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PensionMembershipResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - BearerToken: [] components: schemas: PensionEnrolRequest: properties: enrolment_date: type: string format: date title: Enrolment Date description: Date on which enrolment takes effect entry_route: $ref: '#/components/schemas/PensionEntryRoute' description: >- How the employee entered the scheme (AUTO_ENROLLED, OPTED_IN, JOINED) worker_category: $ref: '#/components/schemas/WorkerCategory' description: Worker category determined at the time of enrolment enrolment_communication_date: anyOf: - type: string format: date - type: 'null' title: Enrolment Communication Date description: >- Date the statutory enrolment communication was issued to the employee. Required to validate the statutory one-month opt-out window. scheme_id: anyOf: - type: string - type: string format: uuid - type: 'null' title: Scheme Id description: >- Pension scheme to enrol into. Stored as provided; not auto-resolved on auto-enrolment — the auto-enrol path stamps the org default scheme at enrolment time. employee_rate: anyOf: - type: number maximum: 1 minimum: 0 - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Employee Rate description: Employee contribution rate override (null = use scheme default) employer_rate: anyOf: - type: number maximum: 1 minimum: 0 - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Employer Rate description: Employer contribution rate override (null = use scheme default) employee_cap: anyOf: - type: number minimum: 0 - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Employee Cap description: Per-period employee contribution cap override employer_cap: anyOf: - type: number minimum: 0 - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Employer Cap description: Per-period employer contribution cap override tax_treatment: anyOf: - $ref: '#/components/schemas/PensionTaxTreatment' - type: 'null' description: >- Per-employee tax treatment override (e.g. RAS when scheme is salary sacrifice) wage_type_code: anyOf: - type: string - type: 'null' title: Wage Type Code description: >- Wage type code for pension deduction; MUST be provided when tax_treatment is set additionalProperties: true type: object required: - enrolment_date - entry_route - worker_category title: PensionEnrolRequest description: >- Request to enrol an employee in the pension scheme. Use to record auto-enrolment, voluntary opt-in, or a worker joining the scheme. If no scheme_id is provided, the organisation's current active scheme is used. Optional rate override fields allow setting per-employee rates at enrolment time; null values fall back to scheme defaults. PensionMembershipResponse: properties: valid_from: type: string format: date title: Valid From description: Date from which this version of the membership record is effective valid_to: anyOf: - type: string format: date - type: 'null' title: Valid To description: >- Date on which this version expires (exclusive); null = current version. Set automatically when a new version is created employee_rate: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Employee Rate description: >- Per-employee employee contribution rate override; null = use scheme default employer_rate: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Employer Rate description: >- Per-employee employer contribution rate override; null = use scheme default employee_cap: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Employee Cap description: >- Per-employee maximum employee contribution per period; null = use scheme default employer_cap: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Employer Cap description: >- Per-employee maximum employer contribution per period; null = use scheme default tax_treatment: anyOf: - $ref: '#/components/schemas/PensionTaxTreatment' - type: 'null' description: >- Per-employee tax treatment override (e.g. RELIEF_AT_SOURCE for an employee whose scheme is SALARY_SACRIFICE); null = use scheme default wage_type_code: anyOf: - type: string - type: 'null' title: Wage Type Code description: >- Per-employee wage type code override for the payslip deduction line; null = use scheme default. Required when tax_treatment override is set status: $ref: '#/components/schemas/PensionMembershipStatus' description: >- Current membership status: ACTIVE (enrolled, contributions calculated), OPTED_OUT (left the scheme; contributions refunded if within 1-month opt-out window), NOT_ENROLLED (no active membership) version: type: integer title: Version description: >- Sequential version number of this membership record; starts at 0, incremented on each change (status change, rate update, etc.) worker_category: anyOf: - $ref: '#/components/schemas/WorkerCategory' - type: 'null' description: >- AE worker category at enrolment time: ELIGIBLE_JOBHOLDER (age 22–SPA, earnings ≥ trigger — employer must enrol), NON_ELIGIBLE_JOBHOLDER (outside age/earnings band — can opt in), ENTITLED_WORKER (earnings below lower limit — can join, employer need not contribute), EXCLUDED (not subject to AE). Null if not yet enrolled entry_route: anyOf: - $ref: '#/components/schemas/PensionEntryRoute' - type: 'null' description: >- How the employee entered the scheme: AUTO_ENROLLED (system enrolled automatically at payroll approval), OPTED_IN (employee requested enrolment), JOINED (entitled worker chose to join). Null if not enrolled enrolment_date: anyOf: - type: string format: date - type: 'null' title: Enrolment Date description: Date on which the membership became ACTIVE; null if not yet enrolled opt_out_date: anyOf: - type: string format: date - type: 'null' title: Opt Out Date description: Date the employee opted out; null if not opted out enrolment_communication_date: anyOf: - type: string format: date - type: 'null' title: Enrolment Communication Date description: >- Date the statutory enrolment letter was issued to the employee; used to validate the 1-month opt-out window scheme_id: anyOf: - type: string - type: 'null' title: Scheme Id description: >- UUID of the pension scheme the employee is enrolled in; null for legacy memberships created before multi-scheme support (engine falls back to the org's default scheme) created_at: type: string format: date-time title: Created At description: Timestamp when this version of the membership record was created created_by: anyOf: - type: string - type: 'null' title: Created By description: >- User identifier who created this version; null if created by the system (e.g. auto-enrolment) additionalProperties: true type: object required: - valid_from - status - version - worker_category - entry_route - enrolment_date - opt_out_date - enrolment_communication_date - scheme_id - created_at - created_by title: PensionMembershipResponse description: >- Current pension membership state for an employee. Reflects the latest (highest version) membership history record. Per-employee rate override fields (employee_rate, employer_rate, etc.) are null when the scheme defaults apply; non-null values take precedence over the scheme. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError PensionEntryRoute: type: string enum: - AUTO_ENROLLED - OPTED_IN - JOINED title: PensionEntryRoute WorkerCategory: type: string enum: - ELIGIBLE_JOBHOLDER - NON_ELIGIBLE_JOBHOLDER - ENTITLED_WORKER - EXCLUDED title: WorkerCategory PensionTaxTreatment: type: string enum: - NET_PAY - RELIEF_AT_SOURCE - SALARY_SACRIFICE title: PensionTaxTreatment PensionMembershipStatus: type: string enum: - ACTIVE - OPTED_OUT - NOT_ENROLLED title: PensionMembershipStatus ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: BearerToken: type: oauth2 flows: password: scopes: read:all: Read all write:all: Write all read:health_check: Read health check write:health_check: Write health check read:wage_types: Read wage types write:wage_types: Write wage types tokenUrl: >- https://auth-preview.intermezzo.ai/authorize?audience=api-preview.intermezzo.ai ````