Create pension scheme
Create a new workplace pension scheme for an organization. Multiple schemes per organization are supported. The first scheme created is automatically set as the default.
Authorizations
Get token from Auth0 and paste it here
Path Parameters
Body
Configure an organization's pension scheme.
Date from which this scheme configuration is effective
Display name for the scheme
Pension provider
NEST, OTHER Tax treatment method (NET_PAY, RELIEF_AT_SOURCE, SALARY_SACRIFICE)
NET_PAY, RELIEF_AT_SOURCE, SALARY_SACRIFICE Which earnings count as pensionable
QUALIFYING_EARNINGS, PENSIONABLE_PAY Employee contribution rate (minimum 0.05 = 5%)
0.05 <= x <= 1Employer contribution rate (minimum 0.03 = 3%)
0.03 <= x <= 1Wage type code used for pension deduction line items on payslip
Maximum employee contribution per period (absolute amount)
Maximum employer contribution per period (absolute amount)
Months to postpone auto-enrolment for new eligible jobholders (0 = none)
0 <= x <= 3Whether employer voluntarily contributes for Entitled Workers who join
Employer's chosen cyclical re-enrolment date (every ~3 years)
Earliest permissible re-enrolment date (3 months before anniversary)
Latest permissible re-enrolment date (3 months after anniversary)
Response
Successful Response
Organisation's pension scheme configuration.
scheme_id is the stable handle identifier — use it in {scheme_id} path segments
and in membership scheme_id fields. valid_from/valid_to describe the validity
window of this particular configuration version.
Date from which this configuration version is effective
Stable handle UUID for the scheme; does not change when configuration is updated via PATCH. Use this in URL path segments and membership scheme_id fields
Whether this is the organisation's default scheme; only one scheme per org can be default. New eligible employees are auto-enrolled into the default scheme
Display name for the scheme
Pension provider (NEST = National Employment Savings Trust, OTHER = any other provider)
NEST, OTHER Tax treatment method: NET_PAY (deducted pre-tax), RELIEF_AT_SOURCE (deducted post-tax, provider claims tax relief from HMRC), SALARY_SACRIFICE (employee gives up salary; saves NIC for both parties)
NET_PAY, RELIEF_AT_SOURCE, SALARY_SACRIFICE Earnings base for contribution calculation: QUALIFYING_EARNINGS (band £6,240–£50,270/year, 2025-26), PENSIONABLE_PAY (full pay, no lower threshold)
QUALIFYING_EARNINGS, PENSIONABLE_PAY Employee contribution rate as a decimal (e.g. 0.05 = 5%); statutory minimum is 5% on qualifying earnings
^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$Employer contribution rate as a decimal (e.g. 0.03 = 3%); statutory minimum is 3% on qualifying earnings
^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$Maximum employee contribution per pay period as an absolute amount; null = no cap
^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$Maximum employer contribution per pay period as an absolute amount; null = no cap
^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$Months to postpone auto-enrolment for newly eligible jobholders (0 = enrol immediately, max 3)
Whether the employer voluntarily contributes for Entitled Workers (earnings below £6,240/year) who choose to join the scheme
Employer's chosen cyclical re-enrolment date (every ~3 years); opted-out employees are re-enrolled on this date
Earliest permissible re-enrolment date (3 months before the staging anniversary)
Latest permissible re-enrolment date (3 months after the staging anniversary)
Wage type code used for the pension deduction line item on payslip; must be PENSION category. NET_PAY/RAS use UK-P-001 or UK-P-002; SALARY_SACRIFICE requires UK-P-003
Timestamp when this configuration version was created
Date on which this version expires (exclusive); null means this is the current active version. Populated automatically when a newer version is created via PATCH
User identifier (from JWT sub) who created this version; null if created by the system