The Employee API from Smart Pension — 10 operation(s) for employee.
openapi: 3.2.0
info:
title: Keystone Employee API
version: v12
description: This is the endpoint description of Keystone API.
servers:
- url: https://api.sandbox.autoenrolment.co.uk
- url: /
tags:
- name: Employee
paths:
/companies/{company_id}/employees/{employee_id}/active_payroll_configuration:
get:
summary: ActivePayrollConfiguration/Get
tags:
- Employee
parameters:
- name: company_id
in: path
required: true
example: 240
schema:
type: string
- name: employee_id
in: path
required: true
example: 57
schema:
type: string
security:
- oAuth2:
- user
- customer
responses:
'200':
description: Success - when the employee has an active payroll configuration
content:
application/json:
example:
id: 1
company_id: 241
description: eget eleifend
frequency: weekly
name: morbi porttitor1
salary_rate: annual
created_at: '2026-08-05T12:59:05.000+01:00'
updated_at: '2026-08-05T12:59:05.000+01:00'
uuid: 1fb28d64-444d-48a0-8baf-8cf9c462c8ec
links:
- rel: company
title: company
href: https://api.host.com/companies/241
frequency_editable: false
destroyable: false
schema:
$ref: '#/components/schemas/response_payroll_configuration'
'404':
description: Not Found - when the employee does not have an active payroll configuration
content:
application/json:
example: ''
/companies/{company_id}/employees:
post:
summary: Employees/Create
tags:
- Employee
security:
- oAuth2:
- user
- customer
parameters:
- name: company_id
in: path
required: true
example: 564
schema:
type: string
requestBody:
content:
application/json:
examples:
valid_request:
value:
forename: forename
surname: surname
postcode: w6 4ra
gender: Male
date_of_birth: '1985-05-05'
starts_on: '2016-01-01'
payroll_name: payroll_name
invalid_parameter:
value:
forename: ''
surname: ''
postcode: ''
gender: ''
schema:
type: object
properties:
date_of_birth:
type: string
starts_on:
type: string
ends_on:
type: string
title:
type: string
enum:
- Mr
- Mrs
- Ms
- Miss
- Mx
- Dr
- Lord
- Lady
- Sir
- Prof
- Rev
- Captain
- Bursar
forename:
type: string
maximum: 100
x-ruby-regexp: (?-mix:\A[[:alpha:]\s`'\-.]*\z)
surname:
type: string
x-ruby-regexp: (?-mix:\A[[:alpha:]\s`'\-.]*\z)
maximum: 80
telephone:
type: string
external_id:
type: string
external_oidc_id:
type: string
email:
type: string
national_insurance_number:
type: string
exit_reason:
type: string
opt_state:
type: string
enum:
- ignition
- opted_in
- opted_out
- rejoined
- ceased_membership
event_date:
type: string
event_code:
type: string
gender:
type: string
enum:
- Male
- Female
percentage:
type: number
company_percentage:
type: number
company_match:
type: boolean
group_id:
type: integer
works_in_uk:
type: boolean
contribute_if_entitled:
type: boolean
customer_id:
type: integer
retirement_age:
type: integer
retirement_date:
type: string
scheme_origin:
type: string
enum:
- standard
- migrated
secondary_email:
type: string
middle_name:
type: string
maximum: 50
x-ruby-regexp: (?-mix:\A[[:alpha:]\s`'\-.]*\z)
civil_status:
type: string
enum:
- Single
- Married
- Civil Partnered
- Divorced
- Widowed
- Other
- Undeclared
effective_date:
type: string
employment_status:
type: string
part_time_percentage:
type: number
line1:
type: string
maximum: 140
line2:
type: string
minimum: 2
maximum: 180
city:
type: string
minimum: 2
maximum: 65
postcode:
type: string
minimum: 2
maximum: 255
employment_category:
type: string
contractual_enrolment:
type: boolean
target_retirement_age:
type: integer
line3:
type: string
employment_type:
type: string
enum:
- employed
- self_employed
- pensioner
- child_under_16
- caring_for_children
- caring_for_someone_over_16
- full_time_education
- unemployed
- other
tax_residency_status_name:
type: string
enum:
- scot
- welsh
- other_uk
- unavailable
country_code:
type: string
avc_percentage:
type: number
salary_sacrifice_signed:
type: boolean
annual_earnings1:
type: number
annual_earnings2:
type: number
region:
type: string
minimum: 2
maximum: 75
benefit_group_assigned_at:
type: string
opt_in_on:
type: string
minimum_percentage:
type: number
maximum_percentage:
type: number
minimum_company_percentage:
type: number
maximum_company_percentage:
type: number
minimum_roth_percentage:
type: number
maximum_roth_percentage:
type: number
required:
- forename
- surname
- gender
- date_of_birth
- starts_on
- postcode
responses:
'201':
description: Success
content:
application/json:
example:
updatable: true
id: 255
email: null
forename: forename
surname: surname
date_of_birth: '1985-05-05'
national_insurance_number: null
gender: Male
telephone: null
identity_person_id: null
reset_password_sent_at: null
remember_created_at: null
last_sign_in_at: null
slug: 75a0fbedf6b3eb13
created_at: '2026-08-05T13:00:37.000+01:00'
updated_at: '2026-08-05T13:00:37.000+01:00'
confirmation_token: null
gauth_enabled: false
gauth_tmp: null
title: null
authentication_token: AQUtxUt8Ugzt7Qd5c6md
group_id: null
line2: null
city: null
region: null
country: null
postcode: w6 4ra
line1: null
works_in_uk: true
starts_on: '2016-01-01'
authentication_token_generated_at: '2026-08-05T13:00:37.000+01:00'
company_percentage: 4
company_percentage_matched: 4
company_match: false
percentage: 2
avc_percentage: null
total_employee_percentage: 2
total_contribution_percentage: 6
contribute_if_entitled: true
enforce_password: true
ends_on: null
exit_reason: null
onboarded_at: null
opt_out_on: null
opt_state: opted_in
opt_in_on: '2026-08-05'
opt_out_window_starts_on: '2026-08-05'
opt_out_window_ends_on: '2026-09-04'
subject_to_money_purchase_annual_allowance: false
money_purchase_annual_allowance_effective_on: null
active_special_cases: []
company_id: 564
automatically_enrolled: false
contractually_enrolled: false
external_id: null
customer_id: null
referral_clicks: 0
retirement_age: 65
target_retirement_age: null
retirement_date: '2050-05-05'
target_retirement_date: null
secondary_email: null
middle_name: null
civil_status: null
country_code: null
benefit_group_id: 60
online_login_disabled: false
line3: null
uuid: a55c5d80-3d90-446b-a05a-7cb78e1464a8
eligible_for_modeller_projection: true
can_manage_contribution_rates: true
active_payroll_configuration:
id: 3
cancelled_at: null
company_id: 564
created_at: '2026-08-05T13:00:37.000+01:00'
description: nulla ac
frequency: weekly
name: payroll_name
salary_rate: annual
updated_at: '2026-08-05T13:00:37.000+01:00'
uuid: fe7d9395-77ac-4ba7-b575-296350fbecc4
employment_type: null
tax_residency_status_name: null
salary_sacrifice_signed: false
links:
- rel: company
title: company
href: https://api.host.com/companies/564
banned_params: []
schema:
$ref: '#/components/schemas/response_employee'
'422':
description: Invalid parameters
content:
application/json:
example:
errors:
- code: 2526
title: Postcode is missing.
detail: Enter a postcode.
meta: {}
source:
pointer: /data/attributes/postcode
- code: 2522
title: Forename is missing.
detail: Enter forename.
meta: {}
source:
pointer: /data/attributes/forename
- code: 2524
title: Surname is missing.
detail: Enter surname.
meta: {}
source:
pointer: /data/attributes/surname
- code: 2681
title: Gender is missing.
detail: Enter gender.
meta: {}
source:
pointer: /data/attributes/gender
- code: 2504
title: Date of birth is missing.
detail: Enter date of birth.
meta: {}
source:
pointer: /data/attributes/date_of_birth
- code: 2527
title: Employment start date is missing.
detail: Enter employment start date.
meta: {}
source:
pointer: /data/attributes/starts_on
schema:
$ref: '#/components/schemas/response_employee'
get:
summary: Companies/Employees/List with Historical Employee Data
tags:
- Employee
security:
- oAuth2:
- user
- customer
parameters:
- name: company_id
in: path
required: true
example: 725
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:
id:
type: array
items:
type: integer
forename:
type: array
items:
type: string
surname:
type: array
items:
type: string
external_id:
type: array
items:
type: string
national_insurance_number:
type: array
items:
type: string
retirement_age:
type: array
items:
type: integer
retirement_date:
type: array
items:
type: string
employee_plan_participation:
type: object
properties:
state:
type: string
updated_at:
type: array
items:
type: string
employee_contribution_configurations:
type: object
properties:
updated_at:
type: string
opt_state:
type: array
items:
type: string
starts_on:
type: array
items:
type: string
ends_on:
type: array
items:
type: string
opt_out_on:
type: array
items:
type: string
opt_in_on:
type: array
items:
type: string
exit_reason:
type: array
items:
type: string
benefit_group_id:
type: array
items:
type: integer
group_id:
type: array
items:
type: integer
required: false
style: deepObject
- name: include[]
in: query
schema:
type: array
items:
enum:
- contributions
- group
- postponements
- employee_plan_participation
- employee_contribution_configurations
- employment_category
required: false
- name: operator
in: query
schema:
type: string
enum:
- or
- and
required: false
responses:
'200':
description: Success with historical employee data
content:
application/json:
examples:
success:
value:
limit: 50
offset: 0
total: 0
links:
- rel: self
title: self
href: http://api.host.com/companies/719/employees
- rel: first
title: first
href: http://api.host.com/companies/719/employees?offset=0&limit=50
- rel: last
title: last
href: http://api.host.com/companies/719/employees?offset=0&limit=50
employees: []
success_with_client_credentials_token:
value:
limit: 50
offset: 0
total: 0
links:
- rel: self
title: self
href: http://api.host.com/companies/720/employees
- rel: first
title: first
href: http://api.host.com/companies/720/employees?offset=0&limit=50
- rel: last
title: last
href: http://api.host.com/companies/720/employees?offset=0&limit=50
employees: []
schema:
type: object
properties:
limit:
type:
- integer
- 'null'
offset:
type:
- integer
- 'null'
total:
type:
- integer
- 'null'
links:
type: array
items:
$ref: '#/components/schemas/link'
employees:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/response_employee'
example:
limit: 50
offset: 0
total: 4
links:
- rel: self
title: self
href: http://api.host.com/companies/725/employees
- rel: first
title: first
href: http://api.host.com/companies/725/employees?offset=0&limit=50
- rel: last
title: last
href: http://api.host.com/companies/725/employees?offset=0&limit=50
employees:
- updatable: true
id: 362
email: john.doe.old@example.com
forename: John
surname: Doe
date_of_birth: '1985-03-15'
national_insurance_number: AB123456C
gender: Male
telephone: 0123456789
identity_person_id: null
reset_password_sent_at: null
remember_created_at: null
last_sign_in_at: null
slug: TKHWDBHdD
created_at: '2026-08-05T13:01:25.000+01:00'
updated_at: '2026-08-05T13:01:25.000+01:00'
confirmation_token: null
gauth_enabled: false
gauth_tmp: null
title: Prof
authentication_token: null
group_id: null
line2: null
city: Rolling Hills
region: null
country: United Kingdom of Great Britain and Northern Ireland
postcode: '51011'
line1: 042 Porter Alley
works_in_uk: true
starts_on: '2016-08-05'
authentication_token_generated_at: null
company_percentage: null
company_percentage_matched: 0
company_match: false
percentage: null
avc_percentage: null
total_employee_percentage: 0
total_contribution_percentage: 0
contribute_if_entitled: true
enforce_password: true
ends_on: null
exit_reason: null
onboarded_at: null
opt_out_on: null
opt_state: ignition
opt_in_on: null
opt_out_window_starts_on: null
opt_out_window_ends_on: null
subject_to_money_purchase_annual_allowance: null
money_purchase_annual_allowance_effective_on: null
active_special_cases: []
company_id: 725
automatically_enrolled: false
contractually_enrolled: false
external_id: null
customer_id: null
referral_clicks: 0
retirement_age: 65
target_retirement_age: null
retirement_date: '2066-08-05'
target_retirement_date: null
secondary_email: null
middle_name: null
civil_status: null
country_code: GB
benefit_group_id: null
online_login_disabled: false
line3: null
uuid: 174b7a2a-28dc-4921-b002-ca6aa3a7b680
eligible_for_modeller_projection: false
can_manage_contribution_rates: true
active_payroll_configuration: null
employment_type: null
tax_residency_status_name: null
salary_sacrifice_signed: false
links:
- rel: company
title: company
href: https://api.host.com/companies/725
banned_params: []
intercom_user_id: emp362
intercom_user_id_hash: d6d86cf0cb4d76b84b9a568f7fc77f879e436843b82e202c162ca37608f8d0c8
is_not_editable: true
- updatable: true
id: 362
email: john.doe.old@example.com
forename: John
surname: Doe
date_of_birth: '1985-03-15'
national_insurance_number: AB123456C
gender: Male
telephone: 0123456789
identity_person_id: null
reset_password_sent_at: null
remember_created_at: null
last_sign_in_at: null
slug: TKHWDBHdD
created_at: '2026-08-05T13:01:25.000+01:00'
updated_at: '2026-08-05T13:01:25.000+01:00'
confirmation_token: null
gauth_enabled: false
gauth_tmp: null
title: Prof
authentication_token: null
group_id: null
line2: null
city: Rolling Hills
region: null
country: United Kingdom of Great Britain and Northern Ireland
postcode: '51011'
line1: 042 Porter Alley
works_in_uk: true
starts_on: '2016-08-05'
authentication_token_generated_at: null
company_percentage: null
company_percentage_matched: 0
company_match: false
percentage: null
avc_percentage: null
total_employee_percentage: 0
total_contribution_percentage: 0
contribute_if_entitled: true
enforce_password: true
ends_on: null
exit_reason: null
onboarded_at: null
opt_out_on: null
opt_state: ignition
opt_in_on: null
opt_out_window_starts_on: null
opt_out_window_ends_on: null
subject_to_money_purchase_annual_allowance: null
money_purchase_annual_allowance_effective_on: null
active_special_cases: []
company_id: 725
automatically_enrolled: false
contractually_enrolled: false
external_id: null
customer_id: null
referral_clicks: 0
retirement_age: 65
target_retirement_age: null
retirement_date: '2066-08-05'
target_retirement_date: null
secondary_email: null
middle_name: null
civil_status: null
country_code: GB
benefit_group_id: null
online_login_disabled: false
line3: null
uuid: 174b7a2a-28dc-4921-b002-ca6aa3a7b680
eligible_for_modeller_projection: false
can_manage_contribution_rates: true
active_payroll_configuration: null
employment_type: null
tax_residency_status_name: null
salary_sacrifice_signed: false
links:
- rel: company
title: company
href: https://api.host.com/companies/725
banned_params: []
intercom_user_id: emp362
intercom_user_id_hash: d6d86cf0cb4d76b84b9a568f7fc77f879e436843b82e202c162ca37608f8d0c8
is_not_editable: true
- updatable: true
id: 363
email: jane.smith@example.com
forename: Jane
surname: Smith
date_of_birth: '1990-07-22'
national_insurance_number: XY987654Z
gender: Female
telephone: 0987654321
identity_person_id: null
reset_password_sent_at: null
remember_created_at: null
last_sign_in_at: null
slug: QsKz2Hdnk
created_at: '2026-08-05T13:01:25.000+01:00'
updated_at: '2026-08-05T13:01:25.000+01:00'
confirmation_token: null
gauth_enabled: false
gauth_tmp: null
title: Captain
authentication_token: null
group_id: null
line2: null
city: Rio Dell
region: null
country: United Kingdom of Great Britain and Northern Ireland
postcode: 48785-9319
line1: 160 Springs Road
works_in_uk: true
starts_on: '2016-08-05'
authentication_token_generated_at: null
company_percentage: null
company_percentage_matched: 0
company_match: false
percentage: null
avc_percentage: null
total_employee_percentage: 0
total_contribution_percentage: 0
contribute_if_entitled: true
enforce_password: true
ends_on: null
exit_reason: null
onboarded_at: null
opt_out_on: null
opt_state: ignition
opt_in_on: null
opt_out_window_starts_on: null
opt_out_window_ends_on: null
subject_to_money_purchase_annual_allowance: null
money_purchase_annual_allowance_effective_on: null
active_special_cases: []
company_id: 725
automatically_enrolled: false
contractually_enrolled: false
external_id: null
customer_id: null
referral_clicks: 0
retirement_age: 65
target_retirement_age: null
retirement_date: '2066-08-05'
target_retirement_date: null
secondary_email: null
middle_name: null
civil_status: null
country_code: GB
benefit_group_id: null
online_login_disabled: false
line3: null
uuid: c27238e3-6181-4e36-9488-1d78792bc232
eligible_for_modeller_projection: false
can_manage_contribution_rates: true
active_payroll_configuration: null
employment_type: null
tax_residency_status_name: null
salary_sacrifice_signed: false
links:
- rel: company
title: company
href: https://api.host.com/companies/725
banned_params: []
intercom_user_id: emp363
intercom_user_id_hash: b90c5bb493ca565187eadaa3705c7a8d504e24fbd8f98bb555eca110dfde4800
- updatable: true
id: 363
email: jane.smith@example.com
forename: Jane
surname: Smith
date_of_birth: '1990-07-22'
national_insurance_number: XY987654Z
gender: Female
telephone: 0987654321
identity_person_id: null
reset_password_sent_at: null
remember_created_at: null
last_sign_in_at: null
slug: QsKz2Hdnk
created_at: '2026-08-05T13:01:25.000+01:00'
updated_at: '2026-08-05T13:01:25.000+01:00'
confirmation_token: null
gauth_enabled: false
gauth_tmp: null
title: Captain
authentication_token: null
group_id: null
line2: null
city: Rio Dell
region: null
country: United Kingdom of Great Britain and Northern Ireland
postcode: 48785-9319
line1: 160 Springs Road
works_in_uk: true
starts_on: '2016-08-05'
authentication_token_generated_at: null
company_percentage: null
company_percentage_matched: 0
company_match: false
percentage: null
avc_percentage: null
total_employee_percentage: 0
total_contribution_percentage: 0
contribute_if_entitled: true
enforce_password: true
ends_on: null
exit_reason: null
onboarded_at: null
opt_out_on: null
opt_state: ignition
opt_in_on: null
opt_out
# --- truncated at 32 KB (185 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/smart-pension/refs/heads/main/openapi/smart-pension-employee-api-openapi.yml