openapi: 3.1.0
info:
  version: 4.1.0
  title: Pension
  description: |
    # Pension-API (Deutsch)

    **** Deutsch (for English see below) ****

    Mit dem Pension-API können Daten zur versicherten Person und deren Vorsorgesituation abgefragt werden. Dies umfasst vereinfacht gesagt
    die Daten, die auf dem Versicherungsausweis zu finden sind. Auch die Erstellung bzw. das Beziehen von bereits erstellten
    Versicherungsausweisen als PDF-Datei ist möglich. Des Weiteren gibt es Endpunkte für Simulationen und für Transaktionen.

    Als Einstieg fürs Pension-API wird eine technische Personen-, Statement- oder Policen-ID benötigt.

    Die wesentlichen Objekte dieses APIs sind *Person*, *Police* und *Pension Statement*. Person bezieht sich immer auf eine natürliche
    Person, die bei einer Pensionskasse versichert ist.

    Die Police beschreibt den indirekten Versicherungsvertrag zwischen der versicherten Person (ArbeitnehmerIn) und der Pensionskasse. Ist
    eine Person über zwei Vorsorgepläne versichert, z.B. über einen Basis- und einen zusätzlichen Kaderplan, so hat sie zwei Policen.

    Das Pension Statement umfasst grundsätzlich die gleichen persönlichen Vorsorgedaten wie die Policen, kann aber die Daten verschiedener
    Policen aggregieren. Je nach Pensionkasse wird dies unterschiedlich gehandhabt.

    Die PDF-Version des Vorsorgeausweises entspricht dem Dokument, welches traditionell anfangs Jahr durch die Pensionskasse für die
    Versicherten ausgestellt wird.

    Das API umfasst auch Simulationen:
    - Änderung des Beschäftigtengrads und/oder des Lohns
    - Freiwilliger Einkauf in die Pensionskasse
    Die Simulationen berechnen die Effekte auf die monatlichen Beiträge sowie auf die voraussichtlichen Rentenleistungen bei
    unterschiedlichem Pensionierungsalter.

    Die in dieser Spezifikation angegebenen URLs sind nur Beispiel-URLs. Das API wird von einer Vielzahl von Pensionskassen implementiert
    und jede Pensionskasse hat eine andere Basis-URL für das API. Die Basis-URL der jeweiligen Pensionskasse wird vom Directory API
    geliefert.

    ## Lokalisierung und Währungshinweise

    Die Sprache der API-Responses kann nicht über die API beeinflusst werden. Sie richtet sich nach den Spracheinstellungen,
    die beim jeweiligen Service Provider für die versicherte Person hinterlegt sind (in der Regel Deutsch, Französisch oder Italienisch).

    Alle monetären Werte (z. B. Guthaben, Beiträge, Leistungen) sind in **Schweizer Franken (CHF)** angegeben.

    ## Simulation

    Die Simulation berechnet, wie hoch das Altersguthaben und die Rente mit und ohne Einkauf sein wird. Dabei können verschiedene Parameter
    gewählt werden:
    - Einkaufssumme (gesamt)
    - Pensionierungsalter
    - Betrag pro Zahlung (bei mehreren Zahlungen)
    - Zahlungsperiodizität (bei mehreren Zahlungen)
    - Datum der (ersten) Zahlung

    Die Simulation geht davon aus, dass die gesetzlichen Voraussetzungen für den Einkauf gegeben sind. Sie prüft, dass der maximale
    Einkaufsbetrag nicht überschritten wird, und passt ihn bei Bedarf an.

    ## Kontobewegung

    Das Kontobewegungsendpunkte liefert die Kontobewegungen des Altersguthabens einer Police.

    # Pension API (English)

    **** English (für Deutsch siehe weiter oben) ****

    The Pension API serves to query details about the insured person and their pension situation. In simplified terms, this includes the
    data found on the insurance certificate. Additionally, policy statements can be generated or already generated statements can be
    retrieved as PDF files. There are also endpoints for simulations and for transactions.

    Person, statement and policy IDs serve as the entry point for this API.

    The main objects of this API are *Person*, *Policy* and *Pension Statement*. Person always refers to a natural person who is insured
    with a pension fund.

    The policy describes the indirect insurance contract between the insured person (employee) and the pension fund. If a person is insured
    under two pension plans, e.g. via a basic plan and an additional management plan, he or she has two policies.

    The pension statement basically contains the same personal pension data as the policies, but can aggregate the data from different
    policies. This is handled differently depending on the pension fund.

    The PDF version of the pension certificate corresponds to the document that is traditionally issued to the insured persons by the
    pension fund at the beginning of the year.

    The API also includes simulations:
    - Change of employment level and/or salary
    - Voluntary purchase into the pension fund
    The simulations calculate the effects on the monthly contributions as well as the effects of the perspective pension benefits for
    different retirement ages.

    The URLs in the specification are examples only. The API is implemented by a many pension funds and each pension fund has an individual
    base URL for the API. The base URL of a specific pension fund is provided by the directory API.

    ## Localization and Currency Notes

    The response language cannot be influenced via the API. It is determined by the language setting stored by the service provider for
    the insured person (typically German, French, or Italian).

    All monetary values (e.g., balances, contributions, benefits) are expressed in **Swiss Francs (CHF)**.

    ## Simulation

    The simulation calculates the prospective retirement capital and pension with and without voluntary purchase. Several parameters of the
    simulation can be specified:
    - Purchase amount (total)
    - Pension age
    - Amount of individual payments (if several payments are made towards a purchase)
    - Payment frequency (if several payments are made towards a purchase)
    - Date of (first) payment

    The simulation assumes that the legal prerequisites for the purchase are fulfilled. It checks that the maximum purchase amount is not
    exceeded and modifies it if needed.

    ## Transactions
    The Transactions endpoints provide the transactions affecting the retirement capital of a policy.

    ### Glossar / Glossary
    Folgende englischen Begriffe werden im API verwendet / The following English terms are used in the API :
    - **Social Security Number (SSN)**: Sozialversicherungsnummer (SVN) - 13 stellige, Schweizer Sozialversicherungsnummer.
    - **Mandatory / supplementary coverage**: Obligatorischer / überobligatorische Anteil / Deckung
    - **Retirement benefits**: Versicherungsleistungen bei Pensionierung (Altersrente und Altersguthaben)
    - **Risk benefits**: Versicherungsleistungen bei Invalidität und Tod
    - **Enveloping interest/conversion rate**: Umhüllender Zinssatz / Umwandlungssatz
    - **Retirement capital**: Altersguthaben / Alterskapital
    - **Savings contribution**: Sparbeitrag (Beitrag an Altersgutben)
    - **Risk contribution**: Risikobeitrag (Beitrag für Leistungen bei Invalidität und Tod)
    - **Vested benefits**: Freizügigkeitsleistungen
  contact:
    email: info@common-api.ch
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://pension.common-api.ch
externalDocs:
  description: Find out more about SFTI API specifications.
  url: https://www.common-api.ch
tags:
  - name: person
    description: Insured person.
  - name: statement
    description: Pension statement.
  - name: policy
    description: Pension fund policy.
  - name: plan
    description: Pension plan.
  - name: simulation
    description: Simulations of salary changes and voluntary purchases.
  - name: transactions
    description: Retirement capital transactions.
security:
  - OAuth2:
      - read:basic_pension_data
