The Enrolment API from Smart Pension — 2 operation(s) for enrolment.
openapi: 3.2.0
info:
title: Keystone Enrolment API
version: v12
description: This is the endpoint description of Keystone API.
servers:
- url: https://api.sandbox.autoenrolment.co.uk
- url: /
tags:
- name: Enrolment
paths:
/companies/{company_id}/enrolments:
post:
summary: Companies/Enrolments/Create
tags:
- Enrolment
security:
- oAuth2:
- user
- customer
parameters:
- name: company_id
in: path
required: true
example: 1006
schema:
type: string
requestBody:
content:
application/json:
examples:
success:
value:
event_on: '2026-08-05'
company:
id: 1006
approved_payer_reference: null
created_at: '2026-08-05T13:02:44.000+01:00'
default_percentage: '3.0'
direct_debit_optional: false
economic_zone_id: null
electronic_data_feed: false
employee_can_change_contribution: true
external_id: null
external_oidc_provider_configuration_id: null
incorporated_on: null
kind_id: null
kind_type: Company
layout_configuration_id: null
legal_structure: Limited Company
name: nibh in 1394
national_insurance_saving_share: null
only_employer_manages_membership: false
only_employer_manages_personal_details: false
payment_method: null
pension_regulator_letter_code: null
pensionable_earning_type: unbanded
prior_reference: null
provider_scheme_migration_id: null
reg_address1: null
reg_address2: null
reg_address3: null
reg_address4: null
reg_address_country_code: null
reg_address_gone_away: false
reg_address_postcode: null
registration_number: '1'
rewards_section_enabled: true
scheme_origin: standard
scheme_origin_provider_id: null
scheme_origin_provider_name: null
self_certification_started_at: null
service_starts_on: null
skip_contribution_validations: false
slug: sociis-1065
state: active
state_effective_on: null
state_of_incorporation: null
tax_office_employer_reference: null
tax_office_number: null
tax_year_end_day: null
tax_year_end_month: null
taxed_as: null
telephone: null
trading_address1: null
trading_address2: null
trading_address3: null
trading_address4: null
trading_address_country_code: null
trading_address_gone_away: false
trading_address_postcode: null
updated_at: '2026-08-05T13:02:44.000+01:00'
uuid: 146d8d01-a949-4e95-b959-70a827a2b5d7
welcome_letters_reminder_sent_at: null
missing_start_on:
value:
event_on: '2026-08-05'
company:
id: 1007
approved_payer_reference: null
created_at: '2026-08-05T13:02:44.000+01:00'
default_percentage: '3.0'
direct_debit_optional: false
economic_zone_id: null
electronic_data_feed: false
employee_can_change_contribution: true
external_id: null
external_oidc_provider_configuration_id: null
incorporated_on: null
kind_id: null
kind_type: Company
layout_configuration_id: null
legal_structure: Limited Company
name: et ultrices 1396
national_insurance_saving_share: null
only_employer_manages_membership: false
only_employer_manages_personal_details: false
payment_method: null
pension_regulator_letter_code: null
pensionable_earning_type: unbanded
prior_reference: null
provider_scheme_migration_id: null
reg_address1: null
reg_address2: null
reg_address3: null
reg_address4: null
reg_address_country_code: null
reg_address_gone_away: false
reg_address_postcode: null
registration_number: '1'
rewards_section_enabled: true
scheme_origin: standard
scheme_origin_provider_id: null
scheme_origin_provider_name: null
self_certification_started_at: null
service_starts_on: null
skip_contribution_validations: false
slug: id-1066
state: active
state_effective_on: null
state_of_incorporation: null
tax_office_employer_reference: null
tax_office_number: null
tax_year_end_day: null
tax_year_end_month: null
taxed_as: null
telephone: null
trading_address1: null
trading_address2: null
trading_address3: null
trading_address4: null
trading_address_country_code: null
trading_address_gone_away: false
trading_address_postcode: null
updated_at: '2026-08-05T13:02:44.000+01:00'
uuid: d47e5bf7-18bb-4c0d-b063-d63587e3e96a
welcome_letters_reminder_sent_at: null
locked_enrolment:
value:
event_on: '2026-08-05'
company:
id: 1008
approved_payer_reference: null
created_at: '2026-08-05T13:02:45.000+01:00'
default_percentage: '3.0'
direct_debit_optional: false
economic_zone_id: null
electronic_data_feed: false
employee_can_change_contribution: true
external_id: null
external_oidc_provider_configuration_id: null
incorporated_on: null
kind_id: null
kind_type: Company
layout_configuration_id: null
legal_structure: Limited Company
name: maecenas pulvinar 1398
national_insurance_saving_share: null
only_employer_manages_membership: false
only_employer_manages_personal_details: false
payment_method: null
pension_regulator_letter_code: null
pensionable_earning_type: unbanded
prior_reference: null
provider_scheme_migration_id: null
reg_address1: null
reg_address2: null
reg_address3: null
reg_address4: null
reg_address_country_code: null
reg_address_gone_away: false
reg_address_postcode: null
registration_number: '1'
rewards_section_enabled: true
scheme_origin: standard
scheme_origin_provider_id: null
scheme_origin_provider_name: null
self_certification_started_at: null
service_starts_on: null
skip_contribution_validations: false
slug: in-1067
state: active
state_effective_on: null
state_of_incorporation: null
tax_office_employer_reference: null
tax_office_number: null
tax_year_end_day: null
tax_year_end_month: null
taxed_as: null
telephone: null
trading_address1: null
trading_address2: null
trading_address3: null
trading_address4: null
trading_address_country_code: null
trading_address_gone_away: false
trading_address_postcode: null
updated_at: '2026-08-05T13:02:45.000+01:00'
uuid: b507d957-72bb-49c8-9361-3d0d4fa72277
welcome_letters_reminder_sent_at: null
invalid_parameters:
value:
event_on: ''
schema:
type: object
properties:
event_on:
type: string
required:
- event_on
responses:
'201':
description: Success
content:
application/json:
example:
id: 33
company_id: 1006
event_on: '2026-08-05'
next_re_declaration_of_compliance_deadline_on: '2030-01-04'
next_re_enrolment_window_starts_on: '2029-05-05'
next_re_enrolment_window_ends_on: '2029-11-04'
created_at: '2026-08-05T13:02:44.000+01:00'
updated_at: '2026-08-05T13:02:44.000+01:00'
links:
- rel: company
title: company
href: https://api.host.com/companies/1006
schema:
$ref: '#/components/schemas/response_enrolment'
'403':
description: Forbidden when enrolment is locked
content:
application/json:
examples:
missing_start_on:
value:
errors:
- code: 11
title: Scheme start date is missing.
detail: Please set your company scheme start date. Without the scheme start date you can not perform this action.
form: null
attribute: base
error: scheme_starts_on_blank
meta: {}
source:
pointer: /base
locked_enrolment:
value:
errors:
- code: 45
title: The re-enrolment date cannot be created yet.
detail: The re-enrolment date cannot be created because it is too far in the future. You will be able to set it from 05 April, 2029
form: null
attribute: base
error: enrolment_locked
meta:
date: 05 April, 2029
source:
pointer: /base
'422':
description: Invalid parameters
content:
application/json:
example:
errors:
- code: 3201
title: Enrolment event on is a required field.
detail: Please include your re-enrolment date.
meta: {}
source:
pointer: /data/attributes/event_on
- code: 3202
title: Enrolment event date is out of range.
detail: Please choose your enrolment date from within a six-month window, which starts on 01 August, 2026 and ends on 31 January, 2027.
meta:
first_day: 01 August, 2026
last_day: 31 January, 2027
source:
pointer: /data/attributes/event_on
get:
summary: Companies/Enrolments/List
tags:
- Enrolment
security:
- oAuth2:
- user
- customer
parameters:
- name: company_id
in: path
required: true
example: 1025
schema:
type: string
- name: limit
in: query
schema:
type: integer
required: false
- name: offset
in: query
schema:
type: integer
required: false
- name: sort
in: query
schema:
type: string
required: false
- name: direction
in: query
schema:
type: string
enum:
- ASC
- DESC
required: false
- name: filter
in: query
schema:
type: object
properties:
event_on:
type: array
items:
type: string
required: false
style: deepObject
- name: operator
in: query
schema:
type: string
enum:
- or
- and
required: false
responses:
'200':
description: Success
content:
application/json:
example:
limit: 50
offset: 0
total: 1
links:
- rel: self
title: self
href: http://api.host.com/companies/1025/enrolments
- rel: first
title: first
href: http://api.host.com/companies/1025/enrolments?offset=0&limit=50
- rel: last
title: last
href: http://api.host.com/companies/1025/enrolments?offset=0&limit=50
enrolments:
- id: 47
company_id: 1025
event_on: '2023-10-01'
next_re_declaration_of_compliance_deadline_on: '2027-02-28'
next_re_enrolment_window_starts_on: '2026-07-01'
next_re_enrolment_window_ends_on: '2026-12-31'
created_at: '2026-08-05T13:02:49.000+01:00'
updated_at: '2026-08-05T13:02:49.000+01:00'
links:
- rel: company
title: company
href: https://api.host.com/companies/1025
schema:
type: object
properties:
limit:
type:
- integer
- 'null'
offset:
type:
- integer
- 'null'
total:
type:
- integer
- 'null'
links:
type: array
items:
$ref: '#/components/schemas/link'
enrolments:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/response_enrolment'
/companies/{company_id}/enrolments/{id}:
delete:
summary: Companies/Enrolments/Destroy
tags:
- Enrolment
security:
- oAuth2:
- user
- customer
parameters:
- name: id
in: path
required: true
example: 38
schema:
type: string
- name: company_id
in: path
required: true
example: 1010
schema:
type: string
responses:
'204':
description: Success
'403':
description: Forbidden when an employee is already re-enrolled
get:
summary: Companies/Enrolments/Get
tags:
- Enrolment
security:
- oAuth2:
- user
- customer
parameters:
- name: id
in: path
required: true
example: 45
schema:
type: string
- name: company_id
in: path
required: true
example: 1023
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
example:
id: 45
company_id: 1023
event_on: '2026-08-05'
next_re_declaration_of_compliance_deadline_on: '2030-01-04'
next_re_enrolment_window_starts_on: '2029-05-05'
next_re_enrolment_window_ends_on: '2029-11-04'
created_at: '2026-08-05T13:02:48.000+01:00'
updated_at: '2026-08-05T13:02:48.000+01:00'
links:
- rel: company
title: company
href: https://api.host.com/companies/1023
schema:
$ref: '#/components/schemas/response_enrolment'
'404':
description: Not Found
put:
summary: Companies/Enrolments/Update
tags:
- Enrolment
security:
- oAuth2:
- user
- customer
parameters:
- name: id
in: path
required: true
example: 49
schema:
type: string
- name: company_id
in: path
required: true
example: 1026
schema:
type: string
requestBody:
content:
application/json:
examples:
success:
value:
event_on: '2023-11-01'
company:
id: 1026
approved_payer_reference: null
created_at: '2026-08-05T13:02:49.000+01:00'
default_percentage: '3.0'
direct_debit_optional: false
economic_zone_id: null
electronic_data_feed: false
employee_can_change_contribution: true
external_id: null
external_oidc_provider_configuration_id: null
incorporated_on: null
kind_id: null
kind_type: Company
layout_configuration_id: null
legal_structure: Limited Company
name: eget semper 1425
national_insurance_saving_share: null
only_employer_manages_membership: false
only_employer_manages_personal_details: false
payment_method: null
pension_regulator_letter_code: null
pensionable_earning_type: unbanded
prior_reference: null
provider_scheme_migration_id: null
reg_address1: null
reg_address2: null
reg_address3: null
reg_address4: null
reg_address_country_code: null
reg_address_gone_away: false
reg_address_postcode: null
registration_number: '1'
rewards_section_enabled: true
scheme_origin: standard
scheme_origin_provider_id: null
scheme_origin_provider_name: null
self_certification_started_at: null
service_starts_on: null
skip_contribution_validations: false
slug: id-1084
state: active
state_effective_on: null
state_of_incorporation: null
tax_office_employer_reference: null
tax_office_number: null
tax_year_end_day: null
tax_year_end_month: null
taxed_as: null
telephone: null
trading_address1: null
trading_address2: null
trading_address3: null
trading_address4: null
trading_address_country_code: null
trading_address_gone_away: false
trading_address_postcode: null
updated_at: '2026-08-05T13:02:49.000+01:00'
uuid: f783deef-6091-4c97-98bd-66e2f35cb05f
welcome_letters_reminder_sent_at: null
enrolment:
id: 49
company_id: 1026
created_at: '2026-08-05T13:02:50.000+01:00'
event_on: '2026-08-05'
updated_at: '2026-08-05T13:02:50.000+01:00'
enrolment_is_scheme_start_date:
value:
event_on: '2023-11-01'
company:
id: 1027
approved_payer_reference: null
created_at: '2026-08-05T13:02:50.000+01:00'
default_percentage: '3.0'
direct_debit_optional: false
economic_zone_id: null
electronic_data_feed: false
employee_can_change_contribution: true
external_id: null
external_oidc_provider_configuration_id: null
incorporated_on: null
kind_id: null
kind_type: Company
layout_configuration_id: null
legal_structure: Limited Company
name: non interdum 1427
national_insurance_saving_share: null
only_employer_manages_membership: false
only_employer_manages_personal_details: false
payment_method: null
pension_regulator_letter_code: null
pensionable_earning_type: unbanded
prior_reference: null
provider_scheme_migration_id: null
reg_address1: null
reg_address2: null
reg_address3: null
reg_address4: null
reg_address_country_code: null
reg_address_gone_away: false
reg_address_postcode: null
registration_number: '1'
rewards_section_enabled: true
scheme_origin: standard
scheme_origin_provider_id: null
scheme_origin_provider_name: null
self_certification_started_at: null
service_starts_on: null
skip_contribution_validations: false
slug: neque-1085
state: active
state_effective_on: null
state_of_incorporation: null
tax_office_employer_reference: null
tax_office_number: null
tax_year_end_day: null
tax_year_end_month: null
taxed_as: null
telephone: null
trading_address1: null
trading_address2: null
trading_address3: null
trading_address4: null
trading_address_country_code: null
trading_address_gone_away: false
trading_address_postcode: null
updated_at: '2026-08-05T13:02:50.000+01:00'
uuid: 8a2f47da-6748-4f18-a33f-cfe852c9647b
welcome_letters_reminder_sent_at: null
enrolment:
id: 51
company_id: 1027
created_at: '2026-08-05T13:02:50.000+01:00'
event_on: '2026-08-05'
updated_at: '2026-08-05T13:02:50.000+01:00'
enrolment_not_latest_one:
value:
event_on: '2023-11-01'
company:
id: 1028
approved_payer_reference: null
created_at: '2026-08-05T13:02:50.000+01:00'
default_percentage: '3.0'
direct_debit_optional: false
economic_zone_id: null
electronic_data_feed: false
employee_can_change_contribution: true
external_id: null
external_oidc_provider_configuration_id: null
incorporated_on: null
kind_id: null
kind_type: Company
layout_configuration_id: null
legal_structure: Limited Company
name: maecenas rhoncus 1429
national_insurance_saving_share: null
only_employer_manages_membership: false
only_employer_manages_personal_details: false
payment_method: null
pension_regulator_letter_code: null
pensionable_earning_type: unbanded
prior_reference: null
provider_scheme_migration_id: null
reg_address1: null
reg_address2: null
reg_address3: null
reg_address4: null
reg_address_country_code: null
reg_address_gone_away: false
reg_address_postcode: null
registration_number: '1'
rewards_section_enabled: true
scheme_origin: standard
scheme_origin_provider_id: null
scheme_origin_provider_name: null
self_certification_started_at: null
service_starts_on: null
skip_contribution_validations: false
slug: ornare-1086
state: active
state_effective_on: null
state_of_incorporation: null
tax_office_employer_reference: null
tax_office_number: null
tax_year_end_day: null
tax_year_end_month: null
taxed_as: null
telephone: null
trading_address1: null
trading_address2: null
trading_address3: null
trading_address4: null
trading_address_country_code: null
trading_address_gone_away: false
trading_address_postcode: null
updated_at: '2026-08-05T13:02:50.000+01:00'
uuid: 61a26b53-d5fd-4c2a-b9fa-9ef5f9db4f94
welcome_letters_reminder_sent_at: null
enrolment:
id: 53
company_id: 1028
created_at: '2026-08-05T13:02:50.000+01:00'
event_on: '2026-08-05'
updated_at: '2026-08-05T13:02:50.000+01:00'
invalid_parameters:
value:
event_on: ''
employee_re_enrolled:
value:
event_on: '2023-11-01'
company:
id: 1030
approved_payer_reference: null
created_at: '2026-08-05T13:02:51.000+01:00'
default_percentage: '3.0'
direct_debit_optional: false
economic_zone_id: null
electronic_data_feed: false
employee_can_change_contribution: true
external_id: null
external_oidc_provider_configuration_id: null
incorporated_on: null
kind_id: null
kind_type: Company
layout_configuration_id: null
legal_structure: Limited Company
name: sit amet 1433
national_insurance_saving_share: null
only_employer_manages_membership: false
only_employer_manages_personal_details: false
payment_method: null
pension_regulator_letter_code: null
pensionable_earning_type: unbanded
prior_reference: null
provider_scheme_migration_id: null
reg_address1: null
reg_address2: null
reg_address3: null
reg_address4: null
reg_address_country_code: null
reg_address_gone_away: false
reg_address_postcode: null
registration_number: '1'
rewards_section_enabled: true
scheme_origin: standard
scheme_origin_provider_id: null
scheme_origin_provider_name: null
self_certification_started_at: null
service_starts_on: null
skip_contribution_validations: false
slug: justo-1088
state: active
state_effective_on: null
state_of_incorporation: null
tax_office_employer_reference: null
tax_office_number: null
tax_year_end_day: null
tax_year_end_month: null
taxed_as: null
telephone: null
trading_address1: null
trading_address2: null
trading_address3: null
trading_address4: null
trading_address_country_code: null
trading_address_gone_away: false
trading_address_postcode: null
updated_at: '2026-08-05T13:02:51.000+01:00'
uuid: 72d5a416-40a0-4e91-b183-3e0ff7c498f5
welcome_letters_reminder_sent_at: null
enrolment:
id: 58
company_id: 1030
created_at: '2026-08-05T13:02:51.000+01:00'
event_on: '2026-08-05'
updated_at: '2026-08-05T13:02:51.000+01:00'
schema:
type: object
properties:
event_on:
type: string
responses:
'204':
description: Success
'403':
description: Forbidden when an employee is already re-enrolled
content:
application/json:
examples:
enrolment_is_scheme_start_date:
value:
errors:
- code: 48
title: Enrolment cannot be updated/deleted.
detail: You can't update/delete your first enrolment event.
form: null
attribute: base
error: first_enrolment
meta: {}
source:
pointer: /base
enrolment_not_latest_one:
value:
errors:
- code: 47
title: Enrolment cannot be updated/deleted.
detail: The enrolment cannot be updated/deleted as enrolment history cannot contain missing records.
form: null
attribute: base
error: not_last_enrolment
meta: {}
source:
pointer: /base
employee_re_enrolled:
value:
errors:
- code: 46
title: This action cann
# --- truncated at 32 KB (115 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/smart-pension/refs/heads/main/openapi/smart-pension-enrolment-api-openapi.yml