The Postponement API from Smart Pension — 3 operation(s) for postponement.
openapi: 3.2.0
info:
title: Keystone Postponement API
version: v12
description: This is the endpoint description of Keystone API.
servers:
- url: https://api.sandbox.autoenrolment.co.uk
- url: /
tags:
- name: Postponement
paths:
/companies/{company_id}/employees/{employee_id}/postponements:
post:
summary: Postponement/Create
tags:
- Postponement
security:
- oAuth2:
- user
- customer
parameters:
- name: company_id
in: path
required: true
example: 807
schema:
type: string
- name: employee_id
in: path
required: true
example: 422
schema:
type: string
requestBody:
content:
application/json:
examples:
success:
value:
deferral_on: '2026-08-06'
invalid_parameters:
value:
deferral_on: ''
schema:
type: object
properties:
include:
type: array
items:
enum:
- employee
responses:
'201':
description: Creates a postponement
content:
application/json:
example:
id: 3
employee_id: 422
starts_on: '2026-08-05'
ends_on: '2026-08-05'
created_at: '2026-08-05T13:01:46.000+01:00'
updated_at: '2026-08-05T13:01:46.000+01:00'
deferral_on: '2026-08-06'
cancelled_at: null
links:
- rel: employee
title: employee
href: https://api.host.com/companies/807/employees/422
schema:
$ref: '#/components/schemas/response_postponement'
'422':
description: Invalid parameters
content:
application/json:
example:
errors:
- code: 1401
title: The deferral date is a required field.
detail: You need to select a deferral date for the postponement. This can be any date up to 3 months and a day later than either your staging date or the employees start of employment, which ever is the latest.
meta: {}
source:
pointer: /data/attributes/deferral_on
get:
summary: Postponement/List
tags:
- Postponement
security:
- oAuth2:
- user
- customer
parameters:
- name: company_id
in: path
required: true
example: 819
schema:
type: string
- name: employee_id
in: path
required: true
example: 429
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
example:
limit: 50
offset: 0
total: 0
links:
- rel: self
title: self
href: http://api.host.com/companies/819/employees/429/postponements
- rel: first
title: first
href: http://api.host.com/companies/819/employees/429/postponements?offset=0&limit=50
- rel: last
title: last
href: http://api.host.com/companies/819/employees/429/postponements?offset=0&limit=50
postponements: []
schema:
type: object
properties:
limit:
type:
- integer
- 'null'
offset:
type:
- integer
- 'null'
total:
type:
- integer
- 'null'
links:
type: array
items:
$ref: '#/components/schemas/link'
postponements:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/response_postponement'
/companies/{company_id}/employees/{employee_id}/postponements/{id}:
delete:
summary: Postponement/Destroy
tags:
- Postponement
security:
- oAuth2:
- user
- customer
parameters:
- name: id
in: path
required: true
example: 4
schema:
type: string
- name: company_id
in: path
required: true
example: 809
schema:
type: string
- name: employee_id
in: path
required: true
example: 424
schema:
type: string
responses:
'204':
description: Success
'403':
description: Forbidden when the employee already has a contribution
'404':
description: Not Found
get:
summary: Postponement/Get
tags:
- Postponement
security:
- oAuth2:
- user
- customer
parameters:
- name: id
in: path
required: true
example: 7
schema:
type: string
- name: company_id
in: path
required: true
example: 815
schema:
type: string
- name: employee_id
in: path
required: true
example: 427
schema:
type: string
- name: include[]
in: query
schema:
type: array
items:
enum:
- employee
required: false
responses:
'200':
description: Success
content:
application/json:
example:
id: 7
employee_id: 427
starts_on: '2026-08-05'
ends_on: '2026-08-05'
created_at: '2026-08-05T13:01:48.000+01:00'
updated_at: '2026-08-05T13:01:48.000+01:00'
deferral_on: '2026-08-06'
cancelled_at: null
links:
- rel: employee
title: employee
href: https://api.host.com/companies/815/employees/427
schema:
$ref: '#/components/schemas/response_postponement'
'404':
description: Not Found
put:
summary: Postponement/Update
tags:
- Postponement
security:
- oAuth2:
- user
- customer
parameters:
- name: id
in: path
required: true
example: 9
schema:
type: string
- name: company_id
in: path
required: true
example: 820
schema:
type: string
- name: employee_id
in: path
required: true
example: 430
schema:
type: string
requestBody:
content:
application/json:
examples:
success:
value:
starts_on: '2026-08-05'
deferral_on: '2026-08-06'
postponement:
deferral_on: '2026-08-06'
employee:
id: 430
api_key: api_key
authentication_token: null
authentication_token_generated_at: null
automatically_enrolled: false
bank_account_detail_id: null
benefit_group_id: null
city: Oakdale
civil_status: null
company_id: 820
company_match: false
confirmation_token: null
contribute_if_entitled: true
country_code: GB
created_at: '2026-08-05T13:01:49.000+01:00'
customer_id: null
date_of_birth: '2001-08-05'
date_of_birth_confirmed: false
email: employee_518@example.com
employee_classification: null
employment_type: null
encrypted_password: null
ends_on: null
exit_reason: null
external_id: null
external_oidc_id: null
forename: Alice
gauth_enabled: false
gauth_secret: null
gauth_tmp: null
gender: Male
group_id: null
identity_person_id: null
kind_id: null
kind_type: Employee
last_sign_in_at: null
line1: 7101 Dapin Place
line2: null
line3: null
member_type: null
middle_name: null
national_identifier_1: null
national_insurance_number: null
nationality_code: null
onboarded_at: null
online_login_disabled: false
opt_in_on: null
opt_out_on: null
opt_out_window_ends_on: null
opt_out_window_starts_on: null
opt_state: ignition
percentage_ownership: null
person_id: null
postcode: '65551'
referral_clicks: 0
region: null
remember_created_at: null
reset_password_sent_at: null
reset_password_token: null
retirement_age: 65
retirement_age_customised: false
retirement_date: '2066-08-05'
scheme_detail_id: 547
scheme_origin: standard
secondary_email: null
single_use_authentication_token: null
single_use_authentication_token_generated_at: null
slug: TO7niFvglK
starts_on: '2016-08-05'
surname: Scott
target_retirement_age: null
target_retirement_date: null
telephone: null
temporary_password: temporary_password
title: Captain
updated_at: '2026-08-05T13:01:49.000+01:00'
uuid: 3e08399f-b817-4918-b8fc-fb10803f8b1c
visa_number: null
works_in_uk: true
invalid_parameters:
value:
starts_on: '2026-08-05'
deferral_on: '2026-08-06'
postponement:
deferral_on: ''
employee:
id: 431
api_key: api_key
authentication_token: null
authentication_token_generated_at: null
automatically_enrolled: false
bank_account_detail_id: null
benefit_group_id: null
city: Merced
civil_status: null
company_id: 822
company_match: false
confirmation_token: null
contribute_if_entitled: true
country_code: GB
created_at: '2026-08-05T13:01:50.000+01:00'
customer_id: null
date_of_birth: '2001-08-05'
date_of_birth_confirmed: false
email: employee_519@example.com
employee_classification: null
employment_type: null
encrypted_password: null
ends_on: null
exit_reason: null
external_id: null
external_oidc_id: null
forename: Judy
gauth_enabled: false
gauth_secret: null
gauth_tmp: null
gender: Male
group_id: null
identity_person_id: null
kind_id: null
kind_type: Employee
last_sign_in_at: null
line1: 93762 Crownhardt Lane
line2: null
line3: null
member_type: null
middle_name: null
national_identifier_1: null
national_insurance_number: null
nationality_code: null
onboarded_at: null
online_login_disabled: false
opt_in_on: null
opt_out_on: null
opt_out_window_ends_on: null
opt_out_window_starts_on: null
opt_state: ignition
percentage_ownership: null
person_id: null
postcode: 33159-7551
referral_clicks: 0
region: null
remember_created_at: null
reset_password_sent_at: null
reset_password_token: null
retirement_age: 65
retirement_age_customised: false
retirement_date: '2066-08-05'
scheme_detail_id: 549
scheme_origin: standard
secondary_email: null
single_use_authentication_token: null
single_use_authentication_token_generated_at: null
slug: sG0eSFEUZA
starts_on: '2016-08-05'
surname: Hicks
target_retirement_age: null
target_retirement_date: null
telephone: null
temporary_password: temporary_password
title: Mx
updated_at: '2026-08-05T13:01:50.000+01:00'
uuid: 77837459-0bb2-470d-b23c-a7d366a11129
visa_number: null
works_in_uk: true
forbidden_with_existing_contribution:
value:
starts_on: '2026-08-05'
deferral_on: '2026-08-06'
postponement:
deferral_on: '2026-08-06'
employee:
id: 432
api_key: api_key
authentication_token: null
authentication_token_generated_at: null
automatically_enrolled: false
bank_account_detail_id: null
benefit_group_id: null
city: Sonoma
civil_status: null
company_id: 824
company_match: false
confirmation_token: null
contribute_if_entitled: true
country_code: GB
created_at: '2026-08-05T13:01:50.000+01:00'
customer_id: null
date_of_birth: '2001-08-05'
date_of_birth_confirmed: false
email: employee_520@example.com
employee_classification: null
employment_type: null
encrypted_password: null
ends_on: null
exit_reason: null
external_id: null
external_oidc_id: null
forename: Anne
gauth_enabled: false
gauth_secret: null
gauth_tmp: null
gender: Male
group_id: null
identity_person_id: null
kind_id: null
kind_type: Employee
last_sign_in_at: null
line1: 115 Arkansas Plaza
line2: null
line3: null
member_type: null
middle_name: null
national_identifier_1: null
national_insurance_number: null
nationality_code: null
onboarded_at: null
online_login_disabled: false
opt_in_on: null
opt_out_on: null
opt_out_window_ends_on: null
opt_out_window_starts_on: null
opt_state: ignition
percentage_ownership: null
person_id: null
postcode: '64624'
referral_clicks: 0
region: null
remember_created_at: null
reset_password_sent_at: null
reset_password_token: null
retirement_age: 65
retirement_age_customised: false
retirement_date: '2066-08-05'
scheme_detail_id: 551
scheme_origin: standard
secondary_email: null
single_use_authentication_token: null
single_use_authentication_token_generated_at: null
slug: wkHS40WRo
starts_on: '2016-08-05'
surname: Simmons
target_retirement_age: null
target_retirement_date: null
telephone: null
temporary_password: temporary_password
title: Sir
updated_at: '2026-08-05T13:01:50.000+01:00'
uuid: 60df9ab2-5913-413f-93f5-2b8f493bc396
visa_number: null
works_in_uk: true
not_found:
value:
starts_on: '2026-08-05'
deferral_on: '2026-08-06'
postponement:
deferral_on: '2026-08-06'
employee:
id: 433
api_key: api_key
authentication_token: null
authentication_token_generated_at: null
automatically_enrolled: false
bank_account_detail_id: null
benefit_group_id: null
city: Bell Gardens
civil_status: null
company_id: 826
company_match: false
confirmation_token: null
contribute_if_entitled: true
country_code: GB
created_at: '2026-08-05T13:01:51.000+01:00'
customer_id: null
date_of_birth: '2001-08-05'
date_of_birth_confirmed: false
email: employee_521@example.com
employee_classification: null
employment_type: null
encrypted_password: null
ends_on: null
exit_reason: null
external_id: null
external_oidc_id: null
forename: Kathy
gauth_enabled: false
gauth_secret: null
gauth_tmp: null
gender: Female
group_id: null
identity_person_id: null
kind_id: null
kind_type: Employee
last_sign_in_at: null
line1: 07319 Buhler Street
line2: null
line3: null
member_type: null
middle_name: null
national_identifier_1: null
national_insurance_number: null
nationality_code: null
onboarded_at: null
online_login_disabled: false
opt_in_on: null
opt_out_on: null
opt_out_window_ends_on: null
opt_out_window_starts_on: null
opt_state: ignition
percentage_ownership: null
person_id: null
postcode: '57118'
referral_clicks: 0
region: null
remember_created_at: null
reset_password_sent_at: null
reset_password_token: null
retirement_age: 65
retirement_age_customised: false
retirement_date: '2066-08-05'
scheme_detail_id: 553
scheme_origin: standard
secondary_email: null
single_use_authentication_token: null
single_use_authentication_token_generated_at: null
slug: IJwxQ83rY1lD
starts_on: '2016-08-05'
surname: Johnston
target_retirement_age: null
target_retirement_date: null
telephone: null
temporary_password: temporary_password
title: Dr
updated_at: '2026-08-05T13:01:51.000+01:00'
uuid: 303cfa8f-8ae9-4b70-a134-2ad92834a7c5
visa_number: null
works_in_uk: true
schema:
type: object
properties:
deferral_on:
type: string
starts_on:
type: string
required:
- starts_on
- deferral_on
responses:
'204':
description: Updates a contribution with gross qualifying earnings
'403':
description: Forbidden when the employee already has a contribution
content:
application/json:
example:
errors:
- code: 28
title: Employee has contributions.
detail: Postponement cannot be deleted or updated because there are contribution records for this employee.
form: null
attribute: base
error: postponement_is_frozen
meta: {}
source:
pointer: /base
'404':
description: Not Found
content:
application/json:
example: ''
'422':
description: Failing with invalid parameters.
content:
application/json:
example:
errors:
- code: 1401
title: The deferral date is a required field.
detail: You need to select a deferral date for the postponement. This can be any date up to 3 months and a day later than either your staging date or the employees start of employment, which ever is the latest.
meta: {}
source:
pointer: /data/attributes/deferral_on
patch:
summary: Postponement/Update
tags:
- Postponement
security:
- oAuth2:
- user
- customer
parameters:
- name: id
in: path
required: true
example: 13
schema:
type: string
- name: company_id
in: path
required: true
example: 828
schema:
type: string
- name: employee_id
in: path
required: true
example: 434
schema:
type: string
requestBody:
content:
application/json:
examples:
success:
value:
starts_on: '2026-08-05'
deferral_on: '2026-08-06'
postponement:
deferral_on: '2026-08-06'
employee:
id: 434
api_key: api_key
authentication_token: null
authentication_token_generated_at: null
automatically_enrolled: false
bank_account_detail_id: null
benefit_group_id: null
city: Aliso Viejo
civil_status: null
company_id: 828
company_match: false
confirmation_token: null
contribute_if_entitled: true
country_code: GB
created_at: '2026-08-05T13:01:51.000+01:00'
customer_id: null
date_of_birth: '2001-08-05'
date_of_birth_confirmed: false
email: employee_522@example.com
employee_classification: null
employment_type: null
encrypted_password: null
ends_on: null
exit_reason: null
external_id: null
external_oidc_id: null
forename: Eric
gauth_enabled: false
gauth_secret: null
gauth_tmp: null
gender: Female
group_id: null
identity_person_id: null
kind_id: null
kind_type: Employee
last_sign_in_at: null
line1: 137 Fair Oaks Road
line2: null
line3: null
member_type: null
middle_name: null
national_identifier_1: null
national_insurance_number: null
nationality_code: null
onboarded_at: null
online_login_disabled: false
opt_in_on: null
opt_out_on: null
opt_out_window_ends_on: null
opt_out_window_starts_on: null
opt_state: ignition
percentage_ownership: null
person_id: null
postcode: 17418-2688
referral_clicks: 0
region: null
remember_created_at: null
reset_password_sent_at: null
reset_password_token: null
retirement_age: 65
retirement_age_customised: false
retirement_date: '2066-08-05'
scheme_detail_id: 555
scheme_origin: standard
secondary_email: null
single_use_authentication_token: null
single_use_authentication_token_generated_at: null
slug: KJQAzf8a0D
starts_on: '2016-08-05'
surname: Garcia
target_retirement_age: null
target_retirement_date: null
telephone: null
temporary_password: temporary_password
title: Bursar
updated_at: '2026-08-05T13:01:51.000+01:00'
uuid: 2b9ace5a-ef83-41dd-8f7c-ee21720a0b73
visa_number: null
works_in_uk: true
invalid_parameters:
value:
starts_on: '2026-08-05'
deferral_on: '2026-08-06'
postponement:
deferral_on: ''
employee:
id: 435
api_key: api_key
authentication_token: null
authentication_token_generated_at: null
automatically_enrolled: false
bank_account_detail_id: null
benefit_group_id: null
city: Highland
civil_status: null
company_id: 830
company_match: false
confirmation_token: null
contribute_if_entitled: true
country_code: GB
created_at: '2026-08-05T13:01:51.000+01:00'
customer_id: null
date_of_birth: '2001-08-05'
date_of_birth_confirmed: false
email: employee_523@example.com
employee_classification: null
employment_type: null
encrypted_password: null
ends_on: null
exit_reason: null
external_id: null
external_oidc_id: null
forename: Sara
gauth_enabled: false
gauth_secret: null
gauth_tmp: null
gender: Female
group_id: null
identity_person_id: null
kind_id: null
kind_type: Employee
last_sign_in_at: null
line1: 39 Northland Street
line2: null
line3: null
member_type: null
middle_name: null
national_identifier_1: null
national_insurance_number: null
nationality_code: null
onboarded_at: null
online_login_disabled: false
opt_in_on: null
opt_out_on: null
opt_out_window_ends_on: null
opt_out_window_starts_on: null
opt_state: ignition
percentage_ownership: null
person_id: null
postcode: 08515
referral_clicks: 0
region: null
remember_created_at: null
reset_password_sent_at: null
reset_password_token: null
retirement_age: 65
retirement_age_customised: false
retirement_date: '2066-08-05'
scheme_detail_id: 557
scheme_origin: standard
secondary_email: null
single_use_authentication_token: null
single_use_authentication_token_generated_at: null
slug: L2cq74McU
starts_on: '2016-08-05'
surname: Larson
target_retirement_age: null
target_retirement_date: null
telephone: null
temporary_password: temporary_password
title: Sir
updated_at: '2026-08-05T13:01:51.000+01:00'
uuid: 8a54af82-412c-4050-957d-badf75c87ec6
visa_number: null
works_in_uk: true
forbidden_with_existing_contribution:
value:
starts_on: '2026-08-05'
deferral_on: '2026-08-06'
postponement:
deferral_on: '2026-08-06'
employee:
id: 436
api_key: api_key
authentication_token: null
authentication_token_generated_at: null
automatically_enrolled: false
bank_account_detail_id: null
benefit_group_id: null
city: Fountain Valley
civil_status: null
company_id: 832
company_match: false
confirmation_token: null
contribute_if_entitled: true
country_code: GB
created_at: '2026-08-05T13:01:52.000+01:00'
customer_id: null
date_of_birth: '2001-08-05'
date_of_birth_confirmed: false
email: employee_524@example.com
# --- truncated at 32 KB (119 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/smart-pension/refs/heads/main/openapi/smart-pension-postponement-api-openapi.yml