paths:
  /insured-persons:
    get:
      summary: Retrieve a list of insured persons that are accessible with the presented access token
      description: |
        Returns the list of person identifier(s) (`personId`) that the authenticated user can access via the API.

        A valid OAuth2 access token, obtained through a user consent flow, is required. No specific scope is enforced
        for this endpoint, but the presence of a valid consent is mandatory.

        The returned list acts as a mapping between the authenticated user (represented by the access token) and the
        insured persons that are technically accessible through this API. The service provider MUST ensure that
        only those person IDs are returned which are both:

        1. authorized for the user in the provider’s system, AND
        2. explicitly permitted for API access under the user’s current consent.

        This prevents exposing additional person IDs that the user might be entitled to in the backend but which are
        not covered by the API consent agreement.

        In most cases, only a single `personId` will be returned. Multiple person IDs MAY be returned if the user is
        authorized and has consented to access data for more than one insured person. If no accessible persons remain
        under the current consent, the endpoint returns an empty list.
      operationId: retrieveInsuredPersons
      tags:
        - person
      security:
        - OAuth2: []
      responses:
        '200':
          description: A list of insured persons.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: Person ID of the insured person(s).
                  required:
                    - personId
                  properties:
                    personId:
                      $ref: '#/components/schemas/PersonId'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '404':
          $ref: '#/components/responses/standard404'
        '500':
          $ref: '#/components/responses/standard500'
  /insured-persons/{personId}:
    get:
      summary: Get details of an insured person
      description: |
        Provides the details of the insured person, including name, address and additional data relevant in the Swiss social security system
        (birth date, sex etc.)
      operationId: getInsuredPerson
      tags:
        - person
      parameters:
        - $ref: '#/components/parameters/person_id'
      security:
        - OAuth2:
            - read:basic_pension_data
      responses:
        '200':
          description: Details of insured person.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsuredPerson'
        '401':
          $ref: '#/components/responses/standard401'
        '404':
          $ref: '#/components/responses/standard404'
        '500':
          $ref: '#/components/responses/standard500'
  /insured-persons/{personId}/statements:
    get:
      summary: Get pension statement(s) data
      description: |
        Provides the pension statement(s) representing the state of the policy/policies for the specified date as structured data. If no
        date is specified, the latest (regular/official) pension statement(s) associated with the insured person is retrieved. If a person
        has several policies (associated to different pension plans), either an aggregated statement is delivered or one statement per
        pension plan. This can vary depending on the pension fund. In the aggregated statement, the related pension plans are listed.

        If the pension fund is unable to provide a statement for the request date, the error code 400 should be returned.
      operationId: getPensionStatementsByDate
      tags:
        - statement
      parameters:
        - $ref: '#/components/parameters/person_id'
        - $ref: '#/components/parameters/reference_date'
      security:
        - OAuth2:
            - read:basic_pension_data
      responses:
        '200':
          description: Statement details.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PensionStatement'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '404':
          $ref: '#/components/responses/standard404'
        '500':
          $ref: '#/components/responses/standard500'
  /statements/{pensionStatementId}/documents:
    get:
      summary: Get the pension statement document for the specified id
      description: |
        Provides the pension statement for the specified id as a PDF document in the insured person's preferred language.
        If the pension fund is unable to provide a document for the request id, the error code 400 should be returned.
      operationId: getPensionStatementDocument
      tags:
        - statement
      parameters:
        - $ref: '#/components/parameters/pension_statement_id'
      security:
        - OAuth2:
            - read:basic_pension_data
      responses:
        '200':
          description: Binary PDF data of the pension statement.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/standard401'
        '404':
          $ref: '#/components/responses/standard404'
        '500':
          $ref: '#/components/responses/standard500'
  /statements/{pensionStatementId}/compact-statements:
    get:
      summary: Get the compact pension statement for the specified id
      description: |
        Provides the pension statement for the specified id as a compact json in the insured person's preferred language. Its sole purpose
        is to provide a compact json for use cases with tight data volume limits such as e.g. a QR code. This endpoint should not be used
        otherwise.

        If the pension fund is unable to provide a json for the request id, the error code 400 should be returned.
      operationId: getPensionStatementCompact
      tags:
        - statement
      parameters:
        - $ref: '#/components/parameters/pension_statement_id'
      security:
        - OAuth2:
            - read:basic_pension_data
      responses:
        '200':
          description: Compact statement details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Psc'
        '401':
          $ref: '#/components/responses/standard401'
        '404':
          $ref: '#/components/responses/standard404'
        '500':
          $ref: '#/components/responses/standard500'
  /statements/{pensionStatementId}/compact-vb-statements:
    get:
      summary: Get the compact vested benefits statement for the specified id
      description: |
        Provides the vested benefits statement for the specified id as a compact json in the insured person's preferred language. Its sole
        purpose is to provide a compact json for use cases with tight data volume limits such as e.g. a QR code. This endpoint should not
        be used otherwise.

        If the pension fund is unable to provide a json for the request id, the error code 400 should be returned.
      operationId: getVestedBenefitStatementCompact
      tags:
        - statement
      parameters:
        - $ref: '#/components/parameters/pension_statement_id'
      security:
        - OAuth2:
            - read:basic_pension_data
      responses:
        '200':
          description: Compact vested benefits statement details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PscVb'
        '401':
          $ref: '#/components/responses/standard401'
        '404':
          $ref: '#/components/responses/standard404'
        '500':
          $ref: '#/components/responses/standard500'
  /statements/{pensionStatementId}/compact-3a-statements:
    get:
      summary: Get the compact 3a statement for the specified id
      description: |
        Provides the 3a statement for the specified id as a compact json in the insured person's preferred language. Its sole
        purpose is to provide a compact json for use cases with tight data volume limits such as e.g. a QR code. This endpoint should not
        be used otherwise.

        If the pension fund is unable to provide a json for the request id, the error code 400 should be returned.
      operationId: get3aStatementCompact
      tags:
        - statement
      parameters:
        - $ref: '#/components/parameters/pension_statement_id'
      security:
        - OAuth2:
            - read:basic_pension_data
      responses:
        '200':
          description: Compact 3a statement details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Psc3A'
        '401':
          $ref: '#/components/responses/standard401'
        '404':
          $ref: '#/components/responses/standard404'
        '500':
          $ref: '#/components/responses/standard500'
  /policies/{policyId}:
    get:
      summary: Get details of a pension fund policy
      description: |
        Provides details about the insurance policy including current retirement capital, prospective pension benefits for different
        retirement ages, contributions to financing the insurance etc.
      operationId: getPolicy
      tags:
        - policy
      parameters:
        - $ref: '#/components/parameters/policy_id'
      security:
        - OAuth2:
            - read:basic_pension_data
      responses:
        '200':
          description: Policy details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '401':
          $ref: '#/components/responses/standard401'
        '404':
          $ref: '#/components/responses/standard404'
        '500':
          $ref: '#/components/responses/standard500'
  /plans/{planId}/description-documents:
    get:
      summary: Get insured person's pension plan description
      description: |
        Retrieves the pension plan description for a specific insured person and pension plan.

        This document provides a description of the insured person's pension plan, including covered benefits, contribution structure, and
        key conditions applicable under their employer's pension scheme.

        If the specified pension plan description is not found for the insured person, a `404` error is returned.
      operationId: getPensionPlanDescriptionDocument
      tags:
        - plan
      parameters:
        - $ref: '#/components/parameters/plan_id'
      security:
        - OAuth2:
            - read:pension_plan
      responses:
        '200':
          description: Pension plan description document for the insured person in PDF format.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/standard401'
        '404':
          $ref: '#/components/responses/standard404'
        '500':
          $ref: '#/components/responses/standard500'
  /policies/{policyId}/salary-change-simulation:
    post:
      summary: Simulate effects of salary and employment level change
      description: Simulates the effects of a salary and/or employment level change on personal pension details (e.g. retirement capital).
      operationId: simulateSalaryChange
      tags:
        - simulation
      parameters:
        - $ref: '#/components/parameters/policy_id'
      security:
        - OAuth2:
            - read:basic_pension_data
      requestBody:
        description: Salary change simulation parameters.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SalaryChangeSimParameters'
      responses:
        '200':
          description: Simulation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationResultPensionStatement'
        '401':
          $ref: '#/components/responses/standard401'
        '404':
          $ref: '#/components/responses/standard404'
        '500':
          $ref: '#/components/responses/standard500'
  /policies/{policyId}/purchase-simulation:
    post:
      summary: Simulate effects of voluntary purchase
      description: |
        Simulates the financial effect of voluntary purchase of additional pension benefits for the provided parameters (retirement age,
        purchase amount etc.)

        If the specified purchase amount is higher the maximum allowed purchase amount, it will be reduced to the allowed amount. The
        simulation result contains the effective purchase amount.

        For periodic payments, the simulation assumes that the payments are made with the specified payment size and payment frequency until
        the maximum purchase amount has been exhausted or the retirement date has been reached (whichever is first).

        If the retirement date is reached before the purchase amount is exhausted, the returned effective purchase amount will be lower than
        both the requested and the maximum purchase amount.

        Using a very high amount (e.g. CHF 10 million), it is possible to query the maximum purchase amount and the maximum additional
        pension at once.
      operationId: simulatePurchase
      tags:
        - simulation
      parameters:
        - $ref: '#/components/parameters/policy_id'
      security:
        - OAuth2:
            - read:basic_pension_data
      requestBody:
        description: Voluntary purchase simulation parameters.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseSimParameters'
      responses:
        '200':
          description: Simulation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationResultPensionStatement'
        '401':
          $ref: '#/components/responses/standard401'
        '404':
          $ref: '#/components/responses/standard404'
        '500':
          $ref: '#/components/responses/standard500'
  /policies/{policyId}/transactions:
    get:
      summary: Get the retirement capital transactions
      description: |
        Retrieves all transactions affecting the policy's retirement capital in the specified date range.

        The resulting transaction list is sorted in chronological order, starting with the oldest transaction. If several transactions
        occurred on the same date, they are ordered such that adding the transaction amount to the previous transactions balance results in
        the balance provided by the current transaction.

        The first transaction in the list is a pseudo transaction providing the carryover balance from the previous period. It is the only
        transaction with the category `carryover`.

        The `from` date must be before or be equal to the `to` date.

        The result contains a date range as well. It is usually equal to the request date range. However, if the requested `from` date is
        before the start of the policy or if the request `to` date is in the future, the date range may be adjusted to reflect the effective
        date range.
      operationId: getRetirementCapitalTransactions
      tags:
        - transactions
      parameters:
        - $ref: '#/components/parameters/policy_id'
        - $ref: '#/components/parameters/from_date'
        - $ref: '#/components/parameters/to_date'
      security:
        - OAuth2:
            - read:basic_pension_data
      responses:
        '200':
          description: Retirement capital transactions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transactions'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '404':
          $ref: '#/components/responses/standard404'
        '500':
          $ref: '#/components/responses/standard500'
