Smart Pension Postponement API

openapi: 3.2.0
info:
  title: Keystone Postponement API
  version: v12
  description: This is the endpoint description of Keystone API.
servers:
- url: https://api.sandbox.autoenrolment.co.uk
- url: /
tags:
- name: Postponement
paths:
  /companies/{company_id}/employees/{employee_id}/postponements:
    post:
      summary: Postponement/Create
      tags:
      - Postponement
      security:
      - oAuth2:
        - user
        - customer
      parameters:
      - name: company_id
        in: path
        required: true
        example: 807
        schema:
          type: string
      - name: employee_id
        in: path
        required: true
        example: 422
        schema:
          type: string
      requestBody:
        content:
          application/json:
            examples:
              success:
                value:
                  deferral_on: '2026-08-06'
              invalid_parameters:
                value:
                  deferral_on: ''
            schema:
              type: object
              properties:
                include:
                  type: array
                  items:
                    enum:
                    - employee
      responses:
        '201':
          description: Creates a postponement
          content:
            application/json:
              example:
                id: 3
                employee_id: 422
                starts_on: '2026-08-05'
                ends_on: '2026-08-05'
                created_at: '2026-08-05T13:01:46.000+01:00'
                updated_at: '2026-08-05T13:01:46.000+01:00'
                deferral_on: '2026-08-06'
                cancelled_at: null
                links:
                - rel: employee
                  title: employee
                  href: https://api.host.com/companies/807/employees/422
              schema:
                $ref: '#/components/schemas/response_postponement'
        '422':
          description: Invalid parameters
          content:
            application/json:
              example:
                errors:
                - code: 1401
                  title: The deferral date is a required field.
                  detail: You need to select a deferral date for the postponement. This can be any date up to 3 months and a day later than either your staging date or the employees start of employment, which ever is the latest.
                  meta: {}
                  source:
                    pointer: /data/attributes/deferral_on
    get:
      summary: Postponement/List
      tags:
      - Postponement
      security:
      - oAuth2:
        - user
        - customer
      parameters:
      - name: company_id
        in: path
        required: true
        example: 819
        schema:
          type: string
      - name: employee_id
        in: path
        required: true
        example: 429
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                limit: 50
                offset: 0
                total: 0
                links:
                - rel: self
                  title: self
                  href: http://api.host.com/companies/819/employees/429/postponements
                - rel: first
                  title: first
                  href: http://api.host.com/companies/819/employees/429/postponements?offset=0&limit=50
                - rel: last
                  title: last
                  href: http://api.host.com/companies/819/employees/429/postponements?offset=0&limit=50
                postponements: []
              schema:
                type: object
                properties:
                  limit:
                    type:
                    - integer
                    - 'null'
                  offset:
                    type:
                    - integer
                    - 'null'
                  total:
                    type:
                    - integer
                    - 'null'
                  links:
                    type: array
                    items:
                      $ref: '#/components/schemas/link'
                  postponements:
                    type:
                    - array
                    - 'null'
                    items:
                      $ref: '#/components/schemas/response_postponement'
  /companies/{company_id}/employees/{employee_id}/postponements/{id}:
    delete:
      summary: Postponement/Destroy
      tags:
      - Postponement
      security:
      - oAuth2:
        - user
        - customer
      parameters:
      - name: id
        in: path
        required: true
        example: 4
        schema:
          type: string
      - name: company_id
        in: path
        required: true
        example: 809
        schema:
          type: string
      - name: employee_id
        in: path
        required: true
        example: 424
        schema:
          type: string
      responses:
        '204':
          description: Success
        '403':
          description: Forbidden when the employee already has a contribution
        '404':
          description: Not Found
    get:
      summary: Postponement/Get
      tags:
      - Postponement
      security:
      - oAuth2:
        - user
        - customer
      parameters:
      - name: id
        in: path
        required: true
        example: 7
        schema:
          type: string
      - name: company_id
        in: path
        required: true
        example: 815
        schema:
          type: string
      - name: employee_id
        in: path
        required: true
        example: 427
        schema:
          type: string
      - name: include[]
        in: query
        schema:
          type: array
          items:
            enum:
            - employee
        required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                id: 7
                employee_id: 427
                starts_on: '2026-08-05'
                ends_on: '2026-08-05'
                created_at: '2026-08-05T13:01:48.000+01:00'
                updated_at: '2026-08-05T13:01:48.000+01:00'
                deferral_on: '2026-08-06'
                cancelled_at: null
                links:
                - rel: employee
                  title: employee
                  href: https://api.host.com/companies/815/employees/427
              schema:
                $ref: '#/components/schemas/response_postponement'
        '404':
          description: Not Found
    put:
      summary: Postponement/Update
      tags:
      - Postponement
      security:
      - oAuth2:
        - user
        - customer
      parameters:
      - name: id
        in: path
        required: true
        example: 9
        schema:
          type: string
      - name: company_id
        in: path
        required: true
        example: 820
        schema:
          type: string
      - name: employee_id
        in: path
        required: true
        example: 430
        schema:
          type: string
      requestBody:
        content:
          application/json:
            examples:
              success:
                value:
                  starts_on: '2026-08-05'
                  deferral_on: '2026-08-06'
                  postponement:
                    deferral_on: '2026-08-06'
                  employee:
                    id: 430
                    api_key: api_key
                    authentication_token: null
                    authentication_token_generated_at: null
                    automatically_enrolled: false
                    bank_account_detail_id: null
                    benefit_group_id: null
                    city: Oakdale
                    civil_status: null
                    company_id: 820
                    company_match: false
                    confirmation_token: null
                    contribute_if_entitled: true
                    country_code: GB
                    created_at: '2026-08-05T13:01:49.000+01:00'
                    customer_id: null
                    date_of_birth: '2001-08-05'
                    date_of_birth_confirmed: false
                    email: employee_518@example.com
                    employee_classification: null
                    employment_type: null
                    encrypted_password: null
                    ends_on: null
                    exit_reason: null
                    external_id: null
                    external_oidc_id: null
                    forename: Alice
                    gauth_enabled: false
                    gauth_secret: null
                    gauth_tmp: null
                    gender: Male
                    group_id: null
                    identity_person_id: null
                    kind_id: null
                    kind_type: Employee
                    last_sign_in_at: null
                    line1: 7101 Dapin Place
                    line2: null
                    line3: null
                    member_type: null
                    middle_name: null
                    national_identifier_1: null
                    national_insurance_number: null
                    nationality_code: null
                    onboarded_at: null
                    online_login_disabled: false
                    opt_in_on: null
                    opt_out_on: null
                    opt_out_window_ends_on: null
                    opt_out_window_starts_on: null
                    opt_state: ignition
                    percentage_ownership: null
                    person_id: null
                    postcode: '65551'
                    referral_clicks: 0
                    region: null
                    remember_created_at: null
                    reset_password_sent_at: null
                    reset_password_token: null
                    retirement_age: 65
                    retirement_age_customised: false
                    retirement_date: '2066-08-05'
                    scheme_detail_id: 547
                    scheme_origin: standard
                    secondary_email: null
                    single_use_authentication_token: null
                    single_use_authentication_token_generated_at: null
                    slug: TO7niFvglK
                    starts_on: '2016-08-05'
                    surname: Scott
                    target_retirement_age: null
                    target_retirement_date: null
                    telephone: null
                    temporary_password: temporary_password
                    title: Captain
                    updated_at: '2026-08-05T13:01:49.000+01:00'
                    uuid: 3e08399f-b817-4918-b8fc-fb10803f8b1c
                    visa_number: null
                    works_in_uk: true
              invalid_parameters:
                value:
                  starts_on: '2026-08-05'
                  deferral_on: '2026-08-06'
                  postponement:
                    deferral_on: ''
                  employee:
                    id: 431
                    api_key: api_key
                    authentication_token: null
                    authentication_token_generated_at: null
                    automatically_enrolled: false
                    bank_account_detail_id: null
                    benefit_group_id: null
                    city: Merced
                    civil_status: null
                    company_id: 822
                    company_match: false
                    confirmation_token: null
                    contribute_if_entitled: true
                    country_code: GB
                    created_at: '2026-08-05T13:01:50.000+01:00'
                    customer_id: null
                    date_of_birth: '2001-08-05'
                    date_of_birth_confirmed: false
                    email: employee_519@example.com
                    employee_classification: null
                    employment_type: null
                    encrypted_password: null
                    ends_on: null
                    exit_reason: null
                    external_id: null
                    external_oidc_id: null
                    forename: Judy
                    gauth_enabled: false
                    gauth_secret: null
                    gauth_tmp: null
                    gender: Male
                    group_id: null
                    identity_person_id: null
                    kind_id: null
                    kind_type: Employee
                    last_sign_in_at: null
                    line1: 93762 Crownhardt Lane
                    line2: null
                    line3: null
                    member_type: null
                    middle_name: null
                    national_identifier_1: null
                    national_insurance_number: null
                    nationality_code: null
                    onboarded_at: null
                    online_login_disabled: false
                    opt_in_on: null
                    opt_out_on: null
                    opt_out_window_ends_on: null
                    opt_out_window_starts_on: null
                    opt_state: ignition
                    percentage_ownership: null
                    person_id: null
                    postcode: 33159-7551
                    referral_clicks: 0
                    region: null
                    remember_created_at: null
                    reset_password_sent_at: null
                    reset_password_token: null
                    retirement_age: 65
                    retirement_age_customised: false
                    retirement_date: '2066-08-05'
                    scheme_detail_id: 549
                    scheme_origin: standard
                    secondary_email: null
                    single_use_authentication_token: null
                    single_use_authentication_token_generated_at: null
                    slug: sG0eSFEUZA
                    starts_on: '2016-08-05'
                    surname: Hicks
                    target_retirement_age: null
                    target_retirement_date: null
                    telephone: null
                    temporary_password: temporary_password
                    title: Mx
                    updated_at: '2026-08-05T13:01:50.000+01:00'
                    uuid: 77837459-0bb2-470d-b23c-a7d366a11129
                    visa_number: null
                    works_in_uk: true
              forbidden_with_existing_contribution:
                value:
                  starts_on: '2026-08-05'
                  deferral_on: '2026-08-06'
                  postponement:
                    deferral_on: '2026-08-06'
                  employee:
                    id: 432
                    api_key: api_key
                    authentication_token: null
                    authentication_token_generated_at: null
                    automatically_enrolled: false
                    bank_account_detail_id: null
                    benefit_group_id: null
                    city: Sonoma
                    civil_status: null
                    company_id: 824
                    company_match: false
                    confirmation_token: null
                    contribute_if_entitled: true
                    country_code: GB
                    created_at: '2026-08-05T13:01:50.000+01:00'
                    customer_id: null
                    date_of_birth: '2001-08-05'
                    date_of_birth_confirmed: false
                    email: employee_520@example.com
                    employee_classification: null
                    employment_type: null
                    encrypted_password: null
                    ends_on: null
                    exit_reason: null
                    external_id: null
                    external_oidc_id: null
                    forename: Anne
                    gauth_enabled: false
                    gauth_secret: null
                    gauth_tmp: null
                    gender: Male
                    group_id: null
                    identity_person_id: null
                    kind_id: null
                    kind_type: Employee
                    last_sign_in_at: null
                    line1: 115 Arkansas Plaza
                    line2: null
                    line3: null
                    member_type: null
                    middle_name: null
                    national_identifier_1: null
                    national_insurance_number: null
                    nationality_code: null
                    onboarded_at: null
                    online_login_disabled: false
                    opt_in_on: null
                    opt_out_on: null
                    opt_out_window_ends_on: null
                    opt_out_window_starts_on: null
                    opt_state: ignition
                    percentage_ownership: null
                    person_id: null
                    postcode: '64624'
                    referral_clicks: 0
                    region: null
                    remember_created_at: null
                    reset_password_sent_at: null
                    reset_password_token: null
                    retirement_age: 65
                    retirement_age_customised: false
                    retirement_date: '2066-08-05'
                    scheme_detail_id: 551
                    scheme_origin: standard
                    secondary_email: null
                    single_use_authentication_token: null
                    single_use_authentication_token_generated_at: null
                    slug: wkHS40WRo
                    starts_on: '2016-08-05'
                    surname: Simmons
                    target_retirement_age: null
                    target_retirement_date: null
                    telephone: null
                    temporary_password: temporary_password
                    title: Sir
                    updated_at: '2026-08-05T13:01:50.000+01:00'
                    uuid: 60df9ab2-5913-413f-93f5-2b8f493bc396
                    visa_number: null
                    works_in_uk: true
              not_found:
                value:
                  starts_on: '2026-08-05'
                  deferral_on: '2026-08-06'
                  postponement:
                    deferral_on: '2026-08-06'
                  employee:
                    id: 433
                    api_key: api_key
                    authentication_token: null
                    authentication_token_generated_at: null
                    automatically_enrolled: false
                    bank_account_detail_id: null
                    benefit_group_id: null
                    city: Bell Gardens
                    civil_status: null
                    company_id: 826
                    company_match: false
                    confirmation_token: null
                    contribute_if_entitled: true
                    country_code: GB
                    created_at: '2026-08-05T13:01:51.000+01:00'
                    customer_id: null
                    date_of_birth: '2001-08-05'
                    date_of_birth_confirmed: false
                    email: employee_521@example.com
                    employee_classification: null
                    employment_type: null
                    encrypted_password: null
                    ends_on: null
                    exit_reason: null
                    external_id: null
                    external_oidc_id: null
                    forename: Kathy
                    gauth_enabled: false
                    gauth_secret: null
                    gauth_tmp: null
                    gender: Female
                    group_id: null
                    identity_person_id: null
                    kind_id: null
                    kind_type: Employee
                    last_sign_in_at: null
                    line1: 07319 Buhler Street
                    line2: null
                    line3: null
                    member_type: null
                    middle_name: null
                    national_identifier_1: null
                    national_insurance_number: null
                    nationality_code: null
                    onboarded_at: null
                    online_login_disabled: false
                    opt_in_on: null
                    opt_out_on: null
                    opt_out_window_ends_on: null
                    opt_out_window_starts_on: null
                    opt_state: ignition
                    percentage_ownership: null
                    person_id: null
                    postcode: '57118'
                    referral_clicks: 0
                    region: null
                    remember_created_at: null
                    reset_password_sent_at: null
                    reset_password_token: null
                    retirement_age: 65
                    retirement_age_customised: false
                    retirement_date: '2066-08-05'
                    scheme_detail_id: 553
                    scheme_origin: standard
                    secondary_email: null
                    single_use_authentication_token: null
                    single_use_authentication_token_generated_at: null
                    slug: IJwxQ83rY1lD
                    starts_on: '2016-08-05'
                    surname: Johnston
                    target_retirement_age: null
                    target_retirement_date: null
                    telephone: null
                    temporary_password: temporary_password
                    title: Dr
                    updated_at: '2026-08-05T13:01:51.000+01:00'
                    uuid: 303cfa8f-8ae9-4b70-a134-2ad92834a7c5
                    visa_number: null
                    works_in_uk: true
            schema:
              type: object
              properties:
                deferral_on:
                  type: string
                starts_on:
                  type: string
              required:
              - starts_on
              - deferral_on
      responses:
        '204':
          description: Updates a contribution with gross qualifying earnings
        '403':
          description: Forbidden when the employee already has a contribution
          content:
            application/json:
              example:
                errors:
                - code: 28
                  title: Employee has contributions.
                  detail: Postponement cannot be deleted or updated because there are contribution records for this employee.
                  form: null
                  attribute: base
                  error: postponement_is_frozen
                  meta: {}
                  source:
                    pointer: /base
        '404':
          description: Not Found
          content:
            application/json:
              example: ''
        '422':
          description: Failing with invalid parameters.
          content:
            application/json:
              example:
                errors:
                - code: 1401
                  title: The deferral date is a required field.
                  detail: You need to select a deferral date for the postponement. This can be any date up to 3 months and a day later than either your staging date or the employees start of employment, which ever is the latest.
                  meta: {}
                  source:
                    pointer: /data/attributes/deferral_on
    patch:
      summary: Postponement/Update
      tags:
      - Postponement
      security:
      - oAuth2:
        - user
        - customer
      parameters:
      - name: id
        in: path
        required: true
        example: 13
        schema:
          type: string
      - name: company_id
        in: path
        required: true
        example: 828
        schema:
          type: string
      - name: employee_id
        in: path
        required: true
        example: 434
        schema:
          type: string
      requestBody:
        content:
          application/json:
            examples:
              success:
                value:
                  starts_on: '2026-08-05'
                  deferral_on: '2026-08-06'
                  postponement:
                    deferral_on: '2026-08-06'
                  employee:
                    id: 434
                    api_key: api_key
                    authentication_token: null
                    authentication_token_generated_at: null
                    automatically_enrolled: false
                    bank_account_detail_id: null
                    benefit_group_id: null
                    city: Aliso Viejo
                    civil_status: null
                    company_id: 828
                    company_match: false
                    confirmation_token: null
                    contribute_if_entitled: true
                    country_code: GB
                    created_at: '2026-08-05T13:01:51.000+01:00'
                    customer_id: null
                    date_of_birth: '2001-08-05'
                    date_of_birth_confirmed: false
                    email: employee_522@example.com
                    employee_classification: null
                    employment_type: null
                    encrypted_password: null
                    ends_on: null
                    exit_reason: null
                    external_id: null
                    external_oidc_id: null
                    forename: Eric
                    gauth_enabled: false
                    gauth_secret: null
                    gauth_tmp: null
                    gender: Female
                    group_id: null
                    identity_person_id: null
                    kind_id: null
                    kind_type: Employee
                    last_sign_in_at: null
                    line1: 137 Fair Oaks Road
                    line2: null
                    line3: null
                    member_type: null
                    middle_name: null
                    national_identifier_1: null
                    national_insurance_number: null
                    nationality_code: null
                    onboarded_at: null
                    online_login_disabled: false
                    opt_in_on: null
                    opt_out_on: null
                    opt_out_window_ends_on: null
                    opt_out_window_starts_on: null
                    opt_state: ignition
                    percentage_ownership: null
                    person_id: null
                    postcode: 17418-2688
                    referral_clicks: 0
                    region: null
                    remember_created_at: null
                    reset_password_sent_at: null
                    reset_password_token: null
                    retirement_age: 65
                    retirement_age_customised: false
                    retirement_date: '2066-08-05'
                    scheme_detail_id: 555
                    scheme_origin: standard
                    secondary_email: null
                    single_use_authentication_token: null
                    single_use_authentication_token_generated_at: null
                    slug: KJQAzf8a0D
                    starts_on: '2016-08-05'
                    surname: Garcia
                    target_retirement_age: null
                    target_retirement_date: null
                    telephone: null
                    temporary_password: temporary_password
                    title: Bursar
                    updated_at: '2026-08-05T13:01:51.000+01:00'
                    uuid: 2b9ace5a-ef83-41dd-8f7c-ee21720a0b73
                    visa_number: null
                    works_in_uk: true
              invalid_parameters:
                value:
                  starts_on: '2026-08-05'
                  deferral_on: '2026-08-06'
                  postponement:
                    deferral_on: ''
                  employee:
                    id: 435
                    api_key: api_key
                    authentication_token: null
                    authentication_token_generated_at: null
                    automatically_enrolled: false
                    bank_account_detail_id: null
                    benefit_group_id: null
                    city: Highland
                    civil_status: null
                    company_id: 830
                    company_match: false
                    confirmation_token: null
                    contribute_if_entitled: true
                    country_code: GB
                    created_at: '2026-08-05T13:01:51.000+01:00'
                    customer_id: null
                    date_of_birth: '2001-08-05'
                    date_of_birth_confirmed: false
                    email: employee_523@example.com
                    employee_classification: null
                    employment_type: null
                    encrypted_password: null
                    ends_on: null
                    exit_reason: null
                    external_id: null
                    external_oidc_id: null
                    forename: Sara
                    gauth_enabled: false
                    gauth_secret: null
                    gauth_tmp: null
                    gender: Female
                    group_id: null
                    identity_person_id: null
                    kind_id: null
                    kind_type: Employee
                    last_sign_in_at: null
                    line1: 39 Northland Street
                    line2: null
                    line3: null
                    member_type: null
                    middle_name: null
                    national_identifier_1: null
                    national_insurance_number: null
                    nationality_code: null
                    onboarded_at: null
                    online_login_disabled: false
                    opt_in_on: null
                    opt_out_on: null
                    opt_out_window_ends_on: null
                    opt_out_window_starts_on: null
                    opt_state: ignition
                    percentage_ownership: null
                    person_id: null
                    postcode: 08515
                    referral_clicks: 0
                    region: null
                    remember_created_at: null
                    reset_password_sent_at: null
                    reset_password_token: null
                    retirement_age: 65
                    retirement_age_customised: false
                    retirement_date: '2066-08-05'
                    scheme_detail_id: 557
                    scheme_origin: standard
                    secondary_email: null
                    single_use_authentication_token: null
                    single_use_authentication_token_generated_at: null
                    slug: L2cq74McU
                    starts_on: '2016-08-05'
                    surname: Larson
                    target_retirement_age: null
                    target_retirement_date: null
                    telephone: null
                    temporary_password: temporary_password
                    title: Sir
                    updated_at: '2026-08-05T13:01:51.000+01:00'
                    uuid: 8a54af82-412c-4050-957d-badf75c87ec6
                    visa_number: null
                    works_in_uk: true
              forbidden_with_existing_contribution:
                value:
                  starts_on: '2026-08-05'
                  deferral_on: '2026-08-06'
                  postponement:
                    deferral_on: '2026-08-06'
                  employee:
                    id: 436
                    api_key: api_key
                    authentication_token: null
                    authentication_token_generated_at: null
                    automatically_enrolled: false
                    bank_account_detail_id: null
                    benefit_group_id: null
                    city: Fountain Valley
                    civil_status: null
                    company_id: 832
                    company_match: false
                    confirmation_token: null
                    contribute_if_entitled: true
                    country_code: GB
                    created_at: '2026-08-05T13:01:52.000+01:00'
                    customer_id: null
                    date_of_birth: '2001-08-05'
                    date_of_birth_confirmed: false
                    email: employee_524@example.com
    

# --- truncated at 32 KB (119 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/smart-pension/refs/heads/main/openapi/smart-pension-postponement-api-openapi.yml