The Letters API from Smart Pension — 6 operation(s) for letters.
openapi: 3.2.0
info:
title: Keystone Letters API
version: v12
description: This is the endpoint description of Keystone API.
servers:
- url: https://api.sandbox.autoenrolment.co.uk
- url: /
tags:
- name: Letters
paths:
/companies/{company_id}/employees/{employee_id}/letters:
post:
summary: Letters/Create
tags:
- Letters
security:
- oAuth2:
- customer
parameters:
- name: company_id
in: path
required: true
example: 714
schema:
type: string
- name: employee_id
in: path
required: true
example: 355
schema:
type: string
requestBody:
content:
application/json:
examples:
Creating welcome letter:
value:
letter:
name: welcome
Creating postponement letter:
value:
letter:
name: postpone
schema:
type: object
properties:
name:
type: string
enum:
- ad_hoc_benefit_statement
- annual_benefit_statement
- annual_statement_over_64
- annual_statement_under_64_with_recent_contributions
- annual_statement_under_64_without_recent_contributions
- automatic_benefit_group_assigned
- benefit_in
- company_fee_default
- deed_of_participation
- employee_notification_of_participation_for_employer
- employee_percentage_explicitly_changed
- percentage_auto_increase_policy_assigned
- enroll
- contractual_enrolment
- exit_statement
- four_months_to_retirement
- gavc_ad_hoc_benefit_statement
- gavc_pension_benefit_statement
- generic_company_fee
- overall_charge
- ill_health
- invite_secondary
- invited_to_join_scheme
- leaver_letter_over_55
- leaver_letter_under_55
- left_employment_sorp_calculation
- left_employment_with_holdings
- gavc_left_employment_with_holdings
- lifestyle_derisking
- indemnity_termination_with_holdings
- migration_transfer_in
- migration_assets_transfer
- new_joiner_sorp_calculation
- new_member_statement
- opted_out
- participation_agreement
- payment
- payment_schedules
- pension_benefit_statement
- plan_overview
- policy_fee
- policy_fee_automated_collection
- portfolio_switch_completed
- gavc_portfolio_switch_completed
- portfolio_redirect_created
- postpone
- regulatory_fee
- regulatory_fee_automated_collection
- retirement
- six_months_to_retirement
- small_fund
- summary_plan_description
- tax_relief_playback_declaration
- transfer_in
- transfer_out
- trust_welcome
- two_months_to_retirement
- un_enroll
- wake_up_2_months_to_retirement
- wake_up_4_months_to_retirement
- wake_up_6_months_to_retirement
- wake_up_6_months_to_age_75
- wake_up_5_years_to_retirement
- wake_up_age_50
- wake_up_age_73_and_74
- wake_up_5_years_after_retirement
- welcome
- member_account_summary_letter
- welcome_laver_leisure_jlg
- welcome_scheme_transferred_employee_active
- welcome_scheme_transferred_employee_deferred
- welcome_scheme_transferred_employee_non_member
- signatories
- rbce_certificate
- gavc_single_contribution_invested
- gavc_account_created
- gavc_summary_plan_description
- gavc_new_member_statement
- gavc_risk_application_summary
- employer_agreement
created_at:
type: string
responses:
'201':
description: Creates a postponement letter
content:
application/json:
examples:
Creating welcome letter:
value:
id: 5
subject: Welcome to your Smart Pension
name: welcome
employee_id: 352
read: false
file_url: null
file_file_name: null
created_at: '2026-08-05T13:01:20.000+01:00'
updated_at: '2026-08-05T13:01:20.000+01:00'
cancelled_at: null
created_by_id: 352
created_by_type: Employee
links:
- rel: letter
title: letter
href: https://api.host.com/companies/711/employees/352/letters/5
Creating postponement letter:
value:
id: 6
subject: Information about when your pension will start.
name: postpone
employee_id: 355
read: false
file_url: null
file_file_name: null
created_at: '2026-08-05T13:01:21.000+01:00'
updated_at: '2026-08-05T13:01:21.000+01:00'
cancelled_at: null
created_by_id: 2
created_by_type: Postponement
links:
- rel: letter
title: letter
href: https://api.host.com/companies/714/employees/355/letters/6
schema:
$ref: '#/components/schemas/response_letter'
'422':
description: Invalid parameters
get:
summary: Companies/Employees/Letters/List
tags:
- Letters
security:
- oAuth2:
- customer
parameters:
- 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:
read:
type: array
items:
type: boolean
employee_id:
type: array
items:
type: integer
name:
type: array
items:
type: string
created_at:
type: array
items:
type: string
required: false
style: deepObject
- name: operator
in: query
schema:
type: string
enum:
- or
- and
required: false
- name: company_id
in: path
required: true
example: 1451
schema:
type: string
- name: employee_id
in: path
required: true
example: 672
schema:
type: string
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/1451/employees/672/letters
- rel: first
title: first
href: http://api.host.com/companies/1451/employees/672/letters?offset=0&limit=50
- rel: last
title: last
href: http://api.host.com/companies/1451/employees/672/letters?offset=0&limit=50
letters:
- id: 29
subject: Welcome to your Smart Pension
name: welcome
employee_id: 672
read: false
file_url: /__w/api/api/spec/test_files/0/letters/letters/000/000/029/original/file.pdf
file_file_name: file.pdf
created_at: '2026-08-05T13:05:38.000+01:00'
updated_at: '2026-08-05T13:05:38.000+01:00'
cancelled_at: null
created_by_id: 672
created_by_type: Employee
links:
- rel: letter
title: letter
href: https://api.host.com/companies/1451/employees/672/letters/29
schema:
type: object
properties:
limit:
type:
- integer
- 'null'
offset:
type:
- integer
- 'null'
total:
type:
- integer
- 'null'
links:
type: array
items:
$ref: '#/components/schemas/link'
letters:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/response_letter'
/companies/{company_id}/employees/{employee_id}/letters/{id}:
get:
summary: Letters/Get
tags:
- Letters
security:
- oAuth2:
- employee
parameters:
- name: id
in: path
required: true
example: 7
schema:
type: string
- name: company_id
in: path
required: true
example: 717
schema:
type: string
- name: employee_id
in: path
required: true
example: 358
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
example:
id: 7
subject: null
name: payment
employee_id: 358
read: false
file_url: null
file_file_name: null
created_at: '2026-08-05T13:01:21.000+01:00'
updated_at: '2026-08-05T13:01:21.000+01:00'
cancelled_at: null
created_by_id: null
created_by_type: null
links:
- rel: letter
title: letter
href: https://api.host.com/companies/717/employees/358/letters/7
schema:
$ref: '#/components/schemas/response_letter'
'404':
description: Not Found
put:
summary: Companies/Employees/Letters/Update
tags:
- Letters
security:
- oAuth2:
- customer
parameters:
- name: company_id
in: path
required: true
example: 1452
schema:
type: string
- name: employee_id
in: path
required: true
example: 673
schema:
type: string
- name: id
in: path
required: true
example: 30
schema:
type: string
requestBody:
content:
application/json:
example: null
responses:
'204':
description: Success
'404':
description: Not Found
patch:
summary: Companies/Employees/Letters/Update
tags:
- Letters
security:
- oAuth2:
- customer
parameters:
- name: company_id
in: path
required: true
example: 1454
schema:
type: string
- name: employee_id
in: path
required: true
example: 675
schema:
type: string
- name: id
in: path
required: true
example: 32
schema:
type: string
requestBody:
content:
application/json:
example: null
responses:
'204':
description: Success
'404':
description: Not Found
/companies/{company_id}/letters:
get:
summary: Companies/Letters/List with Historical Employee Data
tags:
- Letters
security:
- oAuth2:
- customer
parameters:
- name: company_id
in: path
required: true
example: 1153
schema:
type: string
- name: include[]
in: query
items:
type: string
required: false
example: include[]=employee
schema:
type: array
responses:
'200':
description: Success with historical employee data
content:
application/json:
example:
limit: 50
offset: 0
total: 2
links:
- rel: self
title: self
href: http://api.host.com/companies/1153/letters?include%5B%5D=employee
- rel: first
title: first
href: http://api.host.com/companies/1153/letters?include%5B%5D=employee&offset=0&limit=50
- rel: last
title: last
href: http://api.host.com/companies/1153/letters?include%5B%5D=employee&offset=0&limit=50
letters:
- id: 27
subject: Information about when your pension will start.
name: postpone
employee_id: 593
read: false
file_url: null
file_file_name: null
created_at: '2026-08-05T13:03:41.000+01:00'
updated_at: '2026-08-05T13:03:41.000+01:00'
cancelled_at: null
created_by_id: 23
created_by_type: Postponement
links: []
employee:
updatable: true
id: 593
email: employee_689@example.com
forename: Robert
surname: Taylor
date_of_birth: '2001-08-05'
national_insurance_number: RT123456C
gender: Male
telephone: null
identity_person_id: null
reset_password_sent_at: null
remember_created_at: null
last_sign_in_at: null
slug: zX40zawdBLE
created_at: '2026-08-05T13:03:41.000+01:00'
updated_at: '2026-08-05T13:03:41.000+01:00'
confirmation_token: null
gauth_enabled: false
gauth_tmp: null
title: Captain
authentication_token: null
group_id: null
line2: null
city: Laguna Beach
region: null
country: United Kingdom of Great Britain and Northern Ireland
postcode: '70006'
line1: 1 Michigan Court
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: 1153
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: 95a82ee3-2a8e-4ec7-ad0a-7b11c4e02161
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/1153
banned_params: []
intercom_user_id: emp593
intercom_user_id_hash: 2a476394c23604e140ad04515bf91acd155b17f441a6c7ff76caaba17a7dd5e1
- id: 28
subject: Your invite to your workplace pension scheme
name: invited_to_join_scheme
employee_id: 594
read: false
file_url: null
file_file_name: null
created_at: '2026-08-05T13:03:41.000+01:00'
updated_at: '2026-08-05T13:03:41.000+01:00'
cancelled_at: null
created_by_id: null
created_by_type: null
links: []
employee:
updatable: true
id: 594
email: employee_690@example.com
forename: Emily
surname: Davis
date_of_birth: '2001-08-05'
national_insurance_number: ED987654Z
gender: Female
telephone: null
identity_person_id: null
reset_password_sent_at: null
remember_created_at: null
last_sign_in_at: null
slug: fZwMGdv
created_at: '2026-08-05T13:03:41.000+01:00'
updated_at: '2026-08-05T13:03:41.000+01:00'
confirmation_token: null
gauth_enabled: false
gauth_tmp: null
title: Prof
authentication_token: null
group_id: null
line2: null
city: Clayton
region: null
country: United Kingdom of Great Britain and Northern Ireland
postcode: 41250-1623
line1: 173 Truax Court
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: 1153
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: 21232205-c581-4e8e-b696-f84b44039546
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/1153
banned_params: []
intercom_user_id: emp594
intercom_user_id_hash: 5138a3092cb8e9da8f7ac4bbcd2713c7eda804e6aadba80af4f01e328e5b13ab
schema:
type: object
properties:
limit:
type:
- integer
- 'null'
offset:
type:
- integer
- 'null'
total:
type:
- integer
- 'null'
links:
type: array
items:
$ref: '#/components/schemas/link'
letters:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/response_letter'
'401':
description: Unauthorized
'404':
description: Not Found
description: 'Lists letters for a company. When the ''exited_employees_visibility'' feature flag is enabled,
letters for employees who exited more than 6 weeks ago will display historical employee data
(forename, surname, and national_insurance_number as they were at the time of exit) instead of current data.
This applies to the employee, recipient, and created_by associations.
'
/companies/{company_id}/letters/{id}:
get:
summary: Companies/Letters/Get
tags:
- Letters
security:
- oAuth2:
- customer
parameters:
- name: company_id
in: path
required: true
example: 1144
schema:
type: string
- name: id
in: path
required: true
example: 17
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
example:
id: 17
subject: Information about when your pension will start.
name: postpone
employee_id: 586
read: false
file_url: null
file_file_name: null
created_at: '2026-08-05T13:03:38.000+01:00'
updated_at: '2026-08-05T13:03:38.000+01:00'
cancelled_at: null
created_by_id: 17
created_by_type: Postponement
links: []
schema:
$ref: '#/components/schemas/response_letter'
'401':
description: Unauthorized
'404':
description: Not Found
/companies/{company_id}/letters/postponement:
post:
summary: Companies/Letters/Postponement/Create
tags:
- Letters
security:
- oAuth2:
- customer
parameters:
- name: company_id
in: path
required: true
example: 1156
schema:
type: string
requestBody:
content:
application/json:
examples:
success:
value:
type: unreceived
invalid_parameters:
value:
type: ''
schema:
type: object
properties:
type:
type: string
enum:
- all
- unreceived
required:
- type
responses:
'204':
description: Success
'403':
description: Forbidden
content:
application/json:
examples:
company_does_not_have_staging_date:
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
'404':
description: Not Found
content:
application/json:
examples:
company_not_found:
value: ''
text/html:
examples:
creation_of_postponement_letters_is_disabled:
value: ''
'422':
description: Invalid Parameters
content:
application/json:
examples:
invalid_parameters:
value:
errors:
- code: 2101
title: Type is a required field.
detail: You need to include the type.
meta: {}
source:
pointer: /data/attributes/type
- code: 2102
title: Type is not valid.
detail: 'Please select from this list of valid type: new, all.'
meta:
values:
- all
- unreceived
value: null
source:
pointer: /data/attributes/type
/companies/{company_id}/letters/welcome:
post:
summary: Companies/Letters/Welcome/Create
tags:
- Letters
security:
- oAuth2:
- customer
parameters:
- name: company_id
in: path
required: true
example: 1166
schema:
type: string
requestBody:
content:
application/json:
examples:
success:
value:
type: unreceived
invalid_parameters:
value:
type: ''
schema:
type: object
properties:
type:
type: string
enum:
- all
- unreceived
required:
- type
responses:
'204':
description: Success
'403':
description: Forbidden
content:
application/json:
examples:
company_does_not_have_staging_date:
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
'404':
description: Not Found
content:
application/json:
examples:
company_not_found:
value: ''
text/html:
examples:
creation_of_welcome_letters_is_disabled:
value: ''
'422':
description: Invalid Parameters
content:
application/json:
examples:
invalid_parameters:
value:
errors:
- code: 2101
title: Type is a required field.
detail: You need to include the type.
meta: {}
source:
pointer: /data/attributes/type
- code: 2102
title: Type is not valid.
detail: 'Please select from this list of valid type: new, all.'
meta:
values:
- all
- unreceived
value: null
source:
pointer: /data/attributes/type
components:
schemas:
response_band:
type: object
properties:
id:
type: integer
employee_minimum_percentage:
type: number
format: float
employee_maximum_percentage:
type:
- number
- 'null'
format: float
employer_percentage:
type: number
format: float
starts_on:
type: string
format: date
ends_on:
type: string
format: date
range_min:
type:
- integer
- 'null'
range_max:
type:
- integer
- 'null'
default:
type: boolean
response_scheme_contribution_limit:
type: object
properties:
minimum_one_off_contribution_amount:
type: number
format: float
minimum_one_off_contribution_amount_currency:
type: string
maximum_one_off_contribution_amount:
type: number
format: float
maximum_one_off_contribution_amount_currency:
type: string
minimum_recurring_contribution_amount:
type: number
format: float
minimum_recurring_contribution_amount_currency:
type: string
response_adviser:
type: object
properties:
intercom_user_id:
type:
- string
- 'null'
intercom_user_id_ha
# --- truncated at 32 KB (97 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/smart-pension/refs/heads/main/openapi/smart-pension-letters-api-openapi.yml