components:
  schemas:
    AdditionalSalary:
      description: Additional salary component.
      type: number
      format: double
      examples:
        - 0
    Address:
      description: Postal/residence address.
      type: object
      required:
        - countryCode
        - postalCode
        - street
        - town
      properties:
        countryCode:
          $ref: '#/components/schemas/CountryCode'
        postalCode:
          $ref: '#/components/schemas/PostalCode'
        street:
          $ref: '#/components/schemas/Street'
        town:
          $ref: '#/components/schemas/Town'
        poBox:
          $ref: '#/components/schemas/PoBox'
    BalanceEndCurrentYear:
      description: Projected retirement capital as per end of the current year (mandatory and supplementary coverage).
      type: number
      format: double
      examples:
        - 56325.25
    BalanceMandatoryEndCurrentYear:
      description: Projected retirement capital under mandatory coverage as per end of the current year.
      type: number
      format: double
      examples:
        - 40846.6
    BalanceMandatoryReferenceDate:
      description: Retirement capital under mandatory coverage as per a specified reference date.
      type: number
      format: double
      examples:
        - 38942.15
    BalanceReferenceDate:
      description: Retirement capital as per a specified reference date (mandatory and supplementary coverage).
      type: number
      format: double
      examples:
        - 53842.5
    BirthYearMonth:
      description: Year and month of birth (Format YYYY-MM).
      type: string
      pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$
      examples:
        - 1985-05
    Bonus:
      description: Bonus component of the salary.
      type: number
      format: double
      examples:
        - 0
    CapitalBalance:
      description: Retirement capital balance with interest (mandatory and supplementary coverage).
      type: number
      format: double
      examples:
        - 378832.05
    CapitalBalanceMandatory:
      description: Retirement capital balance with interest (mandatory coverage only).
      type: number
      format: double
      examples:
        - 284832.15
    CapitalBalanceNoInterest:
      description: Retirement capital balance assuming no interest on assets (mandatory and supplementary coverage).
      type: number
      format: double
      examples:
        - 331285.25
    CapitalBalanceNoInterestMandatory:
      description: Retirement capital balance assuming no interest on assets (mandatory coverage only).
      type: number
      format: double
      examples:
        - 248862.65
    CapitalDevelopment:
      description: Shared capital development fields.
      type: object
      properties:
        cg:
          type: number
          format: double
          description: Total capital gains (positive) or losses (negative) from investments for the period.
          examples:
            - 1000
        de:
          type: number
          format: double
          description: Total deposits or inflows for the period.
          examples:
            - 5000
        fe:
          type: number
          format: double
          description: Total management or administrative fees for the period. Debits must be provided as a negative value.
          examples:
            - -100
        ic:
          type: number
          format: double
          description: Total interest credits for the period.
          examples:
            - 2000
        wi:
          type: number
          format: double
          description: Total withdrawals or outflows for the period, e.g. for home ownership (WEF) or divorce settlements. Debits must be provided as a negative value.
          examples:
            - -1000
    CapitalTransaction:
      description: |
        Capital transaction made by the insured persons. It includes volunatry purchases, withdrawals for and refunds of home ownerhsip promotion,
        withdrawals or refunds due to divorce.
      type: object
      required:
        - amount
        - date
      properties:
        amount:
          type: number
          format: double
          description: |
            Total transaction amount for mandatory and supplementary part. The amount is positive for payments towards the capital, and negative
            for withdrawals.
          examples:
            - 0
        date:
          description: Date of transaction.
          type: string
          format: date
          examples:
            - '2018-04-13'
        amountMandatory:
          type: number
          format: double
          description: |
            Transaction amount for mandatory part only. The amount is positive for payments towards the capital, and negative for withdrawals.
          examples:
            - 0
    ChildPensionDisability:
      description: Annual child pension in case of disability.
      type: number
      format: double
      examples:
        - 5382
    CommonErrorResponse:
      title: Common Error Response
      description: Common Error Response.
      type: object
      properties:
        detail:
          type: string
          description: Details about the error.
          examples:
            - Detailed problem description with respect to the current request, e.g., invalid account number format
        instance:
          type: string
          description: Instance of the error.
          examples:
            - path/to/corresponding/resource
        title:
          type: string
          description: The error title.
          examples:
            - This is the general problem description
        type:
          $ref: '#/components/schemas/CommonErrorType'
    CommonErrorType:
      title: Common Error Type
      description: Error Types for commonErrorResponse.
      type: string
      enum:
        - /problems/INVALID_PAYLOAD
        - /problems/MALFORMED_PAYLOAD
        - /problems/INVALID_TOKEN
        - /problems/EXPIRED_TOKEN
        - /problems/INSUFFICIENT_PRIVILEGES
        - /problems/NO_ACCESS_TO_RESOURCE
        - /problems/RESOURCE_DOES_NOT_EXIST
        - /problems/RESOURCE_NOT_READY
        - /problems/RESOURCE_TOO_LARGE
        - /problems/WRONG_METHOD
        - /problems/OPERATION_NOT_ALLOWED
        - /problems/TECHNICAL_ERROR
        - /problems/NOT_IMPLEMENTED
        - /problems/SERVICE_UNAVAILABLE
      examples:
        - /problems/TECHNICAL_ERROR
    ContractType:
      description: |
        The contract type of the pension plan, represented by a string identifier.
        Allowed values are:
        - `mand`: Mandatory BVG contract.
        - `suppl`: Supplementary pension plan.
        - `earlyRet`: Plan for early retirement.
        - `bridge`: Bridge pension plan.
        - `1e`: 1e pension plan.
        - `other`: Other contract type not covered by the predefined categories.
      type: string
      enum:
        - mand
        - suppl
        - earlyRet
        - bridge
        - 1e
        - other
      examples:
        - mand
    ContributionAdministrationEmployer:
      description: Annual contribution towards fund administration financed by the employer.
      type: number
      format: double
      examples:
        - 0
    ContributionAdministrationInsuredPerson:
      description: Annual contribution towards fund administration financed by the insured person.
      type: number
      format: double
      examples:
        - 0
    ContributionRiskEmployer:
      description: Annual contribution towards risk benefits financed by the employer.
      type: number
      format: double
      examples:
        - 0
    ContributionRiskInsuredPerson:
      description: Annual contribution towards risk benefits financed by the insured person.
      type: number
      format: double
      examples:
        - 0
    ContributionSavingsEmployer:
      description: Annual contribution towards the retirement captial financed by the employer.
      type: number
      format: double
      examples:
        - 4025
    ContributionSavingsInsuredPerson:
      description: Annual contribution towards the retirement captial financed by the insured person.
      type: number
      format: double
      examples:
        - 4025
    ConversionRateEnveloping:
      description: Enveloping conversion rate (capital to pension) for combined mandatory and supplementary coverage.
      type: number
      format: double
      examples:
        - 6.3
    ConversionRateMandatory:
      description: Conversion rate (capital to pension) for mandatory coverage.
      type: number
      format: double
      examples:
        - 6.8
    ConversionRateSupplementary:
      description: Conversion rate (capital to pension) for supplementary coverage.
      type: number
      format: double
      examples:
        - 5.5
    CountryCode:
      description: ISO country code.
      type: string
      pattern: ^[A-Z]{2}$
      examples:
        - CH
    Date:
      description: Common date format.
      type: string
      format: date
      examples:
        - '2018-04-13'
    DeclaredSalary:
      description: Gross annual salary.
      type: number
      format: double
      examples:
        - 78000
    Employer:
      description: Details of the insured person's employer.
      type: object
      required:
        - employerName
      properties:
        employerName:
          $ref: '#/components/schemas/EmployerName'
        employerId:
          $ref: '#/components/schemas/EmployerId'
        industry:
          $ref: '#/components/schemas/Industry'
    EmployerId:
      description: Swiss Enterprise Identification Number UID.
      type: string
      examples:
        - CHE115873291
    EmployerInternalId:
      description: Pension system internal identifier of the employer that must not be publicly known. Distinct from the Swiss Enterprise Identification Number UID.
      type: string
      examples:
        - EMP_4711
    EmployerName:
      description: The name of the employer.
      type: string
      examples:
        - Acrea AG
    EmploymentLevel:
      description: Level of full-time/part-time employment (in percent, 100 for full-time employment).
      type: number
      format: double
      examples:
        - 100
    Financing:
      description: Contributions for financing the policy.
      type: object
      required:
        - contributionSavingsEmployer
        - contributionSavingsInsuredPerson
      properties:
        contributionSavingsEmployer:
          $ref: '#/components/schemas/ContributionSavingsEmployer'
        contributionSavingsInsuredPerson:
          $ref: '#/components/schemas/ContributionSavingsInsuredPerson'
        contributionAdministrationEmployer:
          $ref: '#/components/schemas/ContributionAdministrationEmployer'
        contributionAdministrationInsuredPerson:
          $ref: '#/components/schemas/ContributionAdministrationInsuredPerson'
        contributionRiskEmployer:
          $ref: '#/components/schemas/ContributionRiskEmployer'
        contributionRiskInsuredPerson:
          $ref: '#/components/schemas/ContributionRiskInsuredPerson'
    HomeOwnershipAvailableForPledge:
      description: |
        The total amount available for the insured person to pledge as collateral from their retirement capital for the purpose of financing home
        ownership.
        After age 50, this amount is subject to legal limitations, which are already reflected in the stated value.

        Note: If a fixed amount is contractually defined, it is usually lower than this value.
      type: number
      format: double
      examples:
        - 50000
    HomeOwnershipAvailableForWithdrawal:
      description: |
        The total amount available for the insured person to withdraw from their retirement capital for the purpose of financing home ownership.
        After age 50, this amount is subject to legal limitations, which are already reflected in the stated value.
      type: number
      format: double
      examples:
        - 31000
    Industry:
      description: The industry or sector the employer operates in.
      type: string
      examples:
        - information technology and management consulting
    InsuredPerson:
      description: Details of insured person.
      type: object
      required:
        - birthDate
        - firstName
        - lastName
        - maritalStatus
        - personId
        - policyIds
        - sex
        - ssn
      properties:
        birthDate:
          description: Birth date.
          type: string
          format: date
          examples:
            - '2018-04-13'
        firstName:
          type: string
          description: First name(s).
          examples:
            - John
        lastName:
          type: string
          description: Last name / family name.
          examples:
            - Doe
        maritalStatus:
          $ref: '#/components/schemas/MaritalStatus'
        personId:
          $ref: '#/components/schemas/PersonId'
        policyIds:
          type: array
          items:
            $ref: '#/components/schemas/PolicyId'
          description: List of IDs of policies that insured person has with this pension fund.
        sex:
          $ref: '#/components/schemas/Sex'
        ssn:
          type: integer
          format: int64
          description: Social security number.
          examples:
            - 7561234567890
        address:
          $ref: '#/components/schemas/Address'
        marriageDate:
          description: Date of marriage (or registration of partnership). Required if `maritalStatus` is `married`.
          type: string
          format: date
          examples:
            - '2018-04-13'
    InsuredSalaryMandatory:
      description: Annual salary insured under mandatory coverage.
      type: number
      format: double
      examples:
        - 59215
    InsuredSalaryRetirement:
      description: Annual salary insured for retirement benefits (mandatory and supplementary coverage).
      type: number
      format: double
      examples:
        - 59215
    InsuredSalaryRisk:
      description: Annual salary insured for risk benefits (mandatory and supplementary coverage).
      type: number
      format: double
      examples:
        - 59215
    InterestRate:
      description: Common interest rate object.
      type: number
      format: double
      examples:
        - 3.175
    InterestRates:
      description: |
        A set of interest rates applicable/applied to the retirement capital, including actual rates for mandatory and supplementary coverage.
        Rates for saving/purchase and projection rates for future value calculations.
      type: object
      properties:
        interestRateEnvelopingProjection:
          $ref: '#/components/schemas/InterestRate'
          description: |
            Projection enveloping interest rate for combined mandatory and supplementary coverage (in percent), used specifically for calculating
            projected future values.
          examples:
            - 6.3
        interestRateEnvelopingPurchase:
          $ref: '#/components/schemas/InterestRate'
          description: |
            Enveloping interest rate for combined mandatory and supplementary coverage (in percent), used specifically in purchase calculations.
          examples:
            - 6.3
        interestRateEnvelopingSaving:
          $ref: '#/components/schemas/InterestRate'
          description: Saving enveloping interest rate for combined mandatory and supplementary coverage (in percent).
          examples:
            - 6.3
        interestRateMandatoryProjection:
          $ref: '#/components/schemas/InterestRate'
          description: Projection rate for mandatory coverage (in percent), used specifically for calculating projected future values.
          examples:
            - 6.8
        interestRateMandatoryPurchase:
          $ref: '#/components/schemas/InterestRate'
          description: Interest rate for mandatory coverage (in percent), used specifically in purchase calculations.
          examples:
            - 6.8
        interestRateMandatorySaving:
          $ref: '#/components/schemas/InterestRate'
          description: Saving interest rate for mandatory coverage (in percent).
          examples:
            - 6.8
        interestRateSupplementaryProjection:
          $ref: '#/components/schemas/InterestRate'
          description: Projection rate for supplementary coverage (in percent), used specifically for calculating projected future values.
          examples:
            - 5.5
        interestRateSupplementaryPurchase:
          $ref: '#/components/schemas/InterestRate'
          description: Interest rate for supplementary coverage (in percent), used specifically in purchase calculations.
          examples:
            - 5.5
        interestRateSupplementarySaving:
          $ref: '#/components/schemas/InterestRate'
          description: Saving interest rate for supplementary coverage (in percent).
          examples:
            - 5.5
      minProperties: 1
      additionalProperties: false
    LanguageCode:
      description: |
        Language code according to ISO 639-1. Examples: `de` (German), `fr` (French), `it` (Italian), `en` (English).
        Used to indicate the language of content based on the insured person's profile.
      type: string
      examples:
        - de
        - fr
        - it
        - en
    LastYearDevelopment:
      description: |
        Details about the capital development for the last year.

        In most cases, all fields should be populated with actual values reflecting the previous calendar year.
        However, if the insured person joined during the current year, some or all of the fields
        may be missing due to the absence of a full year of history.

        Consumers of this data should account for potentially missing values in such cases.
      type: object
      properties:
        balanceBeginningLastYear:
          type: number
          format: double
          description: The capital balance at the beginning of the last year.
          examples:
            - 100000
        balanceEndLastYear:
          type: number
          format: double
          description: The capital balance at the end of the last year.
          examples:
            - 106000
        interestCreditLastYear:
          type: number
          format: double
          description: Interest credits added during the last year.
          examples:
            - 2000
        interestRatesLastYear:
          $ref: '#/components/schemas/InterestRates'
        oldAgeCreditLastYear:
          type: number
          format: double
          description: Old age credits added during the last year.
          examples:
            - 4000
        totalDepositsLastYear:
          type: number
          format: double
          description: Total deposits made during the last year.
          examples:
            - 5000
        totalWithdrawalsLastYear:
          type: number
          format: double
          description: Total withdrawals made during the last year.
          examples:
            - 5000
    LumpSumWithoutPensionBenefits:
      description: |
        A one-off lump sum payment in the event of death, provided no other recurring survivor benefits are paid. This applies when there is no
        entitlement to a partner's pension, orphan's pension, or any other ongoing survivor benefits. The amount typically corresponds to the
        insured person's accrued retirement savings as defined by the pension plan.
      type: number
      format: double
      examples:
        - 92834
    MaritalStatus:
      description: |
        Marital status:
        * `single`: single
        * `married`: married
        * `divorced`: divorced
        * `widowed`: widowed
        * `registeredPartnership`: living in a registered partnership
        * `dissolvedRegisteredPartnership`: registered partnership has been dissolved
        * `unknown`: marital status is not known
      type: string
      enum:
        - single
        - married
        - divorced
        - widowed
        - registeredPartnership
        - dissolvedRegisteredPartnership
        - unknown
      examples:
        - married
    MinimalLumpSumWithPensionBenefits:
      description: |
        A guaranteed minimum one-off lump sum payment in the event of death, which is paid in addition to other pension benefits (e.g., a
        partner’s pension, orphan’s pension, or other recurring survivor benefits).

        This amount can include:
        - Voluntary additional contributions (Einkäufe) made by the insured person.
        - Other supplementary pension capital as defined by the pension plan regulations.

        For example, in some cases, the full accrued retirement savings may be paid in addition to ongoing pension benefits.

        The exact composition and amount of this lump sum depend on the pension plan's rules and the insured person's specific situation.
      type: number
      format: double
      examples:
        - 74383
    OrdinaryRetirementAge:
      description: Age (in month since birth) for ordinary retirement.
      type: integer
      format: int32
      examples:
        - 780
    OrphanPensionDeath:
      description: Annual orphan pension in case of death.
      type: number
      format: double
      examples:
        - 5382
    OtherSalaryComponent:
      description: Other salary component.
      type: number
      format: double
      examples:
        - 0
    PartnerPensionDeath:
      description: Annual partner pension in case of death.
      type: number
      format: double
      examples:
        - 24817
    PaymentFrequency:
      description: |
        Number of payments per year.
        Possible values:
        * 0: One-time payment
        * 1: Annual payment
        * 2: Semi-annual payment
        * 4: Quarterly payment
        * 12: Monthly payment
      type: integer
      examples:
        - 0
    Pension:
      description: Annual pension credit.
      type: number
      format: double
      examples:
        - 22835
    PensionDisability:
      description: Annual pension in case of disability.
      type: number
      format: double
      examples:
        - 40213
    PensionPlan:
      description: |
        The pension plan defines various conditions for the occupational pension provision of the insured employees, incl. the contributions and
        insured benefits.
      type: object
      required:
        - contractType
        - planName
      properties:
        contractType:
          $ref: '#/components/schemas/ContractType'
        planName:
          $ref: '#/components/schemas/PlanName'
        optionalSavingsPlanName:
          type: string
          description: Name of the optional savings plan.
          examples:
            - Sparplan 2
        planId:
          $ref: '#/components/schemas/PlanId'
    PensionProvider:
      description: Pension provider (foundation) administering the policy.
      type: object
      required:
        - providerName
      properties:
        providerName:
          $ref: '#/components/schemas/ProviderName'
        portalName:
          $ref: '#/components/schemas/PortalName'
        portalUrl:
          $ref: '#/components/schemas/PortalUrl'
        providerAddress:
          $ref: '#/components/schemas/Address'
          description: Postal address of the pension provider.
        providerId:
          $ref: '#/components/schemas/ProviderId'
    PensionStatement:
      description: |
        Pension statement consisting of the basic pension statement information, including aggregated personal pension data across related
        policies.
      type: object
      required:
        - employer
        - pensionPlans
        - pensionProvider
        - pensionStatementType
        - personId
        - personalPensionDetails
        - referenceDate
        - timeStamp
      properties:
        employer:
          $ref: '#/components/schemas/Employer'
        pensionPlans:
          type: array
          description: List of related pension plans.
          items:
            $ref: '#/components/schemas/PensionPlan'
        pensionProvider:
          $ref: '#/components/schemas/PensionProvider'
        pensionStatementType:
          $ref: '#/components/schemas/PensionStatementType'
        personId:
          $ref: '#/components/schemas/PersonId'
        personalPensionDetails:
          $ref: '#/components/schemas/PersonalPensionDetails'
        referenceDate:
          description: Reference date of pension statement.
          type: string
          format: date
          examples:
            - '2018-04-13'
        timeStamp:
          description: Date and time of generation of the PensionStatement.
          type: string
          format: date-time
          examples:
            - '2018-04-13T11:11:11Z'
        languageCode:
          $ref: '#/components/schemas/LanguageCode'
        pensionStatementId:
          $ref: '#/components/schemas/PensionStatementId'
        pensionStatementNo:
          $ref: '#/components/schemas/PensionStatementNo'
    PensionStatementId:
      description: Technical ID of pension statement used in API calls.
      type: string
      pattern: ^[A-Za-z0-9_\-.~]{1,64}$
      examples:
        - 550e8450-e59b-21d4-a346-442215440560
    PensionStatementNo:
      description: Pension statement number (as printed on statement).
      type: string
      examples:
        - PS_ID_6789-ABC
    PensionStatementType:
      description: |
        Pension statement type:
        - `regular`: the pension statement is an offical, regular statement on the basis of real values (not changed for simulation purposes)
        - `simulated`: the pension statement is a non-offical, simulated statement, i.e. some values might have been changed for simulation
        purposes
      type: string
      enum:
        - regular
        - simulated
      examples:
        - regular
    PersonId:
      description: Technical ID of insured person used in API calls.
      type: string
      pattern: ^[A-Za-z0-9_\-.~]{1,64}$
      examples:
        - JohnDoe_1234
    PersonalPensionDetails:
      description: |
        Shared pension-related data specific to the insured person. This data structure is used in policies and pension statements to represent
        key attributes like salary, capital and benefits.
      type: object
      required:
        - earliestRetirementAge
        - financing
        - homeOwnershipAvailableForWithdrawal
        - ordinaryRetirementAge
        - regularPurchaseMaxAmount
        - retirementCapital
        - riskBenefits
        - salaryData
        - vestedBenefits
      properties:
        earliestRetirementAge:
          type: integer
          format: int32
          description: Age (in month since birth) for earliest possible retirement.
          examples:
            - 696
        financing:
          $ref: '#/components/schemas/Financing'
        homeOwnershipAvailableForWithdrawal:
          $ref: '#/components/schemas/HomeOwnershipAvailableForWithdrawal'
        ordinaryRetirementAge:
          $ref: '#/components/schemas/OrdinaryRetirementAge'
        regularPurchaseMaxAmount:
          $ref: '#/components/schemas/RegularPurchaseMaxAmount'
        retirementCapital:
          $ref: '#/components/schemas/RetirementCapital'
        riskBenefits:
          $ref: '#/components/schemas/RiskBenefits'
        salaryData:
          $ref: '#/components/schemas/SalaryData'
        vestedBenefits:
          $ref: '#/components/schemas/VestedBenefits'
        homeOwnershipAvailableForPledge:
          $ref: '#/components/schemas/HomeOwnershipAvailableForPledge'
    PlanId:
      description: Technical ID of pension plan used in API calls.
      type: string
      pattern: ^[A-Za-z0-9_\-.~]{1,64}$
      examples:
        - Plan_XY4284_425
    PlanName:
      description: Insurance plan name.
      type: string
      examples:
        - Basisplan
    Pledge:
      description: Details about pledged capital.
      type: object
      properties:
        amount:
          type: number
          format: double
          description: Amount of retirement capital used for pledging (mandatory and supplementary).
          examples:
            - 20000
        amountMandatory:
          type: number
          format: double
          description: Amount of retirement capital used for pledging (mandatory part only).
          examples:
            - 20000
        pledgee:
          type: string
          description: The name of the pledgee.
          examples:
            - UBS AG
        pledgeeAddress:
          $ref: '#/components/schemas/Address'
    PoBox:
      description: PO box.
      type: string
      examples:
        - PO Box 42
    Policy:
      description: Details of policy.
      type: object
      required:
        - contractNo
        - entryDate
        - pensionPlan
        - pensionProvider
        - personId
        - personalPensionDetails
        - policyId
        - policyNo
        - referenceDate
      properties:
        contractNo:
          type: string
          description: Contract number of contract between employer and pension fund.
          examples:
            - C27-842.183
        entryDate:
          description: Entry date into the pension plan.
          type: string
          format: date
          examples:
            - '2018-04-13'
        pensionPlan:
          $ref: '#/components/schemas/PensionPlan'
        pensionProvider:
          $ref: '#/components/schemas/PensionProvider'
        personId:
          $ref: '#/components/schemas/PersonId'
        personalPensionDetails:
          $ref: '#/components/schemas/PersonalPensionDetails'
        policyId:
          $ref: '#/components/schemas/PolicyId'
        policyNo:
          type: string
          description: Policy number (as printed on policy statements).
          examples:
            - 392'485'482
        referenceDate:
          description: Reference date of the personal pension details.
          type: string
          format: date
          examples:
            - '2018-04-13'
        employer:
          $ref: '#/components/schemas/Employer'
        isInVestedBenefitFoundation:
          type: boolean
          description: |
            Indicates if policy is part of a vested benefit foundation (as opposed to a regular pension fund with payments from an employer). If
            the field is not set, a regular pension fund is assumed.
          examples:
            - false
    PolicyId:
      description: Technical ID of policy used in API calls.
      type: string
      pattern: ^[A-Za-z0-9_\-.~]{1,64}$
      examples:
        - Pol_56789-2024
    PortalName:
      description: Offical name of the insurance portal.
      type: string
      examples:
        - Omni Portal
    PortalUrl:
      description: URL of the insurance portal of the pension fund.
      type: string
      examples:
        - www.omnifund.ch
    PostalCode:
      description: Postal code.
      type: string
      examples:
        - '3944'
    ProviderId:
      description: Swiss Enterprise Identification Number UID.
      type: string
      examples:
        - CHE123456789
    ProviderName:
      description: The name of the pension provider.
      type: string
      examples:
        - Omnifund
    Psc:
      description: |
        Psc = pension statement compact, is a reduced pension statement consisting of only the most important pension statement information.
      type: object
      required:
        - bym
        - eii
        - en
        - era
        - hoaw
        - ora
        - ppi
        - ppl
        - ppn
        - pst
        - rb
        - rc
        - rd
        - rpm
        - sd
        - ts
      properties:
        bym:
          $ref: '#/components/schemas/BirthYearMonth'
        eii:
          $ref: '#/components/schemas/EmployerInternalId'
        en:
          $ref: '#/components/schemas/EmployerName'
        era:
          type: integer
          format: int32
          description: Age (in month since birth) for earliest possible retirement.
          examples:
            - 696
        hoaw:
          $ref: '#/components/schemas/HomeOwnershipAvailableForWithdrawal'
        ora:
          type: integer
          format: int32
          description: Age (in month since birth) for ordinary retirement.
          examples:
            - 780
        ppi:
          $ref: '#/components/schemas/ProviderId'
          description: Swiss Enterprise Identification Number UID of the pension provider.
        ppl:
          type: object
          description: |
            The pension plan defines various conditions for the occupational pension provision of the insured employees, incl. the contributions
            and insured benefits.
          required:
            - ct
            - pln
          properties:
            ct:
              $ref: '#/components/schemas/ContractType'
            pln:
              $ref: '#/components/schemas/PlanName'
        ppn:
          $ref: '#/components/schemas/ProviderName'
        pst:
          $ref: '#/components/schemas/PensionStatementType'
        rb:
          type: object
          description: Benefits in case of death or disability to work.
          required:
            - cpd
            - mlswpb
            - opd
            - pd
            - ppd
          properties:
            cpd:
              $ref: '#/components/schemas/ChildPensionDisability'
            mlswpb:
              $ref: '#/components/schemas/MinimalLumpSumWithPensionBenefits'
            opd:
              $ref: '#/components/schemas/OrphanPensionDeath'
            pd:
              $ref: '#/components/schemas/PensionDisability'
            ppd:
              $ref: '#/components/schemas/PartnerPensionDeath'
        rc:
          type: object
          description: Retirement capital balances for the past and projections for the future.
          required:
            - bmr
            - brd
            - prb
          properties:
            bmr:
              $ref: '#/components/schemas/BalanceMandatoryReferenceDate'
            brd:
              $ref: '#/components/schemas/BalanceReferenceDate'
            prb:
              type: array
              description: |
                Projected retirement benefits for selected retirement ages. The list contains projections for the earliest possible retirement
                age, the regular retirement age, and the latest possible retirement age. If the insured person has already exceeded the earliest
                possible retirement age, the projection for the earliest possible retirement age is replaced by a projection for the earliest
                remaining retirement age above the person’s current age. In all cases, the projections for the regular and the latest possible
                retirement age are included, provided they are higher than the current age.
              items:
                type: object
                required:
                  - cb
                  - p
                  - ra
                properties:
                  cb:
                    $ref: '#/components/schemas/CapitalBalance'
                  p:
                    $ref: '#/components/schemas/Pension'
                  ra:
                    $ref: '#/components/schemas/RetirementAge'
        rd:
          description: Reference date of pension statement.
          type: string
          format: date
          examples:
            - '2018-04-13'
        rpm:
          $ref: '#/components/schemas/RegularPurchaseMaxAmount'
        sd:
          type: object
          description: Details of salary relevant for insurance.
          required:
            - ds
            - el
            - ism
            - isre
            - isri
          properties:
            ds:
              $ref: '#/components/schemas/DeclaredSalary'
            el:
              $ref: '#/components/schemas/EmploymentLevel'
            ism:
              $ref: '#/components/schemas/InsuredSalaryMandatory'
            isre:
              $ref: '#/components/schemas/InsuredSalaryRetirement'
            isri:
              $ref: '#/components/schemas/InsuredSalaryRisk'
        ts:
          description: Date and time of generation of the PensionStatement.
          type: string
          format: date-time
          examples:
            - '2018-04-13T11:11:11Z'
    Psc3A:
      description: |
        Psc3A = pension statement compact 3a, is a reduced account statement consisting of only the most important account statement information.
        All monetary values are in Swiss Francs (CHF) unless explicitly stated otherwise.
        Short property names (3-4 chars) are used to minimize payload size.
      type: object
      required:
        - ai
        - cp
        - pn
        - ppn
        - pyd
        - rc
        - rd
        - ts
      properties:
        ai:
          type: string
          description: |
            Unique Account Identifier. Use IBAN format (ISO 13616) whenever possible. If the product does not have an IBAN, use the policy or
            contract number.
          examples:
            - CH9300762011623852957
        cp:
          type: object
          description: Contribution potential (indicative, provider-specific view).
          required:
            - cy
          properties:
            cy:
              type: number
              format: double
              description: |
                Indicative remaining contribution capacity for the current year at this provider.
                Calculated as the applicable annual cap minus deposits already made at THIS provider.
                No guarantee of total tax deductibility if other 3a accounts exist.
              examples:
                - 2500
            ret:
              type: number
              format: double
              description: |
                Indicative potential for retroactive purchases (past years).
                Based solely on information available to this provider.
                Non-binding and without legal effect regarding tax deductibility.
                Omission of this field indicates the amount is unknown.
              examples:
                - 8400
        pn:
          type: string
          description: Product name.
          examples:
            - sparen 3a
        ppn:
          $ref: '#/components/schemas/ProviderName'
        pyd:
          $ref: '#/components/schemas/CapitalDevelopment'
          description: Capital development for the full previous calendar year. When not available set all values to 0.
          required:
            - cg
            - de
            - fe
            - ic
            - wi
          examples:
            - cg: 1500
              de: 7056
              fe: -20
              ic: 50
              wi: 0
        rc:
          type: object
          description: |
            Retirement capital properties.
            Consistency rules:
            - cb = cbpy + sum of cyd-properties
            Minor rounding differences up to CHF 0.05 are acceptable.
          required:
            - cb
            - cbpy
            - inv
          properties:
            cb:
              description: Current capital balance.
              $ref: '#/components/schemas/CapitalBalance'
              examples:
                - 44000
            cbpy:
              $ref: '#/components/schemas/CapitalBalance'
              description: |
                Capital balance at the end of the previous year (Dec 31st).
                Set to 0.0 if the account was opened or transferred to this provider during the current year.
              examples:
                - 42000
            inv:
              type: number
              format: double
              description: |
                Current invested share as an absolute amount. The remaining amount (cb minus inv) represents the cash/liquidity balance.
              examples:
                - 85520
        rd:
          description: Reference date of 3a account statement.
          type: string
          format: date
          examples:
            - '2018-04-13'
        ts:
          description: Date and time of generation of the 3a account statement.
          type: string
          format: date-time
          examples:
            - '2018-04-13T11:11:11Z'
        bch:
          type: boolean
          description: |
            Indicates whether a beneficiary change occurred.
            true = there was a beneficiary change.
            false = there was no beneficiary change.
            Presence of this field confirms the status is known; omission indicates the status is unknown.
          examples:
            - true
            - false
        cyd:
          $ref: '#/components/schemas/CapitalDevelopment'
          description: Capital development from Jan 1st of the current year to the reference date.
          required:
            - cg
            - de
            - fe
            - ic
            - wi
          examples:
            - cg: 200
              de: 1800
              fe: 0
              ic: 0
              wi: 0
        div:
          type: number
          format: double
          description: |
            The amount withdrawn for pension equalization following a divorce.
            Presence of this field confirms that the status and amount are known. Set to 0 if no withdrawal occurred.
            Omission indicates that the status or amount is unknown.
          examples:
            - 10000
        plg:
          type: number
          format: double
          description: |
            The amount of currently pledged capital.
            Presence of this field confirms that the status and amount are known. Set to 0 if no pledged capital exists.
            Omission indicates that the status or amount is unknown.
          examples:
            - 20000
        pw:
          type: boolean
          description: |
            Indicates whether a premium waiver in case of disability applies.
            true = a premium waiver applies.
            false = no premium waiver applies.
            Presence of this field confirms the status is known.
            Omission indicates the status is unknown.
          examples:
            - true
            - false
        wef:
          type: number
          format: double
          description: |
            The cumulative net amount withdrawn for home ownership financing (WEF).
            Based solely on information available to this provider, might be incomplete for technical reasons.
            Set to 0 if no withdrawal occurred. Omission indicates that the status or amount is unknown.
          examples:
            - 50000
    PscVb:
      description: |
        PscVb = pension statement compact vested benefit, is a reduced pension statement consisting of only the most important pension statement
        information. All monetary values are in Swiss Francs (CHF) unless explicitly stated otherwise.
        Short property names (3-4 chars) for QR code payload.
      type: object
      required:
        - ai
        - hoaw
        - pn
        - ppn
        - pyd
        - rc
        - rd
        - ts
      properties:
        ai:
          type: string
          description: |
            Unique Account Identifier. Use IBAN format (ISO 13616) whenever possible. If the product does not have an IBAN, use the policy or
            contract number.
          examples:
            - CH9300762011623852957
        hoaw:
          $ref: '#/components/schemas/HomeOwnershipAvailableForWithdrawal'
          description: Amount available for withdrawal for home ownership.
        pn:
          type: string
          description: Product name.
          examples:
            - vested benefits account
        ppn:
          $ref: '#/components/schemas/ProviderName'
        pyd:
          $ref: '#/components/schemas/CapitalDevelopment'
          description: Capital development for the full previous calendar year. When not available set all values to 0.
          required:
            - cg
            - de
            - fe
            - ic
            - wi
          examples:
            - cg: 1500
              de: 7000
              fe: -20
              ic: 120
              wi: 0
        rc:
          type: object
          description: |
            Retirement capital balances.
            Consistency rules:
            - cb = cbpy + sum of cyd-properties
            Minor rounding differences up to CHF 0.05 are acceptable.
          required:
            - cb
            - cbpy
            - inv
          properties:
            cb:
              description: Current capital balance.
              $ref: '#/components/schemas/CapitalBalance'
              examples:
                - 110000
            cbpy:
              $ref: '#/components/schemas/CapitalBalance'
              description: |
                Capital balance at the end of the previous year (Dec 31st).
                Set to 0.0 if the account was opened or transferred to this provider during the current year.
              examples:
                - 106900
            inv:
              type: number
              format: double
              description: |
                Current invested share as an absolute amount. The remaining amount (cb minus inv) represents the cash/liquidity balance.
              examples:
                - 85520
            bvg:
              type: number
              format: double
              description: BVG share as an absolute amount.
              examples:
                - 71500
        rd:
          description: Reference date of vested benefit statement.
          type: string
          format: date
          examples:
            - '2018-04-13'
        ts:
          description: Date and time of generation of the VestedBenefitStatement.
          type: string
          format: date-time
          examples:
            - '2018-04-13T11:11:11Z'
        bch:
          type: boolean
          description: |
            Indicates whether a beneficiary change occurred.
            true = there was a beneficiary change.
            false = there was no beneficiary change.
            Presence of this field confirms the status is known; omission indicates the status is unknown.
          examples:
            - true
            - false
        cyd:
          $ref: '#/components/schemas/CapitalDevelopment'
          description: Capital development from Jan 1st of the current year to the reference date.
          required:
            - cg
            - de
            - fe
            - ic
            - wi
          examples:
            - cg: 570
              de: 2500
              fe: -20
              ic: 50
              wi: 0
        div:
          type: number
          format: double
          description: |
            The amount withdrawn for pension equalization following a divorce.
            Presence of this field confirms that the status and amount are known. Set to 0 if no withdrawal occurred.
            Omission indicates that the status or amount is unknown.
          examples:
            - 10000
        p3y:
          type: object
          description: |
            If this field is present, then there is known purchase activity information for the last 3 years.
            Based solely on information available to this provider.
            If it is missing, this information is unknown.
          required:
            - s
          properties:
            s:
              type: number
              format: double
              description: |
                Cumulative purchase amount within the last 3 years.
                Based solely on information available to this provider.
              examples:
                - 15000
            d:
              description: |
                Date of the most recent purchase within the last 3 years.
                Based solely on information available to this provider.
                Omit this field if no purchase occurred within the last 3 years.
              type: string
              format: date
              examples:
                - '2025-04-13'
        plg:
          type: number
          format: double
          description: |
            The amount of currently pledged capital.
            Presence of this field confirms that the status and amount are known. Set to 0 if no pledged capital exists.
            Omission indicates that the status or amount is unknown.
          examples:
            - 20000
        wef:
          type: number
          format: double
          description: |
            The cumulative net amount withdrawn for home ownership financing (WEF).
            Based solely on information available to this provider, might be incomplete for technical reasons.
            Set to 0 if no withdrawal occurred. Omission indicates that the status or amount is unknown.
          examples:
            - 50000
    PurchaseSimParameters:
      description: Voluntary purchase simulation parameters.
      type: object
      required:
        - totalAmount
      properties:
        totalAmount:
          type: number
          description: Purchase amount in CHF. For periodic purchases, the sum of all payments.
          examples:
            - 10000
        date:
          description: 'Date of the (first) payment. If omitted: tomorrow.'
          type: string
          format: date
          examples:
            - '2018-04-13'
        paymentFrequency:
          $ref: '#/components/schemas/PaymentFrequency'
        paymentSize:
          type: number
          description: The size of individual periodic payments. If omitted, 0 or equal to 'amount', a one-time payment is assumed.
          examples:
            - 10000
        retirementAge:
          type: integer
          description: Planned retirement age (in month since birth). If omitted, the regular payment age is assumed.
          examples:
            - 780
    RegularPurchaseMaxAmount:
      description: |
        The maximum amount the insured person is permitted to contribute to their pension plan as an ordinary purchase,
        excluding any purchase to finance or compensate for early retirement.
      type: number
      format: double
      examples:
        - 48392.45
    RetirementAge:
      description: Specified age (in month since birth) used for the retirement benefits calculation.
      type: integer
      format: int32
      examples:
        - 756
    RetirementBenefits:
      description: |
        Retirement benefits for retirement at the specified age. The conversion rate is mandatory: either the pair for mandatory and supplementary
        coverage is provided, or the enveloping conversion rate.
      type: object
      required:
        - capitalBalance
        - capitalBalanceMandatory
        - retirementAge
      properties:
        capitalBalance:
          $ref: '#/components/schemas/CapitalBalance'
        capitalBalanceMandatory:
          $ref: '#/components/schemas/CapitalBalanceMandatory'
        retirementAge:
          $ref: '#/components/schemas/RetirementAge'
        capitalBalanceNoInterest:
          $ref: '#/components/schemas/CapitalBalanceNoInterest'
        capitalBalanceNoInterestMandatory:
          $ref: '#/components/schemas/CapitalBalanceNoInterestMandatory'
        conversionRateEnveloping:
          $ref: '#/components/schemas/ConversionRateEnveloping'
        conversionRateMandatory:
          $ref: '#/components/schemas/ConversionRateMandatory'
        conversionRateSupplementary:
          $ref: '#/components/schemas/ConversionRateSupplementary'
        pension:
          $ref: '#/components/schemas/Pension'
    RetirementCapital:
      description: Retirement capital balances for the past and projections for the future.
      type: object
      required:
        - balanceMandatoryReferenceDate
        - balanceReferenceDate
        - interestRates
        - lastYearDevelopment
        - projectedRetirementBenefits
      properties:
        balanceMandatoryReferenceDate:
          $ref: '#/components/schemas/BalanceMandatoryReferenceDate'
        balanceReferenceDate:
          $ref: '#/components/schemas/BalanceReferenceDate'
        interestRates:
          $ref: '#/components/schemas/InterestRates'
        lastYearDevelopment:
          $ref: '#/components/schemas/LastYearDevelopment'
        projectedRetirementBenefits:
          type: array
          description: |
            Projected retirement benefits for a series of retirement ages. The list contains projections for each integer retirement age from 58
            to the regular retirement age. For persons of 58 or older, the list is restricted to retirement ages higher than their current age.
          items:
            $ref: '#/components/schemas/RetirementBenefits'
        balanceEndCurrentYear:
          $ref: '#/components/schemas/BalanceEndCurrentYear'
        balanceMandatoryEndCurrentYear:
          $ref: '#/components/schemas/BalanceMandatoryEndCurrentYear'
        transferredCapital:
          $ref: '#/components/schemas/TransferredCapital'
        transferredCapitalMandatory:
          $ref: '#/components/schemas/TransferredCapitalMandatory'
    RiskBenefits:
      description: Benefits in case of death or disability to work.
      type: object
      required:
        - childPensionDisability
        - lumpSumWithoutPensionBenefits
        - minimalLumpSumWithPensionBenefits
        - orphanPensionDeath
        - partnerPensionDeath
        - pensionDisability
      properties:
        childPensionDisability:
          $ref: '#/components/schemas/ChildPensionDisability'
        lumpSumWithoutPensionBenefits:
          $ref: '#/components/schemas/LumpSumWithoutPensionBenefits'
        minimalLumpSumWithPensionBenefits:
          $ref: '#/components/schemas/MinimalLumpSumWithPensionBenefits'
        orphanPensionDeath:
          $ref: '#/components/schemas/OrphanPensionDeath'
        partnerPensionDeath:
          $ref: '#/components/schemas/PartnerPensionDeath'
        pensionDisability:
          $ref: '#/components/schemas/PensionDisability'
    SalaryChangeSimParameters:
      description: Salary change simulation parameters.
      type: object
      required:
        - declaredSalary
        - employmentLevel
      properties:
        declaredSalary:
          type: number
          format: double
          description: Changed gross annual salary in CHF (for employment level 100%).
          examples:
            - 80000
        employmentLevel:
          type: number
          format: double
          description: Changed level of full-time/part-time employment (in percent, 100 for full-time employment).
          examples:
            - 80
        effectiveDate:
          description: 'Date when the salary change takes effect. If omitted: tomorrow.'
          type: string
          format: date
          examples:
            - '2018-04-13'
    SalaryData:
      description: Details of salary relevant for insurance.
      type: object
      required:
        - declaredSalary
        - employmentLevel
        - insuredSalaryMandatory
        - insuredSalaryRetirement
        - insuredSalaryRisk
      properties:
        declaredSalary:
          $ref: '#/components/schemas/DeclaredSalary'
        employmentLevel:
          $ref: '#/components/schemas/EmploymentLevel'
        insuredSalaryMandatory:
          $ref: '#/components/schemas/InsuredSalaryMandatory'
        insuredSalaryRetirement:
          $ref: '#/components/schemas/InsuredSalaryRetirement'
        insuredSalaryRisk:
          $ref: '#/components/schemas/InsuredSalaryRisk'
        additionalSalary:
          $ref: '#/components/schemas/AdditionalSalary'
        bonus:
          $ref: '#/components/schemas/Bonus'
        otherSalaryComponent:
          $ref: '#/components/schemas/OtherSalaryComponent'
    Sex:
      description: |
        Sex:
        * `male`: male
        * `female`: female
      type: string
      enum:
        - male
        - female
      examples:
        - male
    SimulationResultPensionStatement:
      description: Financial effect of simulation.
      type: object
      required:
        - pensionStatementAfterChange
        - pensionStatementBeforeChange
      properties:
        pensionStatementAfterChange:
          $ref: '#/components/schemas/PensionStatement'
          description: |
            Provides the pension statement after the change.
            In case of salaray change: referenceDate = tomorrow OR effectiveDate, if specified as API parameter
            In case of purchase: referenceData = day after the (last) payment
        pensionStatementBeforeChange:
          $ref: '#/components/schemas/PensionStatement'
          description: Provides the pension statement before the change (referenceDate = today)
    Street:
      description: Street and house number.
      type: string
      examples:
        - Brandstrasse 2
    Town:
      description: Town.
      type: string
      examples:
        - Unterbäch
    Transaction:
      description: Transaction affecting the retirement capital.
      type: object
      required:
        - amount
        - balance
        - category
        - date
        - reason
      properties:
        amount:
          type: number
          description: Transaction amount (in CHF, positive numbers for credits, negative numb for debits).
          examples:
            - 10000
        balance:
          type: number
          format: double
          description: Retirement capital balance after transaction.
          examples:
            - 63842.5
        category:
          type: string
          description: |
            Transaction category:
            - `carryover`: Pseudo transaction to provide the carryover from the preceding period
            - `transfer`: Transfer in and out of the fund (related to an start and end of employment)
            - `employeeContribution`: Employee contribution as part of salary payment
            - `employerContribution`: Employer contribution as part of salary payment
            - `homeOwnershipEncouragement`: Transaction related to home ownerhsip encouragement scheme
            - `voluntaryPurchase`: Transaction related to voluntary purchse of retirement benefits
            - `securityInvestment`: Transaction related to a security investment or deinvestment
            - `dividend`: Transaction related to payouts/distributions from security investments
            - `fee`: Transaction related to fees
            - `other`: Other reason for transaction not listed above
          enum:
            - carryover
            - transfer
            - employeeContribution
            - employerContribution
            - homeOwnershipEncouragement
            - voluntaryPurchase
            - securityInvestment
            - dividend
            - fee
            - other
          examples:
            - voluntaryPurchase
        date:
          description: Transaction date (date the transaction becomes effective financially).
          type: string
          format: date
          examples:
            - '2018-04-13'
        reason:
          type: string
          description: A human-readable description of the transaction reason, in the insured person's preferred language.
          examples:
            - Freiwilliger Einkauf
        id:
          type: string
          description: Transaction ID.
          examples:
            - TR-683463823
    Transactions:
      description: Retirement capital transactions.
      type: object
      required:
        - from
        - to
        - transactions
      properties:
        from:
          description: Start of date range (inclusive).
          type: string
          format: date
          examples:
            - '2018-04-13'
        to:
          description: End of date range (inclusive).
          type: string
          format: date
          examples:
            - '2018-04-13'
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
          description: Chronologically sorted list of transactions.
    TransferredCapital:
      description: Total retirement capital (mandatory and supplementary coverage) brought from other funds into this fund.
      type: number
      format: double
      examples:
        - 45210.25
    TransferredCapitalMandatory:
      description: Retirement capital under mandatory coverage brought from other funds into this fund.
      type: number
      format: double
      examples:
        - 32840.55
    VestedBenefits:
      description: |
        The VestedBenefits object provides detailed information about the insured person's accrued retirement capital under occupational pension
        plans (2nd pillar). It includes key data such as retirement capital at significant milestones (e.g., age 50, marriage), and records of
        transactions like voluntary purchases, withdrawals for home ownership (WEF), or adjustments due to divorce. This information is essential
        for managing entitlements and processing pension transfers.
      type: object
      properties:
        capitalAt50:
          type: number
          format: double
          description: The insured person's retirement capital when he/she was 50 (mandatory and supplementary). Empty for persons younger than 50.
          examples:
            - 0
        capitalAt50Mandatory:
          type: number
          format: double
          description: The insured person's retirement capital when he/she was 50 (mandatory part only). Empty for persons younger than 50.
          examples:
            - 0
        capitalAtMarriage:
          type: number
          format: double
          description: |
            The insured person's retirement capital before he/she got married or entered a registered partnership (mandatory and supplementary).
            Relevant is the last marriage or registered partnership (the marriage/partnership date is part of the insured person object.)

            Empty for persons who are not married or in a registered partnership.
          examples:
            - 28483.35
        capitalAtMarriageMandatory:
          type: number
          format: double
          description: |
            The insured person's retirement capital before he/she got married or entered a registered partnership (mandatory part only). Relevant
            is the last marriage or registered partnership (the marriage/partnership date is part of the insured person object.)

            Empty for persons who are not married or in a registered partnership.
          examples:
            - 23863.15
        capitalFirstCommunicated:
          type: number
          format: double
          description: |
            Vested benefit capital that has been initially communicated or had become due after January 1, 1995 (for insured persons having
            married before January 1, 1995).
          examples:
            - 0
        capitalFirstCommunicatedDate:
          description: |
            Date when vested benefit capital has been initially communicated or had become due after January 1, 1995 (for insured persons having
            married before January 1, 1995).
          type: string
          format: date
          examples:
            - '2018-04-13'
        divorceWithdrawals:
          type: array
          items:
            $ref: '#/components/schemas/CapitalTransaction'
          description: List of withdrawls and refunds due to divorce made in the past.
        homeOwnershipWithdrawals:
          type: array
          items:
            $ref: '#/components/schemas/CapitalTransaction'
          description: List of withdrawls and refunds for home ownership promotion made in the past.
        pledges:
          type: array
          items:
            $ref: '#/components/schemas/Pledge'
          description: List of pledges of parts of the retirement capital.
        referenceDate:
          description: Reference date of the vested benefit information.
          type: string
          format: date
          examples:
            - '2018-04-13'
        voluntaryPurchases:
          type: array
          items:
            $ref: '#/components/schemas/CapitalTransaction'
          description: |
            List of voluntary purchases of additional pension benefits made in the past. At least the purchases of the last 3 years must be
            included. They can be aggregated by calendar year.
  responses:
    standard400:
      description: Some of the input is incomplete or invalid for starting a request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/CommonErrorResponse'
    standard401:
      description: Access token is missing or invalid.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/CommonErrorResponse'
    standard404:
      description: Invalid ID / no authorization to access data.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/CommonErrorResponse'
    standard500:
      description: Internal Server Error - The server encountered an unexpected condition that prevented it from fulfilling the request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/CommonErrorResponse'
  parameters:
    from_date:
      in: query
      name: from
      description: Start of date range (inclusive).
      required: true
      schema:
        $ref: '#/components/schemas/Date'
    pension_statement_id:
      in: path
      name: pensionStatementId
      description: Technical pension statement ID.
      required: true
      schema:
        $ref: '#/components/schemas/PensionStatementId'
    person_id:
      in: path
      name: personId
      description: Technical person ID.
      required: true
      schema:
        $ref: '#/components/schemas/PersonId'
    plan_id:
      in: path
      name: planId
      description: Unique identifier of the pension plan.
      required: true
      schema:
        $ref: '#/components/schemas/PlanId'
    policy_id:
      in: path
      name: policyId
      description: Technical policy ID.
      required: true
      schema:
        $ref: '#/components/schemas/PolicyId'
    reference_date:
      in: query
      name: reference_date
      description: Reference date for information in output.
      required: false
      schema:
        $ref: '#/components/schemas/Date'
    to_date:
      in: query
      name: to
      description: End of date range (inclusive).
      required: true
      schema:
        $ref: '#/components/schemas/Date'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            read:basic_pension_data: Access to basic pension data (user profile, pension statements, and transactions).
            read:pension_plan: Access to pension plan description.