-
Notifications
You must be signed in to change notification settings - Fork 0
/
pensionAPI.yaml
2975 lines (2705 loc) · 112 KB
/
pensionAPI.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
openapi: 3.1.0
info:
version: 1.0.0
title: Pension
# yamllint disable rule:indentiation
# yamllint disable rule:line-length
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 zum Einkaufsprozess, für Simulationen und für Transaktionen.
Als Einstieg fürs Pension-API wird eine technische Personen- oder Policen-ID benötigt.
Dies wird vom Consent API geliefert.
Die wesentlichen Objekte dieses APIs sind *Person*, *Police* und *Vorsorgeausweis*. 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.
Der Vorsorgeausweis entspricht dem Dokument, welches traditionell anfangs Jahr durch die Pensionskasse
für die Versicherten ausgestellt wird.
Wo es relevant ist, Angaben in den obligatorischen und den über-obligatorischen Teil
aufzutrennen, wird jeweils das Total (obligatorisch plus über-obligatorisch) und der
obligatorische Wert separat ausgewiesen. Falls der über-obligatorische Wert benötigt wird, muss
er vom API-Konsumenten selbst berechnet werden (Differenz zwischen den beiden Werten).
Ausgenommen davon sind Zinssätze und Umwandlungssätze. Hier werden entweder der obligatorische
und der über-obligatorische Satz als zwei separate Werte geliefert, oder dann wird der
umhüllende Satz geliefert.
Das API umfasst auch die Simulation einer Änderung des Beschäftigtengrads und/oder Lohns. Die
Simulation berechnet die Effekte auf die monatlichen Beiträge sowie auf die voraussichtlichen
Rentenleistungen bei unterschiedlichem Penionierungsalter.
Das Einkaufsendpunkte erlauben es, die Auswirkungen eines freiwilligen Einkaufs in die Pensionskasse
zu simulieren und einen Einkauf zu starten.
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.
## Einkaufsprozess
Für einen freiwilligen Einkauf gelten eine Reihe von gesetzlichen Voraussetzungen, die erfüllt
sein müssen, z.B. dass WEF-Vorbezüge zurückgezahlt wurden. Deshalb besteht der Einkaufsprozess grob aus zwei Phasen:
- Prüfung: In dieser Phase wird der Antrag geprüft und bei Bedarf weitere Unterlagen von der versicherten Person eingefordert.
- Zahlung: Ist der Antrag bewilligt, so macht die versicherte Person eine oder mehrere Zahlungen.
## Einkaufsantrag
Beim Einkaufsprozess wird im ersten Schritt ein Einkaufsantrag erstellt. Er repräsentiert den nach aussen
sichtbaren Stand der Prozessinstanz. Der interne Prozess unterscheidet sich von Pensionskasse zu Pensionskasse
und besteht aus viel mehr Schritten als von aussen sichtbar. Der Antrag kann folgende Zustände haben, die für
die versicherte Person und im API sichtbar sind:
- In Prüfung: Die Pensionskasse ist dabei, den Antrag zu prüfen. Dies ist der erste Zustand eines neuen Antrags.
- Unterlagen erforderlich: Die Prüfung hat ergeben, dass die versicherte Person weitere Unterlagen einreichen oder
direkt mit der Pensionskasse Kontakt aufnehmen muss.
- Abgelehnt: Der Einkaufsantrag wurde abgelehnt. Dies ist ein Endzustand.
- Bewilligt: Der Einkaufsantrag wurde bewilligt. Die versicherte Person kann nun die Zahlungen vornehmen
(einmalige oder wiederkehrende).
- Abgeschlossen: Der Einkaufsantrag ist abgeschlossen. Eine oder mehrere Zahlungen sind erfolgt, und es sind keine
weiteren Zahlungen mehr möglich. Dies ist ein Endzustand.
Der Antrag kann über das API abgefragt werden und hat neben dem Antragszustand noch viele weitere Attribute,
z.B. die bewilligte Einkaufssumme, die Summe der erfolgten Zahlungen etc.
## Fragen im Einkaufsantrag
Die Einkaufsprüfung ist massgeblich durch gesetzliche Regelungen bestimmt. Dennoch gibt es Unterschiede zwischen den
Pensionskassen. Einige stellen mehr und präzisere Fragen, andere stellen weniger Fragen und fordern schneller nach
zusätzlichen Dokumenten oder Kontaktaufnahme.
Das API deckt dies ab, indem die Pensionskasse bestimmen kann, ob gewisse Fragen überhaupt gestellt werden. Diese
Fragen sind in der Tabelle unten als Optional markiert. Optionale Fragen sind optional für die Pensionskasse. Wird
die Frage angezeigt, muss die versicherte Person sie beantworten. Optionale Fragen können auch benutzt werden, um
die Fragen für die versicherte Person zu individualisieren. So kann darauf verzichtet werden, nach laufenden Renten
zu fragen, wenn die Person noch nicht 55 Jahre alt ist.
Einige Fragen hängen von anderen Fragen ab, d.h. die Fragen sind nur zu beantworten, falls bei einer anderen Frage
eine bestimmte Antwort gegeben wurde. Diese Abhängigkeiten sind in der Tabelle unten erwähnt.
Bei einigen Fragen kann die Pensionskasse einen Wert vorgeben, z.B. eine bereits bekannte Emailadresse. Dieser Wert
wird in das Antwortfeld eingefüllt und kann von der versicherten Person bei Bedarf geändert werden.
| Nr. | Frage | Typ der Antwort | Bemerkungen |
| --- | ----- | --------------- | ----------- |
| 1 | **Betrag** | | |
| 1a | Welchen Betrag möchten Sie in die Pensionskasse einzahlen? | Betrag | |
| 2 | **Freizügigkeitskonten oder -policen** | | |
| 2a | Verfügen Sie über Guthaben auf Freizügigkeitskonten bei Banken, bei der Stiftung Auffangeinrichtungen oder auf Freizügigkeitspolicen? | Ja/Nein | |
| 3 | **Selbständige Erwerbstätigkeit** | | |
| 3a | Waren Sie in der Vergangenheit je selbständig erwerbstätig und haben während dieser Zeit Beiträge zugunsten der Säule 3a einbezahlt? | Ja/Nein | |
| 3b | Wie hoch ist das Guthaben per 31.12. des letzten Jahrs? | Betrag | Optional. Nur fragen, falls Antwort auf Frage 3a “Ja” ist. |
| 4 | **Wohneigentum** | | |
| 4a | Haben Sie bei früheren Pensionskassen oder von Freizügigkeitskonten/-policen Vorbezüge getätigt und diese noch nicht vollständig zurückbezahlt? | Ja/Nein | |
| 5 | **Zuzug aus dem Ausland** | | |
| 5a | Sind Sie innerhalb der letzten 5 Jahre aus dem Ausland zugezogen? (gilt auch für Schweizer Staatsangehörige) | Ja/Nein | Optional. |
| 5b | Wann sind Sie zugezogen? | Datum | Optional. Nur fragen, falls Antwort auf Frage 5a “Ja” ist. |
| 5c | Waren Sie davor bereits bei einer Schweizer Vorsorgeeinrichtung versichert? | Ja/Nein | Optional. Nur fragen, falls Antwort auf Frage 5a “Ja” ist. |
| 5d | Wann sind Sie zum ersten Mal einer Schweizer Vorsorgeeinrichtung beigetreten? | Datum | Optional. Nur fragen, falls Antwort auf Frage 5a “Ja” ist. |
| 6 | **Bezug Altersrente / Kapitalauszahlung** | | |
| 6a | Beziehen Sie von einer Pensionskasse eine Altersrente oder haben Sie sich bereits Alterskapital auszahlen lassen? | Ja/Nein | Optional. |
| 7 | **Weitere Fragen zur Situation** | | |
| 7a | Sind Sie zusätzlich bei einer anderen Vorsorgeversicherung versichert? | Ja/Nein | Optional. |
| 7b | Sind Sie zu 100% arbeitsfähig? | Ja/Nein | Optional. |
| 7c | Handelt es sich beim Einkauf um einen Wiedereinkauf nach Ehescheidung oder nach gerichtlicher Auflösung einer eingetragenen Partnerschaft? | Ja/Nein | Optional. |
| 7d | Wird der Einkauf mit Geld aus der Säule 3a getätigt? | Ja/Nein | Optional. |
| 8 | **Kontaktangaben** | | |
| 8a | Ist Ihre Adresse <adresse> korrekt? | Ja/Nein | Optional. Die Adresse wird von der Pensionskasse geliefert und muss im Text oder separat angezeigt werden. |
| 8b | Unter welcher Telefonnummer dürfen wir Sie bei Fragen kontaktieren? | Telefonnummer | Optional. |
| 8c | Über welche Emailadresse dürfen wir Sie bei Fragen kontaktieren? | Emailadresse | Optional. |
## Instruktionen an die versicherte Person
Ergibt die Prüfung, dass weitere Unterlagen oder eine Kontaktaufnahme mit der Pensionskasse nötig sind, so können der
versicherten Person entsprechende Instruktionen erteilt werden. Diese können von der Pensionskasse frei formuliert werden.
Die Instruktionen bestehen aus einer Liste von Sätzen. Diese werden von der Applikation als unnummerierte Liste angezeigt, z.B:
- *Der Einkaufsbetrag reduziert sich um die Höhe des Guthabens auf den Freizügigkeitskonti / -policen. Bitte senden Sie uns
Kopien von Konto-/Policienauszügen, die den Stand per Ende letzten Jahres zeigen.*
- *Senden Sie die Dokumente an: Personalfürsorge der Firma Heierli AG, Bahnhofstrasse 13, 9000 St. Gallen.*
- *Alternativ können Sie die Dokumente an einkauf@heierli-pk.ch senden. Bitte beachten Sie, dass Emails einen Weg über Server
im Ausland nehmen können und die Vertraulichkeit auf dem Weg nicht gewährt ist.*
Sind weitere Unterlagen nötig, so müssen diese direkt an die Pensionskasse (und nicht über die Applikation) eingereicht werden.
Entsprechend gibt es kein API dafür.
## Feedback an die versicherte Person
In vielen Fällen ist die Antragsprüfung nicht automatisiert und sofort erledigt. Stattdessen dauert sie Stunden oder sogar einige
Tage. Wenn das Ergebnis vorliegt, sollte der/die AntragsstellerIn benachrichtigt werden. Dazu nutzt die Pensionskasse direkte
Kommunikationskanäle (Email, SMS, Telefonanruf etc.)
Hat die App einen eigenen Kommunikationskanal mit der versicherten Person, so kann sie regelmässig prüfen, ob sich der Status des
Antrags verändert hat und bei einer Änderung benachrichtigen. Dieser Kanal ist freiwillig und zusätzlich zur direkten Kommunikation
zwischen Pensionskasse und versicherter Person.
## Zahlungen
Wurde der Einkauf über einen bestimmten Betrag bewilligt, so kann der Betrag wie folgt überwiesen werden:
- **Einmalige Einzahlung mit Einzahlungsschein (QR-Rechnung)**: Die Pensionskasse stellt die Zahlungsdaten (Adresse, Kontonummer,
Referenznummer etc.) aus, die per API an die Applikation geliefert werden.
- **Einmalige Einzahlung über eBill**: Die Pensionskasse sendet eine eBill ans eBill-Konto der versicherten Person.
- **Regelmässige Einzahlungen per eBill**: Es wird ein Zahlungsrhythmus vereinbart, gemäss dem die Pensionskasse eBills ans
eBill-Konto der versicherten Person sendet.
- **Unregelmässige Einzahlungen per Einzahlungsschein (QR-Rechnung)**: Die Pensionskasse stellt die Zahlungsdaten (Adresse,
Kontonummer, Referenznummer etc.) aus, die die Applikation nutzt, um Zahlungen auszulösen, z.B. über eine E-Banking-Schnittstelle.
Es wird für alle Zahlungen die gleiche Referenznummer verwendet.
Eine Pensionskasse muss nicht alle vier Zahlungsmethoden unterstützen. Die unterstützen Zahlungsmethoden können über das API
abgefragt werden.
## 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 in 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 the purchasing process, for simulations
and for transactions.
Person and policy IDs serve as the entry point for this API. They are provided by the
Consent API.
The main objects are *person*, *policy* and *statement*. A person refers to a natural person
insured with a pension fund.
A policy describes the indirect contractural relationship between the insured person
(employee) and the pension fund. If a person is insured by two separate insurance plans,
e.g. a basic and a supplementary executive plan, the person has two separate plans.
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.
If it is relevant to distinguish between the mandatory and the supplementary insurance
coverage, a total value (mandatory and supplementary values combined) and a mandatory
coverage value are provided seperately. If the value for the supplementary coverage is
required, the API consumer must calculate it (difference between the two values).
Interest and conversion rates are the exception to this rule. The pension fund either
provides two separate values for the mandatory and the supplementary part, or they
provide a single enveloping value.
The API also includes the simulation of a change of employment level and/or salary. It
calculates the effects on the monthly contributions as well as the effects of the
perspective pension benefits for different retirement ages.
The Purchases endpoints can simulate the prospective effects of voluntary purchases of retirement
benefits and initiate a purchase.
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.
## Purchase Process
In order to make a voluntary purchase a number of legal requirements must be fulfilled, e.g. early withdrawal of savings
must have been paid back. Thus the purchase process consists of two phases:
- Validation: In the first phase, the purchase application is validated and - if needed - additional documentation is requests from the insured person.
- Payment: Once the application has been approved, the insured person makes one or several payments.
## Purchase Application
The initial step of the purchase process is to create an application. It represent the externally visible state
of the process instance. The internal process differs from pension fund to pension fund and likely consists
of far more steps than are externally visible. The application can have the below states that are visible
for the insured person and in the API:
- In review: The pension fund is reviewing and validating the application. This is the initial state of a new application.
- Input required: The validation requires the the insured person provides additional documents or contacts the pension fund directly.
- Rejected: The application has been rejected. This is a final state.
- Approved: The purchase application was approved. The insured person can now make payments (once or repeating).
- Completed: The purchase application has been completed. One or more payments have been received, and no further payments
are possible. This is a final state.
The application can be queried using the API. It will return the application state and many additional attributes,
such as the approved purchase amount, the amount of received payments.
## Purchase Questionnaire
The purchase application validation is mainly governed by legal regulation. Nevertheless, there are differences between
the pension funds. Some funds ask many precise questions while other funds ask few questions and quickly resort
to requesting additional documents or direct contact.
The API covers these differences as the pension fund can decide if certain questions are asked at all. These questions
are marked as optional in the below table. Optional questions are optional for the pension fund. If the questions is
displayed to the insured person, it must be answered. Optional questions can also be used to tailor the questionnaire
to the insured person, e.g. by not asking whether the person is already drawing a pension if he/she is younger than 55.
Some questions depend on the answer of other question, i.e. the question is only relevant if a certain answer has been
given to a previous question. Such dependencies are mentioned in the below table.
For certain questions, the pension fund can provide an initial value, e.g. an earlier provided email address. The answer field
will be prefilled with this value and the insured person can change it if needed.
| No | Question | Answer type | Remark |
| --- | ----- | --------------- | ----------- |
| 1 | **Amount** | | |
| 1a | What amount of payment would you like to make towards the pension fund? | Amount | |
| 2 | **Pillar 2 Vested Benefits** | | |
| 2a | Do you have any additional pillar 2 claims from vested benefits accounts, vested benefits policies or at the Foundation of the BVG Contingency Fund? | Yes/No | |
| 3 | **Self-employment** | | |
| 3a | Have you ever been self-employed and paid into pillar 3a during that time? | Yes/No | |
| 3b | What is the pillar 3a balance as of 31 December of last year? | Amount | Optional. Will only be asked if the answer for question 3a is 'Yes'. |
| 4 | **Residental property** | | |
| 4a | Have you made an early withdrawal of pension savings to fund the purchase of residential property and have not fully paid it back? | Yes/No | |
| 5 | **Move to Switzerland** | | |
| 5a | Have you moved to Switzerland from another country during the last 5 years? (applies to Swiss citizens as well) | Yes/No | Optional. |
| 5b | When have you moved to Switzerland? | Date | Optional. Will only be asked if answer to question 5a is 'Yes'. |
| 5c | Have you ever joined a Swiss pillar 2 pension plan before? | Yes/No | Optional. Will only be asked if answer to question 5a is 'Yes'. |
| 5d | When have you joined a Swiss pillar 2 pension plan for the first time? | Date | Optional. Will only be asked if answer to question 5a is 'Yes'. |
| 6 | **Early retirement pension / savings capital withdrawal** | | |
| 6a | Are you drawing a retirement pension or have you ever withdrawn retirement savings capital from a pension fund? | Yes/No | Optional. |
| 7 | **Additional question regarding the insured person** | | |
| 7a | Are you currently insured in an additional pension plan? | Yes/No | Optional. |
| 7b | Are you fully able for work? | Yes/No | Optional. |
| 7c | Is the purchase made to make up for the pension savings surrender due to a divorce or a dissolution of a civil partnership?? | Yes/No | Optional. |
| 7d | Is the purchase made with money originating from a pillar 3a account? | Yes/No | Optional. |
| 8 | **Contact** | | |
| 8a | Is your address <adresse> correct? | Yes/No | Optional. The address will be provided by the pension fund and must be displayed in the question text or nearby on the screen. |
| 8b | What is your phone number to contact you in case of questions? | Phone number | Optional. |
| 8c | What is your email address to contact you in case of questions? | Email address | Optional. |
## Instructions for the Insured Person
If the result of the initial review is that additional documents or direct contact with the pension fund is needed,
such instructions can be given to the insured person. The pension fund can phrase the instructions according to their needs.
Structurally, the instructions are a list of sentences. The application will display them as bullet list, e.g.:
- *Your purchasing potential will be reduced by your further claims from pillar 2 (vested benefits account or policy). Please
send us a copy of the current account statement for your vested benefit accounts.*
- *Please send the documents to: Personalfürsorge der Firma Heierli AG, Bahnhofstrasse 13, 9000 St. Gallen.*
- *Alternatively, you can send the documents to einkauf@heierli-pk.ch. Please not that emails can take a route via servers abroad,
and confidentially on this path cannot be guaranteed.*
If additional documents are required for the purchase, they must be sent directly to the pension fund (and not via the application).
Thus, there is no API to upload documents.
## Feedback to the Insured Person
In many cases, the application validation is not fully automated and not immediately done. Instead, it can last hours or even days.
Once the result is ready, the insured person should be notified. The pension fund uses direct communication channels (email, short
text messages, phone calls etc.) for this purpose.
If an application has a communication channel to the insured person, it can regularly poll if the state of the purchase application
has changed and notify the person about changes. Such a channel is voluntary and in addition to the direct communication between
pension fund and insured person.
## Payments
Once the voluntary purchase has been approved, the amount can paid in one four ways:
- **Single payment using a payment slip (QR bill)**: The pension fund provides the payment details (address,
account number, reference number etc.) via API to the application used by the insured person. He/she makes
a payment using the provided data.
- **Single payment by eBill**: The pension fund sends an eBill to the insured person's eBill account.
The insured person provides the eBill email address via the API to the pension fund.
- **Periodic payments by eBill**: The insured person chooses a payment periodicity, which is sent
to the pension fund via the API. The pension fund will later send an eBill for each payment to
the insured person's eBill account.
- **Irregular payments using a payment slip (QR bill)**: The pension fund provides the payment details (address,
account number, reference number etc.) via API to the application. The application then triggers payments
(e.g. via an E-Banking-API). All payments use the same reference number.
A pension fund does not need to support a four payment methods. An application can query the supported methods
with an API call.
## 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
# yamllint enable rule:indentiation
# yamllint enable rule:line-length
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: simulation
description: Simulations of salary changes and voluntary purchases.
- name: purchase
description: Voluntary purchase operations.
- name: transactions
description: Retirement capital transactions.
security:
- bearerAuthentication: []
paths:
/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:
- in: path
name: personId
required: true
schema:
$ref: '#/components/schemas/PersonId'
description: Technical person ID.
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'
/insured-persons/{personId}/statements:
post:
summary: Get pension statement(s) data
description: >
Provides the pension statement(s) representing the state of the policy/policies for
the specified date (or most recent regular/official statement(s) when date not given)
as structured data.
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:
- in: path
name: personId
required: true
schema:
$ref: '#/components/schemas/PersonId'
description: Technical person ID.
requestBody:
description: Reference date for information in output
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/ReferenceDate'
responses:
'200':
description: Statement details
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PensionStatementBasic'
'400':
$ref: '#/components/responses/standard400'
'401':
$ref: '#/components/responses/standard401'
'404':
$ref: '#/components/responses/standard404'
/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:
- in: path
name: pensionStatementId
required: true
schema:
$ref: '#/components/schemas/PensionStatementId'
description: Technical pension statement ID.
responses:
'200':
description: Binary PDF data of the pension statement
content:
application/pdf:
schema:
type: string
contentEncoding: binary
'401':
$ref: '#/components/responses/standard401'
'404':
$ref: '#/components/responses/standard404'
/statements/{pensionStatementId}/statement-for-qr-code:
get:
summary: Get the pension statement QR code json for the specified id
description: |
Provides the pension statement for the specified id as a compact json
in the insured person's preferred language. This json has the same content
and structure as defined in the PensionStatementBasic schema. Its sole purpose
is to provide a compact json so it can be fit into a QR code. This endpoint
should not be used otherwise and will be deprecated once the QR code is no
longer needed.
If the pension fund is unable to provide a json for the request id, the error
code 400 should be returned.
operationId: getPensionStatementQrCodeJson
tags:
- statement
parameters:
- in: path
name: pensionStatementId
required: true
schema:
$ref: '#/components/schemas/PensionStatementId'
description: Technical pension statement ID.
responses:
'200':
description: Compact statement details
content:
application/json:
schema:
type: object
description: Basic, reduced pension statement consisting of only the most important information in compact form for QR code.
required:
- pi
- e
- pp
- rd
- pst
- ppl
- ora
- era
- sd
- rc
- rb
- f
- rpm
- hoaw
properties:
psi:
$ref: '#/components/schemas/PensionStatementId'
pi:
$ref: '#/components/schemas/PersonId'
e:
type: object
description: Details of the insured person's employer.
required:
- en
properties:
ei:
$ref: '#/components/schemas/EmployerId'
en:
$ref: '#/components/schemas/EmployerName'
in:
$ref: '#/components/schemas/Industry'
pp:
type: object
description: Pension provider (foundation) administering the policy.
required:
- ppn
properties:
ppi:
$ref: '#/components/schemas/ProviderId'
ppn:
$ref: '#/components/schemas/ProviderName'
ppa:
type: object
description: Postal address of the pension provider.
properties:
st:
$ref: '#/components/schemas/Street'
pbo:
$ref: '#/components/schemas/PoBox'
to:
$ref: '#/components/schemas/Town'
pc:
$ref: '#/components/schemas/PostalCode'
cc:
$ref: '#/components/schemas/CountryCode'
pu:
$ref: '#/components/schemas/PortalUrl'
pn:
$ref: '#/components/schemas/PortalName'
psn:
$ref: '#/components/schemas/PensionStatementNo'
rd:
$ref: '#/components/schemas/Date'
description: Reference date of pension statement.
pst:
$ref: '#/components/schemas/PensionStatementType'
ed:
$ref: '#/components/schemas/Date'
description: Entry date into the pension fund.
ppl:
type: array
description: List of related pension plans.
items:
type: object
required:
- pln
properties:
pli:
$ref: '#/components/schemas/PlanId'
pln:
$ref: '#/components/schemas/PlanName'
ospn:
$ref: '#/components/schemas/OptionalSavingsPlanName'
ora:
type: integer
format: int32
description: Age (in month since birth) for ordinary retirement.
examples:
- 780
era:
type: integer
format: int32
description: Age (in month since birth) for earliest possible retirement.
examples:
- 696
sd:
type: object
description: Details of salary relevant for insurance.
required:
- ds
- ism
- isre
- isri
- el
properties:
ds:
$ref: '#/components/schemas/DeclaredSalary'
bo:
$ref: '#/components/schemas/Bonus'
as:
$ref: '#/components/schemas/AdditionalSalary'
osc:
$ref: '#/components/schemas/OtherSalaryComponent'
ism:
$ref: '#/components/schemas/InsuredSalaryMandatory'
isre:
$ref: '#/components/schemas/InsuredSalaryRetirement'
isri:
$ref: '#/components/schemas/InsuredSalaryRisk'
el:
$ref: '#/components/schemas/EmploymentLevel'
rc:
type: object
description: Retirement capital balances for the past and projections for the future.
required:
- brd
- bmr
- prb
properties:
tc:
$ref: '#/components/schemas/TransferredCapital'
tcm:
$ref: '#/components/schemas/TransferredCapitalMandatory'
brd:
$ref: '#/components/schemas/BalanceReferenceDate'
bmr:
$ref: '#/components/schemas/BalanceMandatoryReferenceDate'
bec:
$ref: '#/components/schemas/BalanceEndCurrentYear'
bmc:
$ref: '#/components/schemas/BalanceMandatoryEndCurrentYear'
prb:
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:
type: object
required:
- ra
- cb
- cbm
- p
properties:
ra:
$ref: '#/components/schemas/RetirementAge'
cb:
$ref: '#/components/schemas/CapitalBalance'
cbm:
$ref: '#/components/schemas/CapitalBalanceMandatory'
cbni:
$ref: '#/components/schemas/CapitalBalanceNoInterest'
cbnim:
$ref: '#/components/schemas/CapitalBalanceNoInterestMandatory'
p:
$ref: '#/components/schemas/Pension'
crm:
$ref: '#/components/schemas/ConversionRateMandatory'
crs:
$ref: '#/components/schemas/ConversionRateSupplementary'
cre:
$ref: '#/components/schemas/ConversionRateEnveloping'
ir:
type: object
description: A set of interest rates.
properties:
irms:
$ref: '#/components/schemas/InterestRate'
description: Saving interest rate for mandatory coverage (in percent).
examples:
- 6.800
irss:
$ref: '#/components/schemas/InterestRate'
description: Saving interest rate for supplementary coverage (in percent).
examples:
- 5.500
ires:
$ref: '#/components/schemas/InterestRate'
description: Saving enveloping interest rate for combined mandatory and supplementary coverage (in percent).
examples:
- 6.300
irme:
$ref: '#/components/schemas/InterestRate'
description: Interest rate for mandatory coverage (in percent), used specifically in purchase calculations.
examples:
- 6.800
irse:
$ref: '#/components/schemas/InterestRate'
description: Interest rate for supplementary coverage (in percent), used specifically in purchase calculations.
examples:
- 5.500
iree:
$ref: '#/components/schemas/InterestRate'
description: >
Enveloping interest rate for combined mandatory and supplementary coverage (in percent),
used specifically in purchase calculations.
examples:
- 6.300
irmp:
$ref: '#/components/schemas/InterestRate'
description: >
Projection rate for mandatory coverage (in percent),
used specifically for calculating projected future values.
examples:
- 6.800
irsp:
$ref: '#/components/schemas/InterestRate'
description: >
Projection rate for supplementary coverage (in percent),
used specifically for calculating projected future values.
examples:
- 5.500
irep:
$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.300
rb:
type: object
description: Benefits in case of death or disability to work.
required:
- pd
- cpd
- ppd
- opd
- mlswpb
properties:
pd:
$ref: '#/components/schemas/PensionDisability'
cpd:
$ref: '#/components/schemas/ChildPensionDisability'
ppd:
$ref: '#/components/schemas/PartnerPensionDeath'
opd:
$ref: '#/components/schemas/OrphanPensionDeath'
lswpb:
$ref: '#/components/schemas/LumpSumWithoutPensionBenefits'
mlswpb:
$ref: '#/components/schemas/MinimalLumpSumWithPensionBenefits'
f:
type: object
description: Contributions for financing the policy.
required:
- fcsip
- fcse
properties:
fcsip:
$ref: '#/components/schemas/ContributionSavingsInsuredPerson'
fcse:
$ref: '#/components/schemas/ContributionSavingsEmployer'
fcrip:
$ref: '#/components/schemas/ContributionRiskInsuredPerson'
fcre:
$ref: '#/components/schemas/ContributionRiskEmployer'
fcaip:
$ref: '#/components/schemas/ContributionAdministrationInsuredPerson'
fcae:
$ref: '#/components/schemas/ContributionAdministrationEmployer'
rpm:
$ref: '#/components/schemas/RegularPurchaseMaxAmount'
hoaw:
$ref: '#/components/schemas/HomeOwnershipAvailableForWithdrawal'
'401':
$ref: '#/components/responses/standard401'
'404':
$ref: '#/components/responses/standard404'
/policies/{policyId}:
get:
summary: Get details of a pension fund policy
description: >
Provides extensive 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:
- in: path
name: policyId
required: true
schema:
$ref: '#/components/schemas/PolicyId'
description: Technical policy ID.
responses:
'200':
description: Policy details
content:
application/json:
schema:
$ref: '#/components/schemas/Policy'
'401':
$ref: '#/components/responses/standard401'
'404':
$ref: '#/components/responses/standard404'
/policies/{policyId}/salary-change-simulation:
post:
summary: Simulate effects of salary and employment level change
description: >
Simulates the effects of a salaray and/or employment level change on contributions
and prospective retirement benefits. Prospective retirements benefits are calculated
for retirement at the regular age as well as for multiple early retirement ages.
operationId: simulateSalaryChange
tags:
- simulation
parameters:
- in: path
name: policyId
required: true
schema:
$ref: '#/components/schemas/PolicyId'
description: Policy ID.
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/SalaryChangeSimResult'
'401':
$ref: '#/components/responses/standard401'
'404':
$ref: '#/components/responses/standard404'
/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:
- in: path
name: policyId
required: true
schema:
$ref: '#/components/schemas/PolicyId'
description: Policy ID.
requestBody:
description: Voluntary purchase simulation parameters
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SimulationParameters'
responses:
'200':
description: Simulation result
content:
application/json:
schema:
$ref: '#/components/schemas/SimulationResult'
'401':
$ref: '#/components/responses/standard401'
'404':
$ref: '#/components/responses/standard404'
/policies/{policyId}/purchases/template:
get:
summary: Retrieves a purchase request template
description: >
The template purchase request serves to retrieve the configuration
and intial values for a new purchase request.
operationId: getTemplatePurchaseRequest
tags:
- purchase
parameters:
- in: path
name: policyId
required: true
schema:
$ref: '#/components/schemas/PolicyId'
description: Policy ID.
responses:
'200':
description: Purchase request with configuration and initial values
content:
application/json:
schema:
$ref: '#/components/schemas/PurchaseRequest'
'401':
$ref: '#/components/responses/standard401'
'404':
$ref: '#/components/responses/standard404'
/policies/{policyId}/purchases:
get:
summary: Query all purchase requests
description: >