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.yaml '400': $ref: ./components/responses/standard400.yaml '401': $ref: ./components/responses/standard401.yaml '404': $ref: ./components/responses/standard404.yaml '500': $ref: ./components/responses/standard500.yaml /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/path/person_id.yaml security: - OAuth2: - read:basic_pension_data responses: '200': description: Details of insured person. content: application/json: schema: $ref: ./components/schemas/InsuredPerson.yaml '401': $ref: ./components/responses/standard401.yaml '404': $ref: ./components/responses/standard404.yaml '500': $ref: ./components/responses/standard500.yaml /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/path/person_id.yaml - $ref: ./components/parameters/query/reference_date.yaml security: - OAuth2: - read:basic_pension_data responses: '200': description: Statement details. content: application/json: schema: type: array items: $ref: ./components/schemas/PensionStatement.yaml '400': $ref: ./components/responses/standard400.yaml '401': $ref: ./components/responses/standard401.yaml '404': $ref: ./components/responses/standard404.yaml '500': $ref: ./components/responses/standard500.yaml /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/path/pension_statement_id.yaml 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.yaml '404': $ref: ./components/responses/standard404.yaml '500': $ref: ./components/responses/standard500.yaml /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/path/pension_statement_id.yaml security: - OAuth2: - read:basic_pension_data responses: '200': description: Compact statement details. content: application/json: schema: $ref: ./components/schemas/Psc.yaml '401': $ref: ./components/responses/standard401.yaml '404': $ref: ./components/responses/standard404.yaml '500': $ref: ./components/responses/standard500.yaml /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/path/pension_statement_id.yaml security: - OAuth2: - read:basic_pension_data responses: '200': description: Compact vested benefits statement details. content: application/json: schema: $ref: ./components/schemas/PscVb.yaml '401': $ref: ./components/responses/standard401.yaml '404': $ref: ./components/responses/standard404.yaml '500': $ref: ./components/responses/standard500.yaml /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/path/pension_statement_id.yaml security: - OAuth2: - read:basic_pension_data responses: '200': description: Compact 3a statement details. content: application/json: schema: $ref: ./components/schemas/Psc3A.yaml '401': $ref: ./components/responses/standard401.yaml '404': $ref: ./components/responses/standard404.yaml '500': $ref: ./components/responses/standard500.yaml /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/path/policy_id.yaml security: - OAuth2: - read:basic_pension_data responses: '200': description: Policy details. content: application/json: schema: $ref: ./components/schemas/Policy.yaml '401': $ref: ./components/responses/standard401.yaml '404': $ref: ./components/responses/standard404.yaml '500': $ref: ./components/responses/standard500.yaml /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/path/plan_id.yaml 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.yaml '404': $ref: ./components/responses/standard404.yaml '500': $ref: ./components/responses/standard500.yaml /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/path/policy_id.yaml security: - OAuth2: - read:basic_pension_data requestBody: description: Salary change simulation parameters. required: true content: application/json: schema: $ref: ./components/schemas/SalaryChangeSimParameters.yaml responses: '200': description: Simulation result. content: application/json: schema: $ref: ./components/schemas/SimulationResultPensionStatement.yaml '401': $ref: ./components/responses/standard401.yaml '404': $ref: ./components/responses/standard404.yaml '500': $ref: ./components/responses/standard500.yaml /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/path/policy_id.yaml security: - OAuth2: - read:basic_pension_data requestBody: description: Voluntary purchase simulation parameters. required: true content: application/json: schema: $ref: ./components/schemas/PurchaseSimParameters.yaml responses: '200': description: Simulation result. content: application/json: schema: $ref: ./components/schemas/SimulationResultPensionStatement.yaml '401': $ref: ./components/responses/standard401.yaml '404': $ref: ./components/responses/standard404.yaml '500': $ref: ./components/responses/standard500.yaml /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/path/policy_id.yaml - $ref: ./components/parameters/query/from_date.yaml - $ref: ./components/parameters/query/to_date.yaml security: - OAuth2: - read:basic_pension_data responses: '200': description: Retirement capital transactions. content: application/json: schema: $ref: ./components/schemas/Transactions.yaml '400': $ref: ./components/responses/standard400.yaml '401': $ref: ./components/responses/standard401.yaml '404': $ref: ./components/responses/standard404.yaml '500': $ref: ./components/responses/standard500.yaml components: 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.