Skip to main content
POST
Enrol employee in pension scheme

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

organization_id
required
employee_id
required

Body

application/json

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.

enrolment_date
string<date>
required

Date on which enrolment takes effect

entry_route
enum<string>
required

How the employee entered the scheme (AUTO_ENROLLED, OPTED_IN, JOINED)

Available options:
AUTO_ENROLLED,
OPTED_IN,
JOINED
worker_category
enum<string>
required

Worker category determined at the time of enrolment

Available options:
ELIGIBLE_JOBHOLDER,
NON_ELIGIBLE_JOBHOLDER,
ENTITLED_WORKER,
EXCLUDED
enrolment_communication_date
string<date> | null

Date the statutory enrolment communication was issued to the employee. Required to validate the statutory one-month opt-out window.

scheme_id

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

Employee contribution rate override (null = use scheme default)

Required range: 0 <= x <= 1
employer_rate

Employer contribution rate override (null = use scheme default)

Required range: 0 <= x <= 1
employee_cap

Per-period employee contribution cap override

Required range: x >= 0
employer_cap

Per-period employer contribution cap override

Required range: x >= 0
tax_treatment
enum<string> | null

Per-employee tax treatment override (e.g. RAS when scheme is salary sacrifice)

Available options:
NET_PAY,
RELIEF_AT_SOURCE,
SALARY_SACRIFICE
wage_type_code
string | null

Wage type code for pension deduction; MUST be provided when tax_treatment is set

Response

Successful Response

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.

valid_from
string<date>
required

Date from which this version of the membership record is effective

status
enum<string>
required

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)

Available options:
ACTIVE,
OPTED_OUT,
NOT_ENROLLED
version
integer
required

Sequential version number of this membership record; starts at 0, incremented on each change (status change, rate update, etc.)

worker_category
enum<string> | null
required

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

Available options:
ELIGIBLE_JOBHOLDER,
NON_ELIGIBLE_JOBHOLDER,
ENTITLED_WORKER,
EXCLUDED
entry_route
enum<string> | null
required

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

Available options:
AUTO_ENROLLED,
OPTED_IN,
JOINED
enrolment_date
string<date> | null
required

Date on which the membership became ACTIVE; null if not yet enrolled

opt_out_date
string<date> | null
required

Date the employee opted out; null if not opted out

enrolment_communication_date
string<date> | null
required

Date the statutory enrolment letter was issued to the employee; used to validate the 1-month opt-out window

scheme_id
string | null
required

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
string<date-time>
required

Timestamp when this version of the membership record was created

created_by
string | null
required

User identifier who created this version; null if created by the system (e.g. auto-enrolment)

valid_to
string<date> | null

Date on which this version expires (exclusive); null = current version. Set automatically when a new version is created

employee_rate
string | null

Per-employee employee contribution rate override; null = use scheme default

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
employer_rate
string | null

Per-employee employer contribution rate override; null = use scheme default

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
employee_cap
string | null

Per-employee maximum employee contribution per period; null = use scheme default

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
employer_cap
string | null

Per-employee maximum employer contribution per period; null = use scheme default

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
tax_treatment
enum<string> | null

Per-employee tax treatment override (e.g. RELIEF_AT_SOURCE for an employee whose scheme is SALARY_SACRIFICE); null = use scheme default

Available options:
NET_PAY,
RELIEF_AT_SOURCE,
SALARY_SACRIFICE
wage_type_code
string | null

Per-employee wage type code override for the payslip deduction line; null = use scheme default. Required when tax_treatment override is set