The SSIFImports API from Smart Pension — 7 operation(s) for ssifimports.
openapi: 3.2.0
info:
title: Keystone SSIF Imports API
version: v12
description: This is the endpoint description of Keystone API.
servers:
- url: https://api.sandbox.autoenrolment.co.uk
- url: /
tags:
- name: SSIFImports
paths:
/companies/{company_id}/ssif_imports/{ssif_import_id}/assign_ssif_headers_mapping:
post:
summary: SSIFImports/AssignSSIFHeadersMapping
tags:
- SSIFImports
security:
- oAuth2:
- user
- customer
parameters:
- name: company_id
in: path
required: true
example: 1340
schema:
type: string
- name: ssif_import_id
in: path
required: true
example: 2
schema:
type: string
requestBody:
content:
application/json:
examples:
valid_params:
value:
ssif_headers_mapping_id: 23
invalid_params:
value:
ssif_headers_mapping_id: abc
authorizers_eroor:
value:
ssif_headers_mapping_id: 24
import_belongs_to_other_company:
value:
ssif_headers_mapping_id: 25
not_found:
value:
ssif_headers_mapping_id: 26
unauthorized:
value:
ssif_headers_mapping_id: 27
schema:
type: object
properties:
ssif_headers_mapping_id:
type: integer
required:
- ssif_headers_mapping_id
responses:
'200':
description: Success
content:
application/json:
example:
id: 2
created_at: '2026-08-05T13:04:47.000+01:00'
updated_at: '2026-08-05T13:04:48.000+01:00'
file_content_type: text/csv
file_errors: []
header_errors: []
file_file_name: valid_employees_import.csv
file_file_size: 1259
file_updated_at: '2026-08-05T13:04:47.000+01:00'
state: ignition
ssif_headers_mapping_id: 23
response_errors: []
file_url: /__w/api/api/spec/test_files/0/ssif_imports/000/000/002/original/valid_employees_import.csv
type: text/csv
metadata: null
success_row_count: 0
failure_row_count: 0
partial_success_row_count: 0
unchanged_row_count: 0
errors_count: 0
failed_row_actions_count: 0
unrecognized_headers: []
schema:
$ref: '#/components/schemas/response_ssif_import'
'403':
description: Forbidden
content:
application/json:
example:
errors:
- code: 374
title: You don't have the neccessary rights to perform this action.
detail: You don't have the necessary rights to perform this action.
form: null
attribute: base
error: generic_forbidden
meta: {}
source:
pointer: /base
'404':
description: Not found
content:
application/json:
example: ''
'422':
description: Invalid parameters
content:
application/json:
example:
errors:
- code: 102005
title: Value must be numerical.
detail: SSIF headers mapping id should be a numerical value.
meta:
value: abc
source:
pointer: /data/attributes/ssif_headers_mapping_id
/companies/{company_id}/ssif_imports:
post:
summary: SSIFImports/Create
tags:
- SSIFImports
security:
- oAuth2:
- user
- customer
parameters:
- name: company_id
in: path
required: true
example: 1348
schema:
type: string
requestBody:
content:
multipart/form-data:
example:
file: '#<Rack::Test::UploadedFile:0x00007ba22a089c18>'
schema:
type: object
properties:
file:
type: string
format: binary
required:
- file
responses:
'201':
description: Success - Import a file (csv/xml format)
content:
application/json:
example:
id: 7
created_at: '2026-08-05T13:04:50.000+01:00'
updated_at: '2026-08-05T13:04:50.000+01:00'
file_content_type: text/csv
file_errors: []
header_errors: []
file_file_name: valid.csv
file_file_size: 792
file_updated_at: '2026-08-05T13:04:50.000+01:00'
state: ignition
ssif_headers_mapping_id: null
response_errors: []
file_url: /__w/api/api/spec/test_files/0/ssif_imports/000/000/007/original/valid.csv
type: text/csv
metadata: null
success_row_count: 0
failure_row_count: 0
partial_success_row_count: 0
unchanged_row_count: 0
errors_count: 0
failed_row_actions_count: 0
unrecognized_headers: []
schema:
$ref: '#/components/schemas/response_ssif_import'
'422':
description: Failing when parameters are invalid.
get:
summary: SSIFImports/List
tags:
- SSIFImports
security:
- oAuth2:
- user
- customer
parameters:
- name: company_id
in: path
required: true
example: 1366
schema:
type: string
- name: offset
in: query
required: false
schema:
type: string
- name: limit
in: query
required: false
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
examples:
success:
value:
limit: 50
offset: 0
total: 0
links:
- rel: self
title: self
href: http://api.host.com/companies/1365/ssif_imports
- rel: first
title: first
href: http://api.host.com/companies/1365/ssif_imports?offset=0&limit=50
- rel: last
title: last
href: http://api.host.com/companies/1365/ssif_imports?offset=0&limit=50
data: []
success_with_client_credentials_token:
value:
limit: 50
offset: 0
total: 0
links:
- rel: self
title: self
href: http://api.host.com/companies/1366/ssif_imports
- rel: first
title: first
href: http://api.host.com/companies/1366/ssif_imports?offset=0&limit=50
- rel: last
title: last
href: http://api.host.com/companies/1366/ssif_imports?offset=0&limit=50
data: []
schema:
type: object
properties:
limit:
type:
- integer
- 'null'
offset:
type:
- integer
- 'null'
total:
type:
- integer
- 'null'
links:
type: array
items:
$ref: '#/components/schemas/link'
data:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/response_ssif_import'
'401':
description: Unauthorized
/companies/{company_id}/ssif_imports/{ssif_import_id}/file_headers:
get:
summary: SSIFImports/FileHeaders
tags:
- SSIFImports
security:
- oAuth2:
- user
- customer
parameters:
- name: company_id
in: path
required: true
example: 1350
schema:
type: string
- name: ssif_import_id
in: path
required: true
example: 8
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
example:
id: 8
file_headers:
- BirthDate
- Surname
- EmployerID
- PostalCode
- Forename1
- EmploymentStartDate
- BenefitGroupID
- PlatformID
- Gender
- EmailAddress
- Title
- NationalIDNumber
- Address1
- Address2
- City
- County
- EmployeeID
- ExitDate
- ExitReasonCode
- EmployerContributionAmount
- ContributionDueDate
- AdditionalVoluntaryContributionPercent
- PayrollName
- EmployeeContributionAmount
- EmployerContributionPercent
- EmployeeContributionPercent
- AdditionalVoluntaryContributionAmount
- Earnings1
- Earnings2
- Forename2
- Country
- SecondaryEmailAddress
- CivilStatus
- EventCode
- EventDate
- EffectiveDate
- SchemeID
- EmploymentStatus
- PartTimePercentage
- EmploymentCategory
- SalarySacrifice
- RiskSalary1
- RiskSalary2
- EmployerContributionAmountSingle
- EmployeeContributionAmountSingle
- AdditionalVoluntaryContributionAmountSingle
- AnnualEarnings1
- AnnualEarnings2
platform_headers:
- attribute_name: papdis_version
humanized_name: PAPDISVersion
group: File details
order: 1
required: true
- attribute_name: platform_id
humanized_name: PensionProviderId
group: File details
order: 2
required: true
- attribute_name: title
humanized_name: Title
group: Personal details
order: 1
required: true
- attribute_name: forename
humanized_name: Forename1
group: Personal details
order: 2
required: true
- attribute_name: middle_name
humanized_name: Forename2
group: Personal details
order: 3
required: false
- attribute_name: surname
humanized_name: Surname
group: Personal details
order: 4
required: true
- attribute_name: date_of_birth
humanized_name: BirthDate
group: Personal details
order: 5
required: true
- attribute_name: gender
humanized_name: Gender
group: Personal details
order: 6
required: true
- attribute_name: external_id
humanized_name: EmployeeId
group: Employment details
order: 1
required: true
- attribute_name: employer_id
humanized_name: EmployerId
group: Employment details
order: 2
required: true
- attribute_name: starts_on
humanized_name: EmploymentStartDate
group: Employment details
order: 3
required: true
- attribute_name: ends_on
humanized_name: ExitDate
group: Employment details
order: 4
required: false
- attribute_name: exit_reason
humanized_name: ExitReasonCode
group: Employment details
order: 5
required: false
- attribute_name: event_code
humanized_name: EventCode
group: Employment details
order: 6
required: true
- attribute_name: event_date
humanized_name: EventDate
group: Employment details
order: 7
required: false
- attribute_name: group_name
humanized_name: Group
group: Employment details
order: 8
required: true
- attribute_name: sub_group
humanized_name: SubGroup
group: Employment details
order: 9
required: false
- attribute_name: assessment_code
humanized_name: AssessmentCode
group: Employment details
order: 10
required: true
- attribute_name: deferral_on
humanized_name: DeferralDate
group: Employment details
order: 11
required: false
- attribute_name: aeo_opt_out_date
humanized_name: AEOptOutDate
group: Employment details
order: 12
required: false
- attribute_name: aeo_opt_out_reference
humanized_name: AEOptOutReference
group: Employment details
order: 13
required: false
- attribute_name: communications_issued_date
humanized_name: EnrolmentCommunicationsIssuedDate
group: Employment details
order: 14
required: false
- attribute_name: national_insurance_number
humanized_name: NationalInsuranceNumber
group: Identification details
order: 1
required: true
- attribute_name: line1
humanized_name: Address1
group: Residential address
order: 1
required: true
- attribute_name: line2
humanized_name: Address2
group: Residential address
order: 2
required: true
- attribute_name: line4
humanized_name: Address4
group: Residential address
order: 3
required: true
- attribute_name: city
humanized_name: Address3
group: Residential address
order: 4
required: true
- attribute_name: postcode
humanized_name: Postcode
group: Residential address
order: 5
required: true
- attribute_name: country
humanized_name: Country
group: Residential address
order: 6
required: false
- attribute_name: email
humanized_name: EmailAddress
group: Contact details
order: 1
required: true
- attribute_name: secondary_email
humanized_name: SecondaryEmailAddress
group: Contact details
order: 2
required: false
- attribute_name: contribution_deduction_date
humanized_name: ContributionDeductionDate
group: Contribution details
order: 1
required: true
- attribute_name: contribution_starts_on
humanized_name: PayPeriodStartDate
group: Contribution details
order: 2
required: true
- attribute_name: contribution_ends_on
humanized_name: PayPeriodEndDate
group: Contribution details
order: 3
required: true
- attribute_name: period_type
humanized_name: FrequencyCode
group: Contribution details
order: 4
required: true
- attribute_name: pensionable_earnings
humanized_name: PensionableEarningsAmount
group: Contribution details
order: 5
required: true
- attribute_name: company_amount
humanized_name: EmployerContributionsAmount
group: Contribution details
order: 6
required: true
- attribute_name: employee_amount
humanized_name: EmployeeContributionsAmount
group: Contribution details
order: 7
required: true
- attribute_name: company_percentage
humanized_name: EmployerContributionsPercent
group: Contribution details
order: 8
required: true
- attribute_name: employee_percentage
humanized_name: EmployeeContributionsPercent
group: Contribution details
order: 9
required: true
- attribute_name: voluntary_amount
humanized_name: AdditionalVoluntaryContributionsAmount
group: Contribution details
order: 10
required: false
- attribute_name: tax_period
humanized_name: TaxPeriod
group: Contribution details
order: 11
required: true
- attribute_name: additional_voluntary_contribution_percent
humanized_name: AdditionalVoluntaryContributionsPercent
group: Contribution details
order: 12
required: false
- attribute_name: salary_sacrifice_signed
humanized_name: SalarySacrificeIndicator
group: Salary sacrifice details
order: 1
required: true
schema:
$ref: '#/components/schemas/response_ssif_import_file_headers'
'403':
description: Forbidden
'404':
description: Failing when ssif import does not exist
/companies/{company_id}/ssif_imports/template:
get:
summary: SSIFImports/Template
tags:
- SSIFImports
security:
- oAuth2:
- user
- customer
parameters:
- name: company_id
in: path
required: true
example: 1356
schema:
type: string
responses:
'200':
description: Success
content:
text/csv:
example: 'PAPDISVersion,PensionProviderId,EmployerId,Group,PayPeriodStartDate,PayPeriodEndDate,ContributionDeductionDate,FrequencyCode,TaxPeriod,Title,Forename1,Surname,EmployeeId,BirthDate,Gender,NationalInsuranceNumber,Address1,Address2,Address3,Address4,Postcode,EmailAddress,EmploymentStartDate,AssessmentCode,EventCode,PensionableEarningsAmount,SalarySacrificeIndicator
'
/companies/{company_id}/ssif_imports/{ssif_import_id}:
get:
summary: SSIFImports/Get
tags:
- SSIFImports
security:
- oAuth2:
- user
- customer
parameters:
- name: company_id
in: path
required: true
example: 1363
schema:
type: string
- name: ssif_import_id
in: path
required: true
example: 14
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
examples:
success:
value:
id: 11
created_at: '2026-08-05T13:04:53.000+01:00'
updated_at: '2026-08-05T13:04:53.000+01:00'
file_content_type: text/csv
file_errors: []
header_errors: []
file_file_name: valid_employees_import.csv
file_file_size: 1259
file_updated_at: '2026-08-05T13:04:53.000+01:00'
state: ignition
ssif_headers_mapping_id: null
response_errors: []
file_url: /__w/api/api/spec/test_files/0/ssif_imports/000/000/011/original/valid_employees_import.csv
type: text/csv
metadata: null
success_row_count: 0
failure_row_count: 0
partial_success_row_count: 0
unchanged_row_count: 0
errors_count: 0
failed_row_actions_count: 0
unrecognized_headers: []
success_with_client_credentials_token:
value:
id: 14
created_at: '2026-08-05T13:04:54.000+01:00'
updated_at: '2026-08-05T13:04:54.000+01:00'
file_content_type: text/csv
file_errors: []
header_errors: []
file_file_name: valid_employees_import.csv
file_file_size: 1259
file_updated_at: '2026-08-05T13:04:54.000+01:00'
state: ignition
ssif_headers_mapping_id: null
response_errors: []
file_url: /__w/api/api/spec/test_files/0/ssif_imports/000/000/014/original/valid_employees_import.csv
type: text/csv
metadata: null
success_row_count: 0
failure_row_count: 0
partial_success_row_count: 0
unchanged_row_count: 0
errors_count: 0
failed_row_actions_count: 0
unrecognized_headers: []
schema:
$ref: '#/components/schemas/response_ssif_import'
'401':
description: Unauthorized
content:
text/html:
examples:
unauthorized_with_client_credentials_token:
value: ''
'403':
description: Forbidden
content:
application/json:
examples:
unauthorized:
value:
errors:
- code: 374
title: You don't have the neccessary rights to perform this action.
detail: You don't have the necessary rights to perform this action.
form: null
attribute: base
error: generic_forbidden
meta: {}
source:
pointer: /base
'404':
description: Failing when ssif import does not exist
content:
application/json:
examples:
ssif_import_belongs_to_another_company:
value: ''
ssif_import_does_not_exist:
value: ''
/companies/{company_id}/ssif_imports/{ssif_import_id}/ssif_import_missing_employees:
get:
summary: SSIFImports/SSIFImportMissingEmployees/List
tags:
- SSIFImports
security:
- oAuth2:
- user
- customer
parameters:
- name: company_id
in: path
required: true
example: 1368
schema:
type: string
- name: ssif_import_id
in: path
required: true
example: 16
schema:
type: string
- name: offset
in: query
required: false
schema:
type: string
- name: limit
in: query
required: false
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
examples:
success:
value:
limit: 50
offset: 0
total: 1
links:
- rel: self
title: self
href: http://api.host.com/companies/1368/ssif_imports/16/ssif_import_missing_employees
- rel: first
title: first
href: http://api.host.com/companies/1368/ssif_imports/16/ssif_import_missing_employees?offset=0&limit=50
- rel: last
title: last
href: http://api.host.com/companies/1368/ssif_imports/16/ssif_import_missing_employees?offset=0&limit=50
employees:
- updatable: true
id: 640
email: employee_736@example.com
forename: Sara
surname: Chavez
date_of_birth: '2001-08-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: ZXUz1CR
created_at: '2026-08-05T13:04:57.000+01:00'
updated_at: '2026-08-05T13:04:57.000+01:00'
confirmation_token: null
gauth_enabled: false
gauth_tmp: null
title: Lady
authentication_token: null
group_id: null
line2: null
city: Pasadena
region: null
country: United Kingdom of Great Britain and Northern Ireland
postcode: 47561-6075
line1: 91056 East Street
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: 1368
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: 5adb93cb-6db7-40da-b116-fd179e27585e
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/1368
banned_params: []
intercom_user_id: emp640
intercom_user_id_hash: f6f240d5307e02251ccddfdb0cbef7d591ee3f189ddd950ee1dd145eb09125f0
scheme_external_id: PRODUCT-53562d53
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_missing_employee'
'401':
description: Unauthorized
content:
text/plain:
examples:
header_unauthorized:
value: 'HTTP Token: Access denied.
'
'404':
description: Not Found
'422':
description: Invalid parameters
/companies/{company_id}/ssif_imports/{ssif_import_id}/ssif_import_results:
get:
summary: SSIFImports/SSIFImportResults/List
tags:
- SSIFImports
security:
- oAuth2:
- user
- customer
parameters:
- name: company_id
in: path
required: true
example: 1378
schema:
type: string
- name: ssif_import_id
in: path
required: true
example: 25
schema:
type: string
- name: offset
in: query
required: false
schema:
type: string
- name: limit
in: query
required: false
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
examples:
success:
value:
# --- truncated at 32 KB (122 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/smart-pension/refs/heads/main/openapi/smart-pension-ssifimports-api-openapi.yml