Skip to main content
PATCH
Update per-employee pension rates

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 update per-employee pension contribution rates.

Creates a new membership history version effective from valid_from. Standard PATCH semantics:

  • Field omitted from the request body → carry forward the current value unchanged.
  • Field explicitly set to null → clear the override (fall back to scheme default).
  • Field set to a value → apply as the new override.
valid_from
string<date>
required

Effective date of the rate change

employee_rate

Employee contribution rate override

Required range: 0 <= x <= 1
employer_rate

Employer contribution rate override

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

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

Wage type code; 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