Smart Pension Employee API

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