riskine

API Documentation


Welcome to the English documentation of the riskine API! In the following, the functionality of the riskine API and the structure of its resource will be described in general and also service by service.

This document describes the "vanilla" services. However the behaviour of the services are subject to change due to requirements stemming from our mutual project. Each client will be provided an own subdomain under which the customized services are available. For example, the insurance product universe subject to the calculations behind the service /productgroups/prioritization may be adopted to your in-house product universe.

Finally, there are several services in development which are briefly described in the end.

Contents


General


The services are hosted at https://api.riskine.com/<servicename> and the respective test-stage services are hosted at https://work.riskine.com/<servicename>. Please see detailed description of the services below. Some points to consider are:

This is a schematic overview of the service structure for the private customer main services:

api-schematic-overview

Country and language customization


For country customization we parameterize all services via a country parameter. Currently supported countries are Germany (de), Austria (at), Switzerland (ch) and Spain (es, under development). Different languages (for text content) are managed via the URL parameter culture with the usual values en, de, en-US, de-AT, etc.

Authentication


The basic flow of authentication is the following:

  1. When becoming a customer of the riskine API, you are supplied with a username and password
  2. On sending a GET-request containing the username and credentials in form of a Basic Authentication header /gettoken you will receive an API token (a JSON web token)
  3. When accessing any of the other services, the API token has to be included in the Authorization header in the form * Authorization = BEARER <API token>
  4. When failing to authorize, any of the other services send a 401
  5. The API token is valid for 2 weeks, users can generate as many keys as they like using their credentials

API Resource


This section describes the generic API input resource. The API resource models a person via individual parameters like age and sex as well as risk parameters like location of their home. All parameters currently known to the riskine API are described by name and content in the following table, respectively JSON schema:

Parametername Description Example
person.name.first First name John
person.name.last Last name Doe
person.age Age in years 27
person.birthdate Date of birth '1989-10-22'
person.gender Gender. 1: male, 2:female 2
person.education.level Highest educational attainment/Höchste abgeschlossene Ausbildung. 1: Mandatory school, 2: Apprenticeship, 3: High school diploma, 4: University degree, 5: Middle school, 6: Secondary school (Realschule) certificate 3
person.address.region County id 9
person.address.postcode Post code of the persons home 1010
person.address.city Home Town 'Wien'
person.address.street Street name 'Riemergasse'
person.address.housenumber Street or house number '11a'
person.sport.habit Sport habit. 1: yes, regularly, 2: yes, rarely, 3: no 1
person.health.smoke.habit.one Smoking habit. 1: yes, regularly, 2: yes, rarely, 3: no, 4: I don´t want to tell 2
person.family.partner Family status. 1: single, 2: married/in a civil union, 3: divorced, 4: widowed, 5: in a relationship, 9: other 1
person.family.incomedepending Income dependent persons. Array. 1: partner, 2: 1 child, 3: 2 children, 4: 3 children, 5: more than 3 children, 6: none, 7: other person [1,3]
object.vehicle.type Type of vehicle in use. Array. 999: sonstige, ANH: anhänger, KRA: kraftrad, LKW: lastkraftwagen, MOP: motorfahrrad, OMN: omnibus, PKW: personenkraftwagen, PRO: probekennzeichen, SON: sonderfahrzeuge, ZUG: zugmaschine, kein: none ['PKW,'MOP']
object.vehicle.value Sum of the values of vehicles in EUR 12400
object.animal.type.select Specification of pets. 1: at least one dog, 2: others, 3: none 1
object.home.type Type of home. 1: rented flat, 2: rented house, 3: own flat, 4: own house, 5: with parents/partner 1
object.home.size.total Size of home in square meters 98
object.home.niveau Niveau of home and interior. 1: simple, 2: standard, 3: luxurious, 4: unknown 2
person.work.professiontype Type of job. 1: labourer, 2: self-employed, 3: farmer, 5: public sector employee, 7: student, 8: housewife/-husband, 9: unemployed, 10: retired, 11: on (maternity) leave, 12: apprentice, 13: employee 2
person.work.income.net Net monthly income in EUR 1748.65
person.work.income.gross Gross monthly income in EUR 2500
person.statebenefits.pension.months Number of months counting towards pension/SV-Monate 143
person.statebenefits.pension.sum Pension account in EUR 10345.32
person.statebenefits.pension.year Year of Pensionkonto information 2016
person.partner.birthdate Date of birth partner '1993-02-23'
person.partner.age Age of partner in years 23
person.family.marriage.duration Duration of marriage in years 3
person.partner.work.income.gross Gross monthly income of partner 2700
person.partner.work.income.net Net monthly income of partner 1500
person.family.children.common Is there a common child with the partner? 1: yes, 2: no 2
person.statebenefits.pension.wageincrease Expected p.a. mean inrease in incomes across the country in percent. Will be preset by riskine 1.7
person.statebenefits.pension.professionaldevelopment Expected p.a. increase of own income in percent. Will default to 0 1.5
person.statebenefits.pension.interestpresentvalues Interest for present value for calculation of pension. Will be prefilled. 1748.65
person.statebenefits.pension.pensiongap.percentclosed Which part in percent should the net pension plus the bonus annuity make up of the last net income? 85
inflation Expected p.a. inflation during the saving period in percent. Will be preset by riskine 2.17
organization.farm.management manage farm 1: alone, 2: with spouse 1
person.children Definition of income dependent children. Array. Each should be of the form [Date, 1/0 for lives at home/does not live at home, 1/0 for in education/not in education] [['2008-03-19',1,1],['1994-01-12',0,1]]
country de: Germany, at: Austria, ch:Switzerland at
contract.payment.method Frequency of premium payment, '12': Monthly, '4': Quarterly, '2': Six-monthly 12
contract.premium Amount of the premium 100
contract.surcharge Amount of the installment surcharge 5
contract.car.premium Amount of the engine-related insurance tax 100
person.health.healthcare.preferences the importance of private helathcare. 1: short waiting periods, 2: free choise of doctors, 3: access to the second opinion, 4: modern furnishing and high standarts, '5': none Array
person.investment.financialsecurity.preferences the improtance of the financial security. 1: high rate of substitution, 2: to continue the usual lifestyle, 3: playing golf and traveling or staying at home and watching TV, 4: financial independence of family or children, '5': none Array
person.work.selfemployed.owner Do you own a small store: 1: Yes, 2: No 1
person.asset.corporatepension.employer.sum currently value of pension account 1000
person.asset.corporatepension.benefitssum amount of additional pension pension commitments 10000
contract.pension.additionalprovision.years years of additional tax-free provision 20
contract.pension.producttype type of live insurance product: 1: classic, 2: unit-linked, 3: state 10000
contract.pension.valuetotal currently value of live insurance 10000
contract.pension.yearlysum annual premium for live insurance 1000
contract.pension.insured.remaining remaining contract period of live insurance 20
person.asset.severancesystem.type Severance old or new: 1: old, 2:new 1
person.asset.severancesystem.amount wie hoch ist der kummulierte Wert Ihrer Abfertigungsansprüche 10000
person.work.employer.years Wie viele Berufsjahre arbeiten Sie bei Ihrer aktuellen Firma? 60
person.work.employer.yearsplanned Wie viele Jahre planen Sie in etwa noch bei diesem Unternehmen zu bleiben? 60
person.work.employer.pension Nehmen Sie an, dass Sie bis zu Ihrem Pensionsantritt bei diesem Arbeitsgeber bleiben?: 1:Nein, 2:Ja 1
person.work.income.additional.sum Amount of additional income of a pensioner 0
person.asset.corporatepension.employer.yearlysum Yearly amount of contributions to the additional pension 0
person.statebenefits.pension.additional.sum Pension account of additional penison 0
person.statebenefits.pension.additional.paymenttype Paymenttype of the additional pension, 1:one time, 2:yearly 1
person.statebenefits.pension.additional.desiredsum Amount of contributions to the additional pension 0
person.work.income.gross.yearly Gross yearly income in EUR 28000
object.valuables.type valuables to be insured: 1: tablet, 2: smartphone, 3:digital camera, 4: notebook, 5: none ``
lon The longitude of the geopoint you are interested in (EPSG 4326) 15.558229
lat The latitude of the geopoint you are interested in (EPSG 4326) 46.758571
organization.sector The ID of the sector A1
organization.address.city location of the business Wien
organization.employee.number number of employees in total 29
organization.property.type items owned by the company. 1: Cars, 2:Maschines, 3:Computers/Laptops, 4:Building/Real Estate, 5:Stocks, 6:owned or rented office, 7:electronic tools [1,3,5]
organization.business.processes.digital exposure to cyber risks [1,2,3]
organization.type type of legal entity. 1: GmbH/private limited, 2:KGaA, 3:AG/public limites, 4:Verein, 5:Selbstständig/Freiberuflich, 6:OG, 7:KG, 8:GesBr, 9:Genossenschaft,10:empty 1
organization.income.turnover.yearly turnover 10000
organization.employee.number.new number of new and active employees since 2003 16
recommendation.corporate-pension.employees.premium amount of pension savings per employee/year [3,5]
recommendation.corporate-pension.director.premium Pension savings relevance for the owner, 1: yes, 2:no 1
recommendation.severance-indemnity.need optimizing employee accruals via insurances. 1: yes, 2:no 1
recommendation.corporate-pension.beneficiaries for whom are pension savings relevant, 1: owner, 2: all/many of the employees, 3: selected key players, 4:no one [2,3]
organization.business.running.director.dependency Additional accident/illness protection for the owner/managing director relevant 1
organization.business.processes.machinery responsible at a building site or transporting goods 1:construction activity, 2:transporting, 3: assembly, 4: none [1]

All of the information in the above table was generated from the following JSON schema, which is also used internally for validation purposes:

{
    "properties": {
        "person.name.first": {
            "type": "string",
            "description": "First name",
            "examples": [
                "John"
            ]
        },
        "person.name.last": {
            "type": "string",
            "description": "Last name",
            "examples": [
                "Doe"
            ]
        },
        "person.age": {
            "$ref": "#/definitions/age",
            "description": "Age in years",
            "examples": [
                27
            ]
        },
        "person.birthdate": {
            "$ref": "#/definitions/date",
            "description": "Date of birth",
            "examples": [
                "'1989-10-22'"
            ]
        },
        "person.gender": {
            "enum": [
                1,
                2
            ],
            "description": "Gender. `1`: male, `2`:female",
            "examples": [
                2
            ]
        },
        "person.education.level": {
            "enum": [
                1,
                2,
                3,
                4,
                5,
                6
            ],
            "description": "Highest educational attainment/Höchste abgeschlossene Ausbildung.  `1`: Mandatory school, `2`: Apprenticeship, `3`: High school diploma, `4`: University degree, `5`: Middle school, `6`: Secondary school (Realschule) certificate",
            "examples": [
                3
            ]
        },
        "person.address.region": {
            "description": "County id",
            "examples": [
                9
            ]
        },
        "person.address.postcode": {
            "$ref": "#/definitions/postcode",
            "description": "Post code of the persons home",
            "examples": [
                1010
            ]
        },
        "person.address.city": {
            "type": "string",
            "description": "Home Town",
            "examples": [
                "'Wien'"
            ]
        },
        "person.address.street": {
            "type": "string",
            "description": "Street name",
            "examples": [
                "'Riemergasse'"
            ]
        },
        "person.address.housenumber": {
            "type": "string",
            "description": "Street or house number",
            "examples": [
                "'11a'"
            ]
        },
        "person.sport.habit": {
            "enum": [
                1,
                2,
                3,
                4
            ],
            "description": "Sport habit. `1`: yes, regularly, `2`: yes, rarely, `3`: no",
            "examples": [
                1
            ]
        },
        "person.health.smoke.habit.one": {
            "enum": [
                1,
                2,
                3,
                4
            ],
            "description": "Smoking habit. `1`: yes, regularly, `2`: yes, rarely, `3`: no, `4`: I don´t want to tell",
            "examples": [
                2
            ]
        },
        "person.family.partner": {
            "enum": [
                1,
                2,
                3,
                4,
                5,
                9
            ],
            "description": "Family status. `1`: single, `2`: married/in a civil union, `3`: divorced, `4`: widowed, `5`: in a relationship, `9`: other",
            "examples": [
                1
            ]
        },
        "person.family.incomedepending": {
            "type": "array",
            "minItems": 1,
            "items": {
                "enum": [
                    1,
                    2,
                    3,
                    4,
                    5,
                    6,
                    7
                ]
            },
            "description": "Income dependent persons. Array. `1`: partner, `2`: 1 child, `3`: 2 children, `4`: 3 children, `5`: more than 3 children, `6`: none, `7`: other person",
            "examples": [
                "[1,3]"
            ]
        },
        "object.vehicle.type": {
            "type": "array",
            "items": {
                "enum": [
                    "999",
                    "ANH",
                    "KRA",
                    "LKW",
                    "MOP",
                    "OMN",
                    "PKW",
                    "PRO",
                    "SON",
                    "ZUG",
                    "BOOT",
                    "kein"
                ]
            },
            "description": "Type of vehicle in use. Array. `999`: sonstige, `ANH`: anhänger, `KRA`: kraftrad, `LKW`: lastkraftwagen, `MOP`: motorfahrrad, `OMN`: omnibus, `PKW`: personenkraftwagen, `PRO`: probekennzeichen, `SON`: sonderfahrzeuge, `ZUG`: zugmaschine, `kein`: none",
            "examples": [
                "['PKW,'MOP']"
            ]
        },
        "object.vehicle.value": {
            "$ref": "#/definitions/nonnegative",
            "description": "Sum of the values of vehicles in EUR",
            "examples": [
                12400
            ]
        },
        "object.animal.type.select": {
            "enum": [
                1,
                2,
                3
            ],
            "description": "Specification of pets. `1`: at least one dog, `2`: others, `3`: none",
            "examples": [
                1
            ]
        },
        "object.home.type": {
            "enum": [
                1,
                2,
                3,
                4,
                5
            ],
            "description": "Type of home. `1`: rented flat, `2`: rented house, `3`: own flat, `4`: own house, `5`: with parents/partner",
            "examples": [
                1
            ]
        },
        "object.home.size.total": {
            "$ref": "#/definitions/nonnegative",
            "description": "Size of home in square meters",
            "examples": [
                98
            ]
        },
        "object.home.niveau": {
            "enum": [
                1,
                2,
                3,
                4
            ],
            "description": "Niveau of home and interior. `1`: simple, `2`: standard, `3`: luxurious, `4`: unknown",
            "examples": [
                2
            ]
        },
        "person.work.professiontype": {
            "enum": [
                1,
                2,
                3,
                5,
                7,
                8,
                9,
                10,
                11,
                12,
                13
            ],
            "description": "Type of job. `1`: labourer, `2`: self-employed, `3`: farmer, `5`: public sector employee, `7`: student, `8`: housewife/-husband, `9`: unemployed, `10`: retired, `11`: on (maternity) leave, `12`: apprentice, `13`: employee",
            "examples": [
                2
            ]
        },
        "person.work.income.net": {
            "$ref": "#/definitions/nonnegative",
            "description": "Net monthly income in EUR",
            "examples": [
                1748.65
            ]
        },
        "person.work.income.gross": {
            "$ref": "#/definitions/nonnegative",
            "description": "Gross monthly income in EUR",
            "examples": [
                2500
            ]
        },
        "person.statebenefits.pension.months": {
            "$ref": "#definitions/nonnegative",
            "description": "Number of months counting towards pension/SV-Monate",
            "examples": [
                143
            ]
        },
        "person.statebenefits.pension.sum": {
            "$ref": "#definitions/nonnegative",
            "description": "Pension account in EUR",
            "examples": [
                10345.32
            ]
        },
        "person.statebenefits.pension.year": {
            "$ref": "#/definitions/pension.year",
            "description": "Year of Pensionkonto information",
            "examples": [
                2016
            ]
        },
        "person.partner.birthdate": {
            "$ref": "#/definitions/date",
            "description": "Date of birth partner",
            "examples": [
                "'1993-02-23'"
            ]
        },
        "person.partner.age": {
            "$ref": "#/definitions/age",
            "description": "Age of partner in years",
            "examples": [
                23
            ]
        },
        "person.family.marriage.duration": {
            "$ref": "#definitions/nonnegative",
            "description": "Duration of marriage in years",
            "examples": [
                3
            ]
        },
        "person.partner.work.income.gross": {
            "$ref": "#definitions/nonnegative",
            "description": "Gross monthly income of partner",
            "examples": [
                2700
            ]
        },
        "person.partner.work.income.net": {
            "$ref": "#definitions/nonnegative",
            "description": "Net monthly income of partner",
            "examples": [
                1500
            ]
        },
        "person.family.children.common": {
            "enum": [
                1,
                0
            ],
            "description": "Is there a common child with the partner? `1`: yes, `2`: no",
            "examples": [
                2
            ]
        },
        "person.statebenefits.pension.wageincrease": {
            "$ref": "#/definitions/percent",
            "description": "Expected p.a. mean inrease in incomes across the country in percent. Will be preset by __riskine__",
            "examples": [
                1.7
            ]
        },
        "person.statebenefits.pension.professionaldevelopment": {
            "$ref": "#/definitions/percent",
            "description": "Expected p.a. increase of own income in percent. Will default to `0`",
            "examples": [
                1.5
            ]
        },
        "person.statebenefits.pension.interestpresentvalues": {
            "$ref": "#/definitions/percent",
            "description": "Interest for present value for calculation of pension. Will be prefilled.",
            "examples": [
                1748.65
            ]
        },
        "person.statebenefits.pension.pensiongap.percentclosed": {
            "$ref": "#/definitions/percent",
            "description": "Which part in percent should the net pension plus the bonus annuity make up of the last net income?",
            "examples": [
                85
            ]
        },
        "inflation": {
            "$ref": "#/definitions/percent",
            "description": "Expected p.a. inflation during the saving period in percent. Will be preset by __riskine__",
            "examples": [
                2.17
            ]
        },
        "organization.farm.management": {
            "enum": [
                1,
                2
            ],
            "description": "manage farm 1: alone, 2: with spouse",
            "examples": [
                1
            ]
        },
        "person.children": {
            "$ref": "#/definitions/children",
            "description": "Definition of income dependent children. Array. Each should be of the form `[Date, 1/0 for lives at home/does not live at home, 1/0 for in education/not in education]`",
            "examples": [
                "[['2008-03-19',1,1],['1994-01-12',0,1]]"
            ]
        },
        "country": {
            "type": "string",
            "description": "`de`: Germany, `at`: Austria, `ch`:Switzerland",
            "enum": [
                "de",
                "at",
                "ch",
                "es"
            ],
            "examples": [
                "at"
            ]
        },
        "contract.payment.method": {
            "enum": [
                12,
                4,
                2
            ],
            "description": "Frequency of premium payment, '12': Monthly, '4': Quarterly, '2': Six-monthly",
            "examples": [
                12
            ]
        },
        "contract.premium": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000,
            "description": "Amount of the premium",
            "examples": [
                100
            ]
        },
        "contract.surcharge": {
            "type": "number",
            "minimum": 0,
            "maximum": 10,
            "description": "Amount of the installment surcharge",
            "examples": [
                5
            ]
        },
        "contract.car.premium": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000,
            "description": "Amount of the engine-related insurance tax",
            "examples": [
                100
            ]
        },
        "person.health.healthcare.preferences": {
            "type": "array",
            "minItems": 1,
            "items": {
                "enum": [
                    1,
                    2,
                    3,
                    4,
                    5
                ],
                "type": "integer"
            },
            "description": "the importance of private helathcare. `1`: short waiting periods, `2`: free choise of doctors, `3`: access to the second opinion, `4`:  modern furnishing and high standarts, '5': none",
            "examples": [
                [
                    1
                ],
                [
                    2,
                    3
                ],
                [
                    4
                ]
            ]
        },
        "person.investment.financialsecurity.preferences": {
            "type": "array",
            "minItems": 1,
            "items": {
                "enum": [
                    1,
                    2,
                    3,
                    4,
                    5
                ],
                "type": "integer"
            },
            "description": "the improtance of the financial security. `1`: high rate of substitution, `2`: to continue the usual lifestyle, `3`: playing golf and traveling or staying at home and watching TV, `4`:  financial independence of family or children, '5': none",
            "examples": [
                [
                    1
                ],
                [
                    2,
                    3
                ],
                [
                    4
                ]
            ]
        },
        "person.work.selfemployed.owner": {
            "enum": [
                1,
                2
            ],
            "description": "Do you own a small store: 1: Yes, 2: No",
            "examples": [
                1
            ]
        },
        "person.asset.corporatepension.employer.sum": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000,
            "description": "currently value of pension account",
            "examples": [
                1000
            ]
        },
        "person.asset.corporatepension.benefitssum": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000,
            "description": "amount of additional pension pension commitments",
            "examples": [
                10000
            ]
        },
        "contract.pension.additionalprovision.years": {
            "type": "integer",
            "minimum": 0,
            "maximum": 80,
            "description": "years of additional tax-free provision",
            "examples": [
                20
            ]
        },
        "contract.pension.producttype": {
            "enum": [
                1,
                2,
                3
            ],
            "description": "type of live insurance product: 1: classic, 2: unit-linked, 3: state ",
            "examples": [
                10000
            ]
        },
        "contract.pension.valuetotal": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000,
            "description": "currently value of live insurance",
            "examples": [
                10000
            ]
        },
        "contract.pension.yearlysum": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000,
            "description": "annual premium for live insurance",
            "examples": [
                1000
            ]
        },
        "contract.pension.insured.remaining": {
            "type": "integer",
            "minimum": 0,
            "maximum": 60,
            "description": "remaining contract period of live insurance",
            "examples": [
                20
            ]
        },
        "person.asset.severancesystem.type": {
            "enum": [
                1,
                2
            ],
            "description": "Severance old or new: 1: old, 2:new",
            "examples": [
                1
            ]
        },
        "person.asset.severancesystem.amount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000,
            "description": "wie hoch ist der kummulierte Wert Ihrer Abfertigungsansprüche",
            "examples": [
                10000
            ]
        },
        "person.work.employer.years": {
            "type": "integer",
            "minimum": 0,
            "maximum": 60,
            "description": "Wie viele Berufsjahre arbeiten Sie bei Ihrer aktuellen Firma?",
            "examples": [
                60
            ]
        },
        "person.work.employer.yearsplanned": {
            "type": "integer",
            "minimum": 0,
            "maximum": 60,
            "description": "Wie viele Jahre planen Sie in etwa noch bei diesem Unternehmen zu bleiben?",
            "examples": [
                60
            ]
        },
        "person.work.employer.pension": {
            "enum": [
                1,
                2
            ],
            "description": "Nehmen Sie an, dass Sie bis zu Ihrem Pensionsantritt bei diesem Arbeitsgeber bleiben?: 1:Nein, 2:Ja",
            "examples": [
                1
            ]
        },
        "person.work.income.additional.sum": {
            "type": "integer",
            "description": "Amount of additional income of a pensioner",
            "examples": [
                0
            ]
        },
        "person.asset.corporatepension.employer.yearlysum": {
            "type": "integer",
            "description": "Yearly amount of contributions to the additional pension",
            "examples": [
                0
            ]
        },
        "person.statebenefits.pension.additional.sum": {
            "type": "integer",
            "description": "Pension account of additional penison",
            "examples": [
                0
            ]
        },
        "person.statebenefits.pension.additional.paymenttype": {
            "enum": [
                1,
                2
            ],
            "description": "Paymenttype of the additional pension, 1:one time, 2:yearly",
            "examples": [
                1
            ]
        },
        "person.statebenefits.pension.additional.desiredsum": {
            "type": "integer",
            "description": "Amount of contributions to the additional pension",
            "examples": [
                0
            ]
        },
        "person.work.income.gross.yearly": {
            "type": "integer",
            "description": "Gross yearly income in EUR",
            "examples": [
                28000
            ]
        },
        "object.valuables.type": {
            "type": "array",
            "minItems": 1,
            "items": {
                "enum": [
                    1,
                    2,
                    3,
                    4
                ],
                "type": "integer"
            },
            "description": "valuables to be insured: 1: tablet, 2: smartphone, 3:digital camera, 4: notebook, 5: none "
        },
        "lon": {
            "type": "number",
            "description": "The longitude of the geopoint you are interested in (EPSG 4326)",
            "examples": [
                15.5582290
            ]
        },
        "lat": {
            "type": "number",
            "description": "The latitude of the geopoint you are interested in (EPSG 4326)",
            "examples": [
                46.7585710
            ]
        },
        "organization.sector": {
            "type": "string",
            "description": "The ID of the sector",
            "examples": [
                "A1"
            ]
        },
        "organization.address.city": {
            "type": "integer",
            "description": "location of the business",
            "examples": [
                "Wien"
            ]
        },
        "organization.employee.number": {
            "type": "integer",
            "description": "number of employees in total",
            "examples": [
                29
            ]
        },
        "organization.property.type": {
            "type": "array",
            "minItems": 0,
            "items": {
                "enum": [
                    1,
                    2,
                    3,
                    4,
                    5,
                    6,
                    7
                ]
            },
            "description": "items owned by the company. `1`: Cars, `2`:Maschines, `3`:Computers/Laptops, `4`:Building/Real Estate, `5`:Stocks, `6`:owned or rented office, `7`:electronic tools",
            "examples": [
                "[1,3,5]"
            ]
        },
        "organization.business.processes.digital": {
            "type": "array",
            "minItems": 1,
            "items": {
                "enum": [
                    1,
                    2,
                    3,
                    4,
                    5
                ]
            },
            "description": "exposure to cyber risks",
            "examples": [
                "[1,2,3]"
            ]
        },
        "organization.type": {
            "enum": [
                1,
                2,
                3,
                4,
                5,
                6,
                7,
                8,
                9,
                10
            ],
            "description": "type of legal entity. `1`: GmbH/private limited, `2`:KGaA, `3`:AG/public limites, `4`:Verein, `5`:Selbstständig/Freiberuflich, `6`:OG, `7`:KG, `8`:GesBr, `9`:Genossenschaft,`10`:empty",
            "examples": [
                1
            ]
        },
        "organization.income.turnover.yearly": {
            "type": "integer",
            "description": "turnover",
            "examples": [
                10000
            ]
        },
        "organization.employee.number.new": {
            "type": "integer",
            "description": "number of new and active employees since 2003",
            "minimum": 0,
            "maximum": 9999999999,
            "examples": [
                16
            ]
        },
        "recommendation.corporate-pension.employees.premium": {
            "type": "array",
            "minItems": 1,
            "items": {
                "enum": [
                    1,
                    2,
                    3,
                    4
                ]
            },
            "description": "amount of pension savings per employee/year",
            "examples": [
                "[3,5]"
            ]
        },
        "recommendation.corporate-pension.director.premium": {
            "enum": [
                1,
                2
            ],
            "description": "Pension savings relevance for the owner, `1`: yes, `2`:no",
            "examples": [
                1
            ]
        },
        "recommendation.severance-indemnity.need": {
            "enum": [
                1,
                2
            ],
            "description": "optimizing employee accruals via insurances. `1`: yes, `2`:no",
            "examples": [
                1
            ]
        },
        "recommendation.corporate-pension.beneficiaries": {
            "type": "array",
            "minItems": 1,
            "items": {
                "enum": [
                    1,
                    2,
                    3,
                    4
                ]
            },
            "description": "for whom are pension savings relevant, `1`: owner, `2`: all/many of the employees, `3`: selected key players, `4`:no one",
            "examples": [
                "[2,3]"
            ]
        },
        "organization.business.running.director.dependency": {
            "type": "integer",
            "enum": [
                1,
                2
            ],
            "description": "Additional accident/illness protection for the owner/managing director relevant",
            "examples": [
                1
            ]
        },
        "organization.business.processes.machinery": {
            "type": "array",
            "minItems": 1,
            "items": {
                "enum": [
                    1,
                    2,
                    3,
                    4,
                    5
                ]
            },
            "description": "responsible at a building site or transporting goods `1`:construction activity, `2`:transporting, `3`: assembly, `4`: none",
            "examples": [
                "[1]"
            ]
        }
    },
    "type": "object",
    "definitions": {
        "age": {
            "type": "integer",
            "minimum": 0,
            "maximum": 120
        },
        "date": {
            "type": "string",
            "pattern": "^\\d\\d\\d\\d-\\d\\d-\\d\\d$"
        },
        "postcode": {
            "type": "integer",
            "minimum": 10,
            "maximum": 99999
        },
        "nonnegative": {
            "type": "number",
            "minimum": 0
        },
        "pension.year": {
            "type": "integer",
            "minimum": 2014,
            "maximum": 2018
        },
        "percent": {
            "type": "number",
            "minimum": 0,
            "maximum": 100
        },
        "children": {
            "type": "array",
            "minItems": 1,
            "items": {
                "type": "object",
                "properties": {
                    "birthdate": {
                        "$ref": "#/definitions/date"
                    },
                    "withparents": {
                        "enum": [
                            1,
                            0
                        ]
                    },
                    "ineducation": {
                        "enum": [
                            1,
                            0
                        ]
                    }
                }
            }
        }
    }
}

Whenever you send data that does not fit the schema, you will receive a response containing one of the following resultcodes:

Result code Description
1 Data type did not validate
2 Parameter content did not validate
3 Problem with parameter dependencies

Note: These error codes will be replaced by fully descriptive messages about where validation went wrong. Implementation is currently in progress.

Services


This section describes functionality as well as schemata of the in- and outputs of the riskine API services. In general, each service imposes its own constraints on the resource structure, representing the required parameters for each service. This way, not every service requires every parameter to be set in the posted data. The obvious exception is the /gettoken service, which only needs a Basic Authentication header to return success.

GET /gettoken


As descriped in the section about Authentication, This service expects only a Basic Authentication header containing your username and password` and returns an API key which you can use to access any of the other services. The API key will be valid for 2 weeks.

Status code Description
200 Success
401 Failed to authenticate

Example result:

POST /productgroups/coverages


As in the service /productgroups/prioritization, this addresses the optimal insurance portfolio and calculates recommended coverages fo certain products. Just like the rest of the riskine API services, the rules and logic behind these calculations as well as the results have been developed in cooperation with and were validated by the expert team at Verein für Konsumenteninformation. As mentioned in the introduction, there may well be the need to adjust the product universe or results during our mutual project.

Possible response status:

Status code Description
200 Success
400 Data not properly specified

Example result:

{
    "returncode": 0,
    "result": {
        "accident-onetimeloss": 150000,
        "accident-incomeloss-total": 162000,
        "accident-incomeloss-monthly": 500,
        "termlife": 0,
        "pension-gap-monthly": 210,
        "pension-gap-yearly": 2940,
        "pension-benefitnet": 1486,
        "savings-lowreturns-constant": 438,
        "savings-lowreturns-dynamic": 266,
        "savings-mediumreturns-constant": 355,
        "savings-mediumreturns-dynamic": 209,
        "savings-highreturns-constant": 226,
        "savings-highreturns-dynamic": 126,
        "household": 115000,
        "cash-reserve": 5100
    }
}

... where the values refer to the following coverages:

response field description
accident-onetimeloss Coverage for one-time damage after an accident (modify home etc)
accident-incomeloss-total Total damage in case of invalidity, summed over the rest of the expected life span spent earning
accident-incomeloss-monthly Monthly loss of income in case of invalidity
termlife Coverage for risk life insurance
pension-gap-monthly net expected pension gap in current worth (monthly)
pension-gap-monthly net expected pension gap in current worth (yearly)
pension-benefitnet net expected pension in current worth
savings-lowreturns-constant needed monthly saving amount to reach desired pension coverage (0.5% p.a. net returns, constant premium)
savings-lowreturns-dynamic needed monthly saving amount to reach desired pension coverage (0.5% p.a. net returns, dynamic premium)
savings-mediumreturns-constant needed monthly saving amount to reach desired pension coverage (2.5% p.a. net returns, constant premium)
savings-mediumreturns-dynamic needed monthly saving amount to reach desired pension coverage (2.5% p.a. net returns, dynamic premium)
savings-highreturns-constant needed monthly saving amount to reach desired pension coverage (5.0% p.a. net returns, constant premium)
savings-highreturns-dynamic needed monthly saving amount to reach desired pension coverage (5.0% p.a. net returns, dynmic premium)
household recommended coverage for household insurance
cash-reserve recommended saved up liquidity

POST /productgroups/prioritization


This service calculates a recommendation ranking for insurance products, based on the risk impact evaluations as in /profile/risks/prioritization. The ranking is discrete, ranging from 3 indicating 'absolutely recommended' down to 0 indicating 'not recommended' (e.g. pet insurance for persons without pets). As mentioned in the introduction, there may well be the need to adjust the product universe during our mutual project.

Possible response status:

Status code Description
200 Success
400 Data not properly specified

Example result:

{
    "returncode": 0,
    "result": {
        "accident": 3,
        "private-liability": 3,
        "landowner-liability": 0,
        "invalidity": 0,
        "car-liability": 0,
        "pension": 1,
        "home": 0,
        "termlife": 0,
        "car-comprehensive": 0,
        "household": 0,
        "legal": 1,
        "car-legal": 0,
        "travel": 1,
        "care": 2,
        "animal-liability": 0,
        "health-private": 1
    }
}

Productgroup list for Austria (can be adjusted during project together with the client)

product description
termlife Term life insurance
outpatient Supplementary health insurance (ambulant)
cash-reserve Liquidity reserve
invalidity Disability insurance
home Home (homeowners insurance)
landowner-liability Landowner liability
household Household insurance
animal-liability Livestock/pet owner liability
car-liability Motor vehicle liability
car-comprehensive Motor vehicle own-damage
car-legal Motor legal protection
inpatient Supplementary health insurance (for hospital)
dailybenefit Daily benefits insurance
care Nursing care insurance
private-liability Private liability
legal Legal protection
travel Travel insurance
accident Accident insurance
pension Private pension insurance

Productgroup list for Germany (can be adjusted during project together with the client)

product description
accident Accident insurance
private-liability Private liability
landowner-liability Landowner liability
invalidity Disability insurance
car-liability Motor vehicle liability
animal-liability Livestock/pet owner liability
life Life insurance 3rd column
home Home (homeowners insurance)
termlife Term life insurance
car-comprehensive Motor vehicle own-damage
household Household insurance
legal Legal protection
dailybenefit Daily benefits insurance
travel Travel insurance
care Nursing care insurance
health-private Private health insurance
health-supplementary Supplementary health insurance
pension-riester Riester pension
pension-rurup Rürup pension
principal-liability Builders liability
health-public Statutory health insurance
invalidity-child Children invalidity insurance
funeral Funeral expense insurance

Productgroup list for Switzerland (can be adjusted during project together with the client)

product description
accident Accident insurance
private-liability Private liability
car Motor vehicle insurance
animal-liability Livestock/pet owner liability
life Life insurance 3rd column
home Home (homeowners insurance)
household Household insurance
legal Legal protection
travel Travel insurance
health-public Statutory health insurance

POST /conversation/questions


Service to dynamically supply the content of a customer journey / dynamic question or decision tree. This service delivers a list of all parameters (and therefore next questions to be asked) in a schematic/descriptive way as well as meta-information like ordering. With each user interaction, the list is adapted and grows as the end user is guided through a smart process that is supposed to extract information in an optimal way.

Features are

This service is intended be the main access point for all of the dynamic front end applications using the riskine API. The resource structure supports integration with different front-ends, e.g. sequential questionnaire, forms, chatbot views and voice.

Customization for institutional clients includes predefining the questions as well as adapting the definition format to the specific product needs. In the following, you'll find a description of the resource tags respectively the features of the API. Below, you'll find an example interaction flow.

The service needs one additional input from the client:

tag Description
path Workflow id. E.g. "main" for the entry path/initial D&N analysis (Bedarfsanalyse). All other pathes, a list of all paths will be provided for each client separately, work the same way.

The response can contain the following tags. Note that the riskine API omits redundant tags (null, false, []) in the response to reduce load:

tag Description
params Parameter list to include all parameters to be collected from the user.
type Rendering type of the control in the front-end. "radio" are radiobuttons, "multi" are multiselect buttons, "ddown" are dropdowns, "date" are date fields, "text" are freeform inputs, "inline-text" are readonly-texts, "hidden" are hidden forms and finally "group" are grouped controls which recursively contain a params tag.
validate A JSON Schema v7 to schematize the expected user answer. This always concurs with the schema of the fields in the general riskine API resource
label Textlabel to display as question text. Contains raw for raw text and, if needed md for markdown-formatted text. Also contains gluemiddle and gluelast for mapping the user's answer to a fully conversational answer. See section on Chatbot view below
required Boolean describing whether the answer is required from the user or no
pos Position in the Parameter list
schemanode If true, the list needs to be regenerated after the client has a valid answer from the user. It means that there is more than one branch in the model and the correct path is decided after this question. A new request has to be done. Only needed for sequential questionnaire
dependencynode If true, the list needs to be regenerated after the client has a valid answer from the user. It means that there is more than one branch in the model and the correct path is decided based upon this question. Only needed when the questionnaire is shown in form-style (all questions at once)
showonce If true, show this question only if the client does not yet have a valid answer from the user. This serves to minimize questions by not showing questions often asked in various different paths. Although the questions were not asked again the will remain, and not crossed out, in the path filled up already.
reset Array of parameters to be reset (deleted) after the client got a valid answer to this question. Empty in most cases.
dependencies Array of parameters. Show the question tagged with dependency only when there is a valid answers from the user to all dependencies, otherwise hide it
booldependencies Array of other questions. Tagged question should only be shown when all questions in the array are answered with a 1
placeholder Text to be shown as a normal placeholder in freeform questions
override Text to be shown as a normal placeholder in freeform questions
options Will be given for radio, multi, and ddown questions. Contains the possible options complete with a label, longlabel (see Chatbot view for more), value (which is the value the riskine API expects back) ,exclusive and an alwaysselected tag. The exclusive tag will always be true for radio questions, but can vary for multi questions
exclusive Always true for radio options. For multi options, can be either true (deselect all other options), "<identifier>" (deselect all other options with the same identifier) or false (don't deselect any other options)
alwaysselected Tag for options. If true, the option should always be selected and the user should be unable to deselect the option
infotext Contains a textlabel for either smallprint under the question title or tooltip text etc.
fieldwrap Contains a textlabel to wrap around the question field where a $ delimits the field position in the text
suggest a value to be prefilled in case there is no answer from the user yet. Always a valid JSON according to the validate schema of the question
format Contains format instructions. E.g. "money" for integers that need to be displayed in currency style
autofill Servicehook for asking into a domain. This tag is a JSON containing a micro servicedescription to get the needed suggestions from the riskine API
fillother Servicehook for filling other fields with calculation results. This tag is a JSON containing a micro servicedescription to get the needed suggestions from the riskine API

Here is how you interact with the API:

// first request - gives back the initial question list
{
    "path": "main"
}

with the response

// first response - shown until the first question with schemanode: true
// Objects under "params" are the questions respectively question groups (e.g. "person.birthdate", "person.gender")
// the client should sequentially run through all the questions in the list until it arrives at the question "object.vehicle.type.owned"
// "object.vehicle.type.owned" contains the tag "schemanode": true, which means that immediately after the question, there is a potential branch in the question tree
// after the user gives a validated answer to "object.vehicle.type.owned", the client needs to request /next again with all the information it collected from the user
// questions contain the tag "validate" - this is a JSON schema (v6) that defines the data field
// request is shown below
{
    "returncode": 0,
    "result": {
        "params": {
            "person.sport.habit": {
                "gposition": 1,
                "type": "radio",
                "required": true,
                "options": [
                    {
                        "pos": 1,
                        "exclusive": "true",
                        "longlabel": "Yes, I exercise on a regular basis.",
                        "label": "Yes, regularly",
                        "value": 1
                    },
                    {
                        "pos": 2,
                        "exclusive": "true",
                        "longlabel": "Yes, I exercise from time to time.",
                        "label": "Yes, irregularly",
                        "value": 2
                    },
                    {
                        "pos": 3,
                        "exclusive": "true",
                        "longlabel": "No, I don't do any sports.",
                        "label": "No",
                        "value": 3
                    }
                ],
                "validate": {
                    "type": "integer",
                    "enum": [
                        1,
                        2,
                        3
                    ]
                },
                "label": {
                    "raw": "Do you exercise?",
                    "validatehint": "Please choose an option"
                },
                "questioncategory": "detail",
                "pos": 3
            },
            "person.health.smoke.habit.one": {
                "gposition": 1,
                "type": "radio",
                "required": true,
                "options": [
                    {
                        "pos": 1,
                        "exclusive": "true",
                        "longlabel": "Yes, I smoke.",
                        "label": "Yes",
                        "value": 1
                    },
                    {
                        "pos": 2,
                        "exclusive": "true",
                        "longlabel": "I smoke sometimes.",
                        "label": "Yes, occassionally",
                        "value": 2
                    },
                    {
                        "pos": 3,
                        "exclusive": "true",
                        "longlabel": "No, I don´t smoke.",
                        "label": "No",
                        "value": 3
                    },
                    {
                        "pos": 4,
                        "exclusive": "true",
                        "longlabel": "I don´t want to tell.",
                        "label": "Not specified",
                        "value": 4
                    }
                ],
                "validate": {
                    "type": "integer",
                    "enum": [
                        1,
                        2,
                        3,
                        4
                    ]
                },
                "label": {
                    "raw": "Do you smoke?",
                    "validatehint": "Please choose an option"
                },
                "questioncategory": "detail",
                "pos": 4
            },
            "person.birthdate": {
                "pattern": "\\d\\d\\d\\d-\\d\\d-\\d\\d",
                "resultclass": "parameter",
                "gposition": 1,
                "type": "date",
                "required": true,
                "options": [
                    {
                        "exclusive": "true"
                    }
                ],
                "placeholder": "DD.MM.YYYY",
                "validate": {
                    "pattern": "\\d\\d\\d\\d-\\d\\d-\\d\\d",
                    "type": "string",
                    "max-date": "-18Y",
                    "min-date": "-120Y"
                },
                "showonce": true,
                "min-date": "-120Y",
                "format": "date",
                "label": {
                    "raw": "What is your date of birth? (The minimum age 18 years.)",
                    "validatehint": "Must be at least 18 years back"
                },
                "questioncategory": "detail",
                "max-date": "-18Y",
                "pos": 5
            },
            "object.animal.type.select": {
                "gposition": 1,
                "type": "radio",
                "required": true,
                "options": [
                    {
                        "pos": 1,
                        "exclusive": "true",
                        "longlabel": "Yes, I have a dog or a horse.",
                        "label": "Yes, at least 1 dog or horse",
                        "value": 1
                    },
                    {
                        "pos": 2,
                        "exclusive": "true",
                        "longlabel": "Yes, I have pets, but no dogs or horses.",
                        "label": "Yes, other pets",
                        "value": 2
                    },
                    {
                        "pos": 3,
                        "exclusive": "true",
                        "longlabel": "No, I don´t have any pets.",
                        "label": "No",
                        "value": 3
                    }
                ],
                "validate": {
                    "type": "integer",
                    "enum": [
                        1,
                        2,
                        3
                    ]
                },
                "label": {
                    "raw": "Do you have pets?",
                    "validatehint": "Please choose an option"
                },
                "questioncategory": "detail",
                "pos": 6
            },
            "object.home.type": {
                "gposition": 1,
                "type": "radio",
                "required": true,
                "options": [
                    {
                        "pos": 1,
                        "exclusive": "true",
                        "longlabel": "I live in a rented apartment.",
                        "label": "Rented apartment",
                        "value": 1
                    },
                    {
                        "pos": 2,
                        "exclusive": "true",
                        "longlabel": "I live in a rented house.",
                        "label": "Rented house",
                        "value": 2
                    },
                    {
                        "pos": 3,
                        "exclusive": "true",
                        "longlabel": "I live in a condominium.",
                        "label": "Condominium",
                        "value": 3
                    },
                    {
                        "pos": 4,
                        "exclusive": "true",
                        "longlabel": "I live in my own house.",
                        "label": "House (proprietary)",
                        "value": 4
                    },
                    {
                        "pos": 5,
                        "exclusive": "true",
                        "longlabel": "I live with my parents or with my partner.",
                        "label": "With parents/ partner",
                        "value": 5
                    }
                ],
                "validate": {
                    "type": "integer",
                    "enum": [
                        1,
                        2,
                        3,
                        4,
                        5
                    ]
                },
                "label": {
                    "raw": "Where do you live?",
                    "validatehint": "Please choose an option"
                },
                "schemanode": true,
                "questioncategory": "detail",
                "pos": 7
            },
            "object.vehicle.type.owned": {
                "gposition": 1,
                "type": "multi",
                "required": true,
                "options": [
                    {
                        "pos": 1,
                        "exclusive": "false",
                        "longlabel": "a car",
                        "label": "Car",
                        "value": "PKW"
                    },
                    {
                        "pos": 2,
                        "exclusive": "false",
                        "longlabel": "a motorbike",
                        "label": "Motorbike",
                        "value": "KRA"
                    },
                    {
                        "pos": 3,
                        "exclusive": "false",
                        "longlabel": "a truck",
                        "label": "Truck",
                        "value": "LKW"
                    },
                    {
                        "pos": 4,
                        "exclusive": "false",
                        "longlabel": "another vehicle",
                        "label": "Other vehicle ",
                        "value": "SON"
                    },
                    {
                        "pos": 5,
                        "exclusive": "true",
                        "longlabel": "I don´t own a vehicle.",
                        "label": "No vehicle",
                        "value": "kein"
                    }
                ],
                "validate": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                        "type": "string",
                        "enum": [
                            "999",
                            "ANH",
                            "KRA",
                            "LKW",
                            "MOP",
                            "OMN",
                            "PKW",
                            "PRO",
                            "SON",
                            "ZUG",
                            "kein"
                        ]
                    }
                },
                "label": {
                    "raw": "What type of vehicle do you own?",
                    "gluelast": " and ",
                    "gluemiddle": ", ",
                    "validatehint": "Please choose at least one option"
                },
                "schemanode": true,
                "minItems": 1,
                "questioncategory": "detail",
                "pos": 8
            },
            "person.family.partner": {
                "gposition": 1,
                "type": "radio",
                "required": true,
                "options": [
                    {
                        "pos": 1,
                        "exclusive": "true",
                        "longlabel": "I´m single.",
                        "label": "Single",
                        "value": 1
                    },
                    {
                        "pos": 2,
                        "exclusive": "true",
                        "longlabel": "I´m married or in a civil union.",
                        "label": "Married/ in a civil union",
                        "value": 2
                    },
                    {
                        "pos": 3,
                        "exclusive": "true",
                        "longlabel": "I´m divorced.",
                        "label": "Divorced",
                        "value": 3
                    },
                    {
                        "pos": 4,
                        "exclusive": "true",
                        "longlabel": "I´m widowed.",
                        "label": "Widowed",
                        "value": 4
                    },
                    {
                        "pos": 5,
                        "exclusive": "true",
                        "longlabel": "I´m in a relationship.",
                        "label": "In a relationship",
                        "value": 5
                    }
                ],
                "validate": {
                    "type": "integer",
                    "enum": [
                        1,
                        2,
                        3,
                        4,
                        5
                    ]
                },
                "showonce": true,
                "label": {
                    "raw": "What is your marital status?",
                    "validatehint": "Please choose an option"
                },
                "questioncategory": "detail",
                "pos": 9
            },
            ...

the client sequentially collects all the answers from the user and then requests the question list again:

// second request
{
    "path": "main",
    "person.birthdate": "1980-01-01",
    "person.sport.habit": 2,
    "person.health.smoke.habit.one": 1,
    "object.home.type": 1,
    "object.vehicle.type.owned": ["PKW"]
}

with the response

// response
// the updated list comes back - see the end of the list - now the question "kfzwert" comes before the question "haustiere"
// the client should now continue to sequentially collect answers from the user until it hits a "schemanode": true question
// when the end of the list is reached and the last question doesn't contain the tag "schemanode": true, there are no more questions
{
    "returncode": 0,
    "result": {
        "params": {
            "person.sport.habit": {
                "gposition": 1,
                "type": "radio",
                "required": true,
                "options": [
                    {
                        "pos": 1,
                        "exclusive": "true",
                        "longlabel": "Yes, I exercise on a regular basis.",
                        "label": "Yes, regularly",
                        "value": 1
                    },
                    {
                        "pos": 2,
                        "exclusive": "true",
                        "longlabel": "Yes, I exercise from time to time.",
                        "label": "Yes, irregularly",
                        "value": 2
                    },
                    {
                        "pos": 3,
                        "exclusive": "true",
                        "longlabel": "No, I don't do any sports.",
                        "label": "No",
                        "value": 3
                    }
                ],
                "validate": {
                    "type": "integer",
                    "enum": [
                        1,
                        2,
                        3
                    ]
                },
                "label": {
                    "raw": "Do you exercise?",
                    "validatehint": "Please choose an option"
                },
                "questioncategory": "detail",
                "pos": 3
            },
            "person.health.smoke.habit.one": {
                "gposition": 1,
                "type": "radio",
                "required": true,
                "options": [
                    {
                        "pos": 1,
                        "exclusive": "true",
                        "longlabel": "Yes, I smoke.",
                        "label": "Yes",
                        "value": 1
                    },
                    {
                        "pos": 2,
                        "exclusive": "true",
                        "longlabel": "I smoke sometimes.",
                        "label": "Yes, occassionally",
                        "value": 2
                    },
                    {
                        "pos": 3,
                        "exclusive": "true",
                        "longlabel": "No, I don´t smoke.",
                        "label": "No",
                        "value": 3
                    },
                    {
                        "pos": 4,
                        "exclusive": "true",
                        "longlabel": "I don´t want to tell.",
                        "label": "Not specified",
                        "value": 4
                    }
                ],
                "validate": {
                    "type": "integer",
                    "enum": [
                        1,
                        2,
                        3,
                        4
                    ]
                },
                "label": {
                    "raw": "Do you smoke?",
                    "validatehint": "Please choose an option"
                },
                "questioncategory": "detail",
                "pos": 4
            },
            "person.birthdate": {
                "pattern": "\\d\\d\\d\\d-\\d\\d-\\d\\d",
                "resultclass": "parameter",
                "gposition": 1,
                "type": "date",
                "required": true,
                "options": [
                    {
                        "exclusive": "true"
                    }
                ],
                "placeholder": "DD.MM.YYYY",
                "validate": {
                    "pattern": "\\d\\d\\d\\d-\\d\\d-\\d\\d",
                    "type": "string",
                    "max-date": "-18Y",
                    "min-date": "-120Y"
                },
                "showonce": true,
                "min-date": "-120Y",
                "format": "date",
                "label": {
                    "raw": "What is your date of birth? (The minimum age 18 years.)",
                    "validatehint": "Must be at least 18 years back"
                },
                "questioncategory": "detail",
                "max-date": "-18Y",
                "pos": 5
            },
            "object.animal.type.select": {
                "gposition": 1,
                "type": "radio",
                "required": true,
                "options": [
                    {
                        "pos": 1,
                        "exclusive": "true",
                        "longlabel": "Yes, I have a dog or a horse.",
                        "label": "Yes, at least 1 dog or horse",
                        "value": 1
                    },
                    {
                        "pos": 2,
                        "exclusive": "true",
                        "longlabel": "Yes, I have pets, but no dogs or horses.",
                        "label": "Yes, other pets",
                        "value": 2
                    },
                    {
                        "pos": 3,
                        "exclusive": "true",
                        "longlabel": "No, I don´t have any pets.",
                        "label": "No",
                        "value": 3
                    }
                ],
                "validate": {
                    "type": "integer",
                    "enum": [
                        1,
                        2,
                        3
                    ]
                },
                "label": {
                    "raw": "Do you have pets?",
                    "validatehint": "Please choose an option"
                },
                "questioncategory": "detail",
                "pos": 6
            },
            "object.home.type": {
                "gposition": 1,
                "type": "radio",
                "required": true,
                "options": [
                    {
                        "pos": 1,
                        "exclusive": "true",
                        "longlabel": "I live in a rented apartment.",
                        "label": "Rented apartment",
                        "value": 1
                    },
                    {
                        "pos": 2,
                        "exclusive": "true",
                        "longlabel": "I live in a rented house.",
                        "label": "Rented house",
                        "value": 2
                    },
                    {
                        "pos": 3,
                        "exclusive": "true",
                        "longlabel": "I live in a condominium.",
                        "label": "Condominium",
                        "value": 3
                    },
                    {
                        "pos": 4,
                        "exclusive": "true",
                        "longlabel": "I live in my own house.",
                        "label": "House (proprietary)",
                        "value": 4
                    },
                    {
                        "pos": 5,
                        "exclusive": "true",
                        "longlabel": "I live with my parents or with my partner.",
                        "label": "With parents/ partner",
                        "value": 5
                    }
                ],
                "validate": {
                    "type": "integer",
                    "enum": [
                        1,
                        2,
                        3,
                        4,
                        5
                    ]
                },
                "label": {
                    "raw": "Where do you live?",
                    "validatehint": "Please choose an option"
                },
                "schemanode": true,
                "questioncategory": "detail",
                "pos": 7
            },
            "object.home.size.total": {
                "resultclass": "parameter",
                "gposition": 1,
                "type": "text",
                "required": true,
                "validate": {
                    "type": "integer",
                    "minimum": 10,
                    "maximum": 10000
                },
                "showonce": true,
                "format": "m2",
                "label": {
                    "longlabel": "My flat has $ m².",
                    "raw": "What is the size of your rented apartment?",
                    "validatehint": "Please insert a value between 10 and 10000"
                },
                "questioncategory": "detail",
                "maximum": "10000",
                "fieldwrap": "$ m² living space",
                "minimum": "10",
                "pos": 8
            },
            "object.vehicle.type.owned": {
                "gposition": 1,
                "type": "multi",
                "required": true,
                "options": [
                    {
                        "pos": 1,
                        "exclusive": "false",
                        "longlabel": "a car",
                        "label": "Car",
                        "value": "PKW"
                    },
                    {
                        "pos": 2,
                        "exclusive": "false",
                        "longlabel": "a motorbike",
                        "label": "Motorbike",
                        "value": "KRA"
                    },
                    {
                        "pos": 3,
                        "exclusive": "false",
                        "longlabel": "a truck",
                        "label": "Truck",
                        "value": "LKW"
                    },
                    {
                        "pos": 4,
                        "exclusive": "false",
                        "longlabel": "another vehicle",
                        "label": "Other vehicle ",
                        "value": "SON"
                    },
                    {
                        "pos": 5,
                        "exclusive": "true",
                        "longlabel": "I don´t own a vehicle.",
                        "label": "No vehicle",
                        "value": "kein"
                    }
                ],
                "validate": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                        "type": "string",
                        "enum": [
                            "999",
                            "ANH",
                            "KRA",
                            "LKW",
                            "MOP",
                            "OMN",
                            "PKW",
                            "PRO",
                            "SON",
                            "ZUG",
                            "kein"
                        ]
                    }
                },
                "label": {
                    "raw": "What type of vehicle do you own?",
                    "gluelast": " and ",
                    "gluemiddle": ", ",
                    "validatehint": "Please choose at least one option"
                },
                "schemanode": true,
                "minItems": 1,
                "questioncategory": "detail",
                "pos": 9
            },
            "object.vehicle.value": {
                "gposition": 1,
                "type": "radio",
                "required": true,
                "options": [
                    {
                        "pos": 1,
                        "exclusive": "true",
                        "longlabel": "My vehicle/s are worth less than 5.000 €.",
                        "label": "Less than 5.000 €",
                        "value": 5000
                    },
                    {
                        "pos": 2,
                        "exclusive": "true",
                        "longlabel": "My vehicle/s are worth up to 10.000 €.",
                        "label": "Up to 10.000 €",
                        "value": 10000
                    },
                    {
                        "pos": 3,
                        "exclusive": "true",
                        "longlabel": "My vehicle/s are worth up to 20.000 €.",
                        "label": "Up to 20.000 €",
                        "value": 20000
                    },
                    {
                        "pos": 4,
                        "exclusive": "true",
                        "longlabel": "My vehicle/s are worth up to 60.000 €.",
                        "label": "Up to 60.000 €",
                        "value": 60000
                    },
                    {
                        "pos": 5,
                        "exclusive": "true",
                        "longlabel": "My vehicle/s are worth more than 60.000 €.",
                        "label": "More than 60.000 €",
                        "value": 150000
                    }
                ],
                "validate": {
                    "type": "integer",
                    "enum": [
                        5000,
                        10000,
                        20000,
                        60000,
                        150000
                    ]
                },
                "label": {
                    "raw": "What is the overall value of all your vehicles?",
                    "validatehint": "Please choose an option"
                },
                "questioncategory": "detail",
                "pos": 10
            },
            "person.family.partner": {
                "gposition": 1,
                "type": "radio",
                "required": true,
                "options": [
                    {
                        "pos": 1,
                        "exclusive": "true",
                        "longlabel": "I´m single.",
                        "label": "Single",
                        "value": 1
                    },
                    {
                        "pos": 2,
                        "exclusive": "true",
                        "longlabel": "I´m married or in a civil union.",
                        "label": "Married/ in a civil union",
                        "value": 2
                    },
                    {
                        "pos": 3,
                        "exclusive": "true",
                        "longlabel": "I´m divorced.",
                        "label": "Divorced",
                        "value": 3
                    },
                    {
                        "pos": 4,
                        "exclusive": "true",
                        "longlabel": "I´m widowed.",
                        "label": "Widowed",
                        "value": 4
                    },
                    {
                        "pos": 5,
                        "exclusive": "true",
                        "longlabel": "I´m in a relationship.",
                        "label": "In a relationship",
                        "value": 5
                    }
                ],
                "validate": {
                    "type": "integer",
                    "enum": [
                        1,
                        2,
                        3,
                        4,
                        5
                    ]
                },
                "showonce": true,
                "label": {
                    "raw": "What is your marital status?",
                    "validatehint": "Please choose an option"
                },
                "questioncategory": "detail",
                "pos": 11
            },
            ...

Chatbot view


To support chatbot-like front-ends we include additional textlabels that serve to mimic conversation flow, e.g. when asked the gender, user picks "male" yet the chatbot view prints out "I am male". This textcontent also varies based on rules and different user inputs. The functionality is achieved by tagging questions and options with longlabels as described in the following table:

tag desription example
longlabel inside textlabel of freeform question Should be filled in with the user's answer at the $ "I was born on the $" -> "I was born on the 22.10.1989"
longlabel inside radio option Complete answer - can simply be printed out label: "yes", longlabel: "Yes please, I need additional coverage for my second motorcycle"
longlabel inside multi option To be used with the gluemiddle and gluelast parameters given at question level. The long answer needs to be built like first answer + gluemiddle + second answer + gluemiddle + ... + gluelast + last answer first answer longlabel: "My partner", second answer longlabel: "3 kids", Third answer longlabel: "other persons", gluemiddle: ", ", gluelast: "and" -> "My partner, 3 kids and other persons"
gluemiddle inside multi question textlabel See above first answer longlabel: "My partner", second answer longlabel: "3 kids", Third answer longlabel: "other persons", gluemiddle: ", ", gluelast: "and" -> "My partner, 3 kids and other persons"
gluelast inside multi question textlabel See above first answer longlabel: "My partner", second answer longlabel: "3 kids", Third answer longlabel: "other persons", gluemiddle: ", ", gluelast: "and" -> "My partner, 3 kids and other persons"

POST /conversation/results


After finishing a specific path of a product, results will be shown as a summary of the previous questions. This summary includes all relevant information concerning the personal data, wishes and needs of the customer. /pathresults contains exactly one category which is hierarchicly divided as follows

A category contains the following fields

type description example
name name of the category "Life and Living"
id ID of the category "lifeliving"
productgroup a productgroup contains reasons and optional modules ``

A productgroup contains the following fields

type description example
name name of the product "Livestock/pet owner liability"
id ID of the propduct group "tier"
products products of the insurance ``

A product contains the following fields

type description example
name name of the product "Animal insurance"
id ID of the module "tierstd"
reasons list of all reasons of the product "Covers any damages caused by your cat(s)."
modules a specification of one product. Modules usually contain different components. ``

A module contains the following fields

type description example
name name of the module "Dog Liability Insurance"
id ID of the module "hund"
parameter contains the parsed label "Date of birth dog: 01.01.2010"

Example request:

{
  "country": "ch",
  "path": "animal-liability",
  "object.animal[0].type.radio": 1,
  "object.animal.dog[0].birthdate": "2010-01-01",
  "object.animal[0].looper": 1,
  "object.animal[1].type.radio": 2,
  "object.animal.cat[1].birthdate": "2012-04-02",
  "object.animal[1].looper": 2,
  "recommendation.animal-liability.startdate": "2018-01-01",
  "recommendation.animal-liability.comments": "Insurance for cat need to be for 3 cats."
}

Example result:

{
    "returncode": 0,
    "result": {
        "categories": [
            {
                "name": "Life and Living",
                "productgroups": [
                    {
                        "name": "Livestock/pet owner liability",
                        "id": "animal-liability",
                        "products": [
                            {
                                "name": "Animal insurance",
                                "id": "animal-liability",
                                "modules": [
                                    {
                                        "name": "Dog Liability Insurance",
                                        "id": "dog",
                                        "parameter": [
                                            {
                                                "parsedlabel": "Date of birth dog: 01.01.2010"
                                            }
                                        ]
                                    },
                                    {
                                        "name": "Cat Liability Insurance",
                                        "id": "cat",
                                        "parameter": [
                                            {
                                                "parsedlabel": "Date of birth cat: 02.04.2012"
                                            }
                                        ]
                                    }
                                ],
                                "reasons": [
                                    "Covers any damages caused by your dog(s).",
                                    "Covers any damages caused by your cat(s).",
                                    "Desired start of insurance: 01.01.2018",
                                    "Comments: Insurance for cat need to be for 3 cats."
                                ]
                            }
                        ]
                    }
                ],
                "id": "lifeliving"
            }
        ]
    }
}

POST /statebenefits/pension, /statebenefits/invalidity, /statebenefits/dependants, /statebenefits/care


This service provides different calculations on the different specific products of pension. Provided are the following subservices. You can either request /statebenefits to calculate all, or specify one.

For the service pension

field description
lastincomenet last net income, monthly and yearly
benefitnet net pension, monthly and yearly
gap gap between last net income and net pension, monthly and yearly
retirement regular retirement age, earliest retirement age, latest retirement age, planned date of retirement
additionalpension optional additional pension if opted in, monthly and yearly

Full response Example:

{
    "returncode": 0,
    "result": {
        "benefitnet": {
            "monthly": 1338,
            "yearly": 18732
        },
        "lastincomenet": {
            "monthly": 1809,
            "yearly": 25328
        },
        "gap": {
            "monthly": 471,
            "yearly": 6594
        },
        "retirement": {
            "regularage": 65,
            "earlyage": 62,
            "latestage": 68,
            "date": "2045-01-01"
        },
        "additionalpension": {
            "monthly": 0,
            "yearly": 0
        }
    }
}

For the service invalidity

Field description
lastincomenet last net income before entry into invalidity pension, monthly, yearly and expected total (until regular retirement)
benefitnet job incapacity net sum, monthly, yearly and expected total (until regular retirement)
nettosum net pension sum
gap gap between last net income and net benefit, monthly, yearly and expected total (until regular retirement)
retirement earliest retirement age, latest retirement age, planned date of retirement, current age, years until regular retirement

Full response example:

{
    "returncode": 0,
    "result": {
        "benefitnet": {
            "monthly": 1035,
            "yearly": 14486,
            "total": 347663
        },
        "lastincomenet": {
            "monthly": 1809,
            "yearly": 25328,
            "total": 521040
        },
        "gap": {
            "monthly": 774,
            "yearly": 10836,
            "total": 173377
        },
        "retirement": {
            "earlyage": 38,
            "latestage": 62,
            "date": "2018-01-01",
            "age": 38,
            "yearsuntilretirement": 24
        }
    }
}

For the service dependants (widow- and orphans pension)

Field description
widow net benefit (monthly), net gap (monthly) and information about whether pension is limited or not (1 = unlimited)
orphans net benefit for all children in total (monthly), net gap (monthly) and net benefit for one child (monthly)
fullorphans same as orhpans, but both parents deceased
mean monthly mean of net benefit, last net income before entry into pension and gap

Full response example:

{
    "returncode": 0,
    "result": {
        "widow": {
            "benefitnet": {
                "monthly": 204
            },
            "gap": {
                "monthly": 1605
            },
            "unlimited": 1
        },
        "orphans": {
            "benefitnet": {
                "monthly": null
            },
            "gap": {
                "monthly": null
            },
            "singlenet": {
                "monthly": null
            }
        },
        "fullorphans": {
            "benefitnet": {
                "monthly": null
            },
            "gap": {
                "monthly": null
            },
            "singlenet": {
                "monthly": null
            }
        },
        "mean": {
            "benefitnet": {
                "monthly": 204
            },
            "lastincomenet": {
                "monthly": 1809
            },
            "gap": {
                "monthly": 1605
            }
        }
    }
}

For the service care (=pension provision): There is a varying number of "levels", e.g. 5 in Germany, 7 in Austria. The response contains the correct number of levels, called level1, level2, etc.

Field description
user Information about advised person: net income, children, careerfactor, time in marriage, income of partner, age of partner
care/level1, care/level2, ... Per level in the respective public system - estimated cost, monthly and yearly, net benefit, monthly and yearly, gap, monthly and yearly, infotext
mean mean over all levels. contains the same data points

Full response example:

{
    "returncode": 0,
    "result": {
        "user": {
            "netto": 1809,
            "children": null,
            "careerfactor": 0,
            "timemarried": 11,
            "partnerincome": 2553,
            "partnerage": 38
        },
        "care": {
            "level1": {
                "cost": {
                    "monthly": 1283,
                    "yearly": 17962
                },
                "benefitnet": {
                    "monthly": 157,
                    "yearly": 2202
                },
                "gap": {
                    "monthly": 1126,
                    "yearly": 15760
                },
                "info": "#### Pflegebedarf Stufe 1  \n Mehr als 65 Stunden pro Monat.  \n `Quelle: help.gv.at`\n\n\n#### Berechnungen Kosten:  \n Annahme eines Stundensatzes von rund € 16,- für die Betreuung zuhause."
            },
            "level2": {
                "cost": {
                    "monthly": 1727,
                    "yearly": 24178
                },
                "benefitnet": {
                    "monthly": 290,
                    "yearly": 4060
                },
                "gap": {
                    "monthly": 1437,
                    "yearly": 20118
                },
                "info": "#### Pflegebedarf Stufe 2  \n Mehr als 95 Stunden pro Monat.  \n `Quelle: help.gv.at`\n\n\n#### Berechnungen Kosten:  \n Annahme eines Stundensatzes von rund € 16,- für die Betreuung zuhause."
            },
            "level3": {
                "cost": {
                    "monthly": 2340,
                    "yearly": 32760
                },
                "benefitnet": {
                    "monthly": 452,
                    "yearly": 6325
                },
                "gap": {
                    "monthly": 1888,
                    "yearly": 26435
                },
                "info": "#### Pflegebedarf Stufe 3  \n Mehr als 120 Stunden pro Monat.  \n `Quelle: help.gv.at`\n\n\n#### Berechnungen Kosten:  \n Annahme einer Vollzeitbetreuung zuhause mit Kosten iHv € 2.340."
            },
            "level4": {
                "cost": {
                    "monthly": 2340,
                    "yearly": 32760
                },
                "benefitnet": {
                    "monthly": 678,
                    "yearly": 9486
                },
                "gap": {
                    "monthly": 1662,
                    "yearly": 23274
                },
                "info": "#### Pflegebedarf Stufe 4  \n Mehr als 160 Stunden pro Monat.  \n `Quelle: help.gv.at`\n\n\n#### Berechnungen Kosten:  \n Annahme einer Vollzeitbetreuung zuhause mit Kosten iHv € 2.340."
            },
            "level5": {
                "cost": {
                    "monthly": 3500,
                    "yearly": 49000
                },
                "benefitnet": {
                    "monthly": 920,
                    "yearly": 12884
                },
                "gap": {
                    "monthly": 2580,
                    "yearly": 36116
                },
                "info": "#### Pflegebedarf Stufe 5  \n Mehr als 180 Stunden pro Monat und Erfordernis eines außergewöhnlichen Pflegeaufwands.  \n `Quelle: help.gv.at`\n\n\n#### Berechnungen Kosten:  \n Annahme einer Heimbetreuung mit Kosten iHv € 3.500."
            },
            "level6": {
                "cost": {
                    "monthly": 3500,
                    "yearly": 49000
                },
                "benefitnet": {
                    "monthly": 1285,
                    "yearly": 17993
                },
                "gap": {
                    "monthly": 2215,
                    "yearly": 31007
                },
                "info": "#### Pflegebedarf Stufe 6  \n Mehr als 180 Stunden pro Monat und Notwendigkeit\n\n - von zeitlich nicht planbaren regelmäßigen Betreuungsmaßnahmen bei Tag und Nacht oder\n  - der erforderlichen dauernden Anwesenheit einer Pflegeperson wegen Eigen- oder Fremdgefährdung\n\n `Quelle: help.gv.at`\n\n\n#### Berechnungen Kosten:  \n Annahme einer Heimbetreuung mit Kosten iHv € 3.500."
            },
            "level7": {
                "cost": {
                    "monthly": 3500,
                    "yearly": 49000
                },
                "benefitnet": {
                    "monthly": 1689,
                    "yearly": 23645
                },
                "gap": {
                    "monthly": 1811,
                    "yearly": 25355
                },
                "info": "#### Pflegebedarf Stufe 7  \n Mehr als 180 Stunden pro Monat, wenn\n\n - keine zielgerichteten Bewegungen der vier Extremitäten mit funktioneller Umsetzung möglich sind oder\n - ein gleich zu achtender Zustand vorliegt\n\n `Quelle: help.gv.at`\n\n\n#### Berechnungen Kosten:  \n Annahme einer Heimbetreuung mit Kosten iHv € 3.500."
            },
            "mean": {
                "cost": {
                    "monthly": 2599,
                    "yearly": 36380
                },
                "benefitnet": {
                    "monthly": 782,
                    "yearly": 10942
                },
                "gap": {
                    "monthly": 1817,
                    "yearly": 25438
                },
                "info": ""
            }
        }
    }
}

POST /productgroups/prioritization/details


Shows the results of the general demands and needs analysis for private clients. The results contain per productgroup/path a description text including the calculated amount of coverage and additional, optional, info text

type description example
description description of the details (can be empty) "The insured sum should correlate with your car's value."
id path information "kfzkasko"
title title of recommendation "Motor vehicle own-damage"
info additional information of the details (can be empty) null

Example request:

{
    "country":"de",
    "path":"pathvorsorge"
}

Example result:

{
    "returncode": 0,
    "result": [
        {
            "description": null,
            "id": "invalidity-child",
            "title": "Children invalidity insurance",
            "info": "Check exactly when your insurance company renders which services. In addition to a lump sum, if affordable, a lifelong pension is desirable."
        },
        {
            "description": null,
            "id": "funeral",
            "title": "Funeral expense insurance",
            "info": "Please note that the contributions are very high at the age of 65 at the beginning of the contract. Check if subareas are already included in your term life insurance."
        }
    ]
}

POST /profile/risks/prioritization


This service uses the core riskine algorithm to calculate impact evaluations for the 8 life risks. On a discrete scale from 0 to 6, each of the 8 life risks is assigned a ranking or prioritization based upon their respective financial impacts. As in the riskine analysis, this can be used complementary to the life risk probability values. For example, death may have a seemingly insignificant probability in younger years, yet the financial impact can be enormous for income-dependent persons. Thus, although the risk probability values may be low, this service still indicates a possible danger and need to insure.

Possible response status:

Status code Description
200 Success
400 Data not properly specified

Example result:

{
    "returncode": 0,
    "result": {
        "health": {
            "total": 84,
            "onetimeloss": 27,
            "incomeloss": 86,
            "statebenefit": 34
        },
        "accident": {
            "total": 97,
            "onetimeloss": 44,
            "incomeloss": 88,
            "statebenefit": 35
        },
        "pensiongap": {
            "total": 0,
            "onetimeloss": 0,
            "incomeloss": 0,
            "statebenefit": 0
        },
        "natcat": {
            "total": 15,
            "onetimeloss": 15,
            "incomeloss": 0,
            "statebenefit": 0
        },
        "unemployment": {
            "total": 0,
            "onetimeloss": 0,
            "incomeloss": 0,
            "statebenefit": 0
        },
        "crime": {
            "total": 7,
            "onetimeloss": 7,
            "incomeloss": 0,
            "statebenefit": 0
        },
        "death": {
            "total": 10,
            "onetimeloss": 0,
            "incomeloss": 0,
            "statebenefit": 0
        },
        "legal": {
            "total": 15,
            "onetimeloss": 15,
            "incomeloss": 0,
            "statebenefit": 0
        }
    }
}

POST /profile/risks/probabilities


This service calculates the yearly probabilities for sufferig from one of 8 life risks. It accepts any input from the empty object {} to the fully specified resource. When not specified, a parameter will range over all possible values. For example, posting the empty object {} will result in the average probability for all of Austria. As demonstrated in the riskine analysis, this could be used in a customer journey to start from the average probabilities and individualize them step-by-step as the user specifies their parameters.

The additional scale parameter indicates a maximum scale value against which all the risks fit nicely in a bars UI, e.g.

Possible response status:

Status code Description
200 Success
400 Data not properly specified

Example result:

{
    "returncode": 0,
    "result": {
        "scale": 0.24939779093796,
        "health": 0.17457845365657,
        "accident": 0.085926522239249,
        "pensiongap": 0.1454,
        "natcat": 0.1152025375,
        "unemployment": 0.05678109960701,
        "crime": 0.0059802504119243,
        "death": 0.00094905564063066,
        "legal": 0.04380361
    }
}

POST /profile/risks/details


This service is the big brother of the service /profile/risks/probabilities. It takes into account the full resource (although not every parameter needs to be specified) and calculates yearly probabilities for the 8 life risks as well as the constituting subrisks and moreover various damage numbers like expected natural disaster damage or expected loss in income at retirement.

The additional scale parameter indicates a maximum scale value against which all the risks fit nicely in a bars UI, e.g.

Possible response status:

Status code Description
200 Success
400 Data not properly specified

Example result:

{
    "returncode": 0,
    "result": {
        "scale": 0.29291313933154,
        "health": {
            "gesamt": 0.20503919753208,
            "geszust": 0.0686874706628,
            "chron": 0.2817773355696,
            "pflege": 0.0075837627250555,
            "kstand": 9.6,
            "khausaufenth": 6.4,
            "invalid": 0.0949,
            "pflegest": 120,
            "topdiagn": {
                "ws1": 32.138,
                "ws2": 10.7182,
                "ws3": 9.9152,
                "b1": "Schwangerschaft, Geburt und Wochenbett (ist selbstverständlich keine Krankheit)\r\n",
                "b2": "Krankheiten des Urogenitalsystems",
                "b3": "Neubildungen (Krebs)"
            },
            "topchron": {
                "ws1": 29.6346,
                "ws2": 15.6969,
                "ws3": 15.2909,
                "b1": "Allergien, wie allergischer Schnupfen, Heuschnupfen, allergische Reaktionen der Augen oder der Haut (Dermatitis), Lebensmittelallergie oder andere Allergien (ausgenommen allergisches Asthma)",
                "b2": "Chronische Nackenschmerzen oder sonstige chronische Beschwerden an der Halswirbelsäule",
                "b3": "Chronische Kreuzschmerzen oder ein anderes chronisches Rückenleiden"
            }
        },
        "accident": {
            "gesamt": 0.078440614410996,
            "arbeit": 0.026296943949451,
            "heim": 0.027036931653776,
            "sport": 0.019871851105052,
            "verkehr": 0.0075295710546377,
            "krankenst": 20,
            "krankenh": 7.2,
            "stationaer": 22,
            "invalide": 2
        },
        "pensiongap": {
            "gesamt": 0.1262,
            "plueckenormpct": 0.12590084739983,
            "plueckenormeur": 214.03144057971,
            "plueckekarrpct": 0.35103354036692,
            "plueckekarreur": 596.75701862376,
            "plueckeuntpct": 0.49232965882353,
            "plueckeunteur": 836.96042
        },
        "natcat": {
            "gesamt": 0.1337850687799,
            "hagel": 0.0639,
            "hochw": 0.0001,
            "sturm": 0.0818,
            "brand": 0.0082,
            "leitungsw": 0.05,
            "dambrand": 11184,
            "damhagel": 3000,
            "damhw": 10000,
            "damsturmkfz": 3000,
            "damsturmheim": 1500,
            "damleitungsw": 2000
        },
        "unemployment": {
            "gesamt": 0.031302406806568,
            "arblgkeit": 0.031302406806568,
            "insolvenz": 0,
            "arblgeldpct": 0.45
        },
        "crime": {
            "gesamt": 0.029224917496069,
            "kfzeinbr": 0,
            "kfzdiebst": 0,
            "einbruch": 0.012969463180097,
            "person": 0.016469049041122,
            "dameinbruch": 2200
        },
        "death": {
            "gesamt": 0.0006657063267754,
            "krankheit": 0.00070270356053184,
            "krim": 1e-7,
            "selbstm": 0.0001,
            "unfall": 0.00018197024228977,
            "wipenseur": 0,
            "wipenspct": 0,
            "wapenseur": 0,
            "wapenspct": 0
        },
        "legal": {
            "gesamt": 0.049407861717,
            "verlsch": 0.0092,
            "familie": 0,
            "arbeit": 0.0083,
            "mahnung": 0.0765,
            "verkehr": 0,
            "miete": 0.0325
        }
    }
}

POST /productgroups-corporate/prioritization


This service calculates a recommendation ranking for corporate insurance products, based on the risk impact evaluations and regulatory requirements. The ranking is discrete, ranging from 3 indicating 'absolutely recommended' down to 0 indicating 'not recommended' (e.g. building insurance for businesses without an owned building). As mentioned in the introduction, there may well be the need to adjust the product universe during our mutual project. Refer to the additional input schema to find out about required parameters and their dependencies.

Possible response status:

Status code Description
200 Success
400 Data not properly specified

Example request:

{
    "organization.sector": "A1",
    "organization.employees.number": 20,
    "organization.business.processes.digital": [3],
    "organization.property.type": [1,2,3,4,5]
}

Example result:

{
    "returncode": 0,
    "result": {
        "corporate-legal": 2,
        "corporate-person": 1,
        "corporate-event": 1,
        "corporate-director": 1,
        "corporate-travel": 1,
        "corporate-unfall": 2,
        "corporate-health": 2,
        "corporate-vehicle": 3,
        "corporate-machinery": 2,
        "corporate-machinery-interruption": 2,
        "corporate-device": 2,
        "corporate-building": 3,
        "corporate-interior": 1,
        "corporate-cyber": 3,
        "corporate-pension": 1,
        "corporate-pension-benefit": 1
    }
}

POST /profile/risks-corporate/prioritization


This service returns an indication which parameter in the general demands and needs analysis for corporate clients has an impact on which risk category.

Possible response status:

Status code Description
200 Success
400 Data not properly specified

Example request:

{
    "qrel": "organization.sector"
}

Example result:

{
    "returncode": 0,
    "result": {
        "question": "organization.sector",
        "person": 1,
        "property": 1,
        "financial": 1
    }
}

Supporting Services


POST /addresses


This service is used to validate an address data set against the riskine adress database. The service will return an array of matches from the database including an ID. It is intended to be used as a pre-validation of address parameters prior to using the other services. As the riskine algorithm takes into account elementary risk on a GPS-exact basis, posting validated adresses is important for exact calculation. Once matched, the ID adresseid can be used to quickly match the adress in the future. The ID is the same across all services.

The /addresses service was designed with the consideration in mind that every client may have addresses of their users which are incomplete, contain typos or are generally written down in a non-standard way. Using this service, clients of the riskine API could also implement validation routines to prompt their users with suggestions of correct addresses during the customer journey (As in the riskine analysis).

There is of course a more generic and less-imposing way to match a users address, and the service is currently undergoing development.

Note a few things about usage:

Possible response status:

Status code Description
200 Success
400 Data not properly specified

Example result:

POST /industrysectors


Possible response status:

Status code Description
200 Success
400 Data not properly specified

Example request:

{
    "branche": "kernbre"
}

Example result:

{
    "returncode": 0,
    "result": [
        {
            "edvcode": "C2446",
            "branche": "Aufbereitung v. Kernbrennstoffen"
        }
    ]
}

POST /professions


Possible response status:

Status code Description
200 Success
400 Data not properly specified

Example request:

{
    "berufsliste": "arz"
}

Example result:

{
    "returncode": 0,
    "result": [
        {
            "id": 22,
            "berufe": "Arzt (außer Chirurg und Notarzt)"
        },
        {
            "id": 23,
            "berufe": "Arzthelfer/in"
        }
    ]
}

POST /income


This service serves as a gross/net calculator. Given a job description and either net monthly or gross monthly income, this calculates the missing value in accordance with the Austrian Law. The service exposes the same calculator used by the riskine algorithm interally.

Possible response status:

Status code Description
200 Success
400 Data not properly specified

Example result:

POST /cards?area=:questionarea


The service cards loads risk related pictures out of a database. The parameter area specifies the question, for which the images are requested. If the question is within a group, area would be set with the groupname of this group, otherwise with the paramname the question. Possible format values are base64, svg and url describing the data value.

Url parameter

Required: questionarea = [string] example: questionarea = branche

Possible response status:

Status code Description
200 Success
400 Data not properly specified

Example request:

{
    "branche": "224",
    "besitztum": [1, 2, 3, 4, 5, 6, 7]
}

Example result:

[
    {
        "id": "gastronomy",
        "title": "Gastronomie",
        "infotext": "",
        "risk": "usachwerte",
        "image": {
            "data": "/9j/4AAQSk...",
            "format": "base64"
        },
        "mediatype": "jpg"
    }
]

POST /enginepower


Calculates PS from kW and vice versa.

Possible response status:

Status code Description
200 Success
400 Data not properly specified

Example request:

{
    "unit_kw": 999
}

Example result:

{
    "returncode": 0,
    "result": {
        "unit_ps": 1358.26,
        "unit_kw": 999
    }
}

POST /edges/{workflowname}


This service can be used to create a visualisation of a given workflow. Returns all edges relevant vor the visualisation.

Possible response status:

Status code Description
200 Success

Example request:

riskine.com/edges/pension-insurance

Example result:

{
    "returncode": 0,
    "result": [
          {
             "data": {
                 "source": "e5187660-9cc5-4958-9474-ef5692902b5a",
                 "label": "BEFORE",
                 "annotation": [
                     "customer is over 18 years of age"
                 ],
                 "id": "a8d669c1-05d9-430c-bc95-e64d69dafa77",
                 "nodegroup": "",
                 "target": "c4da6bc5-aeca-4380-bbc7-4c987256a950"
             },
             "classes": "before"
         },
         {
             "data": {
                 "source": "b5d89912-f7b3-414f-bbd3-343054e9c9ee",
                 "label": "OPTION",
                 "id": "cf352540-f2bc-417d-aabe-03ab28e89785",
                 "nodegroup": "b5d89912-f7b3-414f-bbd3-343054e9c9ee",
                 "target": "5d3723fc-6303-426c-83a3-fb4ae7e19d00"
             },
             "classes": "option"
         },
         {
             "data": {
                 "id": "66da907f-e521-4f8c-b222-463f850c1fdc",
                 "source": "2ce440d1-5b33-4691-9dba-a0eba9c17ceb",
                 "target": "3cf331b8-a7ad-4627-9170-02fc9360e09f",
                 "label": "RECOMMEND"
             },
             "classes": "recommend"
         }
    ]
}

(The rest of the result was omitted)

POST /floodrisk


Calculates and returns statistical risk of flood in terms of yearly probability. Needs Lat and Lon coordinates.

Possible response status:

Status code Description
200 Success
400 Data not properly specified

Example request:

{
    "lon": 16.65939,
    "lat": 47.89328
}

Example result:

{
    "returncode": 0,
    "result": {
        "floodrisk": 0.033333
    }
}

POST /makes/car


Possible response status:

Status code Description
200 Success
400 Data not properly specified

Example request:

{
    "automarke": "la"
}

Example result:

{
    "returncode": 0,
    "result": [
        {
            "id": 8,
            "automarke": "Cadillac"
        },
        {
            "id": 32,
            "automarke": "Lada"
        },
        {
            "id": 33,
            "automarke": "Lamborghini"
        },
        {
            "id": 34,
            "automarke": "Lancia"
        },
        {
            "id": 35,
            "automarke": "Land Rover"
        },
        {
            "id": 43,
            "automarke": "McLaren"
        },
        {
            "id": 66,
            "automarke": "Tesla"
        }
    ]
}

POST /makes/motorcycle


Possible response status:

Status code Description
200 Success
400 Data not properly specified

Example request:

{
    "motorradmarke": "su"
}

Example result:

{
    "returncode": 0,
    "result": [
        {
            "id": 50,
            "motorradmarke": "Hsun"
        },
        {
            "id": 53,
            "motorradmarke": "Hyosung"
        },
        {
            "id": 105,
            "motorradmarke": "Suzuki"
        }
    ]
}

POST /countries


Returns a lists of countries matching the search term.

Possible response status:

Status code Description
200 Success
400 Data not properly specified

Example request:

{
    "country": "united"
}

Example result:

{
    "returncode": 0,
    "result": [
        {
            "iso_code": "ARE",
            "country": "United Arab Emirates"
        },
        {
            "iso_code": "GBR",
            "country": "United Kingdom (UK)"
        },
        {
            "iso_code": "USA",
            "country": "United States of America"
        }
    ]
}

POST /nationalities


Returns a lists of nationalities matching the search term.

Possible response status:

Status code Description
200 Success
400 Data not properly specified

Example request (?locale=en):

{
    "nationality": "moza"
}

Example result:

{
    "returncode": 0,
    "result": [
        {
            "id": 129,
            "nationality": "Mozambican"
        }
    ]
}

POST /risksport


Returns a lists of risksports matching the search term.

Possible response status:

Status code Description
200 Success
400 Data not properly specified

Example request (?locale=en):

{
    "risksport": "div"
}

Example result:

{
    "returncode": 0,
    "result": [
        {
            "id": 68,
            "risksport": "Diving  Without breathing equipment"
        },
        {
            "id": 69,
            "risksport": "Diving (w/respiration equipment) > 80m"
        },
        {
            "id": 70,
            "risksport": "Diving (w/respiration equipment) up to 40"
        },
        {
            "id": 95,
            "risksport": "Skydiving"
        }
    ]
}

GET /nodes/{workflowname}


This service can be used to create a visualisation of a given workflow. Returns all nodes relevant vor the visualisation.

Possible response status:

Status code Description
200 Success

Example request:

riskine.com/nodes/pension-insurance

Example result:

{
    "returncode": 0,
    "result": [
         {
                    "data": {
                        "id": "156cb3bb-e02c-42ab-942d-e4be8711e2cc",
                        "textlabel": "Vorname",
                        "nodegroup": "",
                        "parent": "01f88390-a7ef-4003-b08d-09e80d4ba8aa"
                    },
                    "classes": "question"
        },
        {
                    "data": {
                        "id": "73ac5b4f-fe07-4bc1-aff1-95d06c9139f8",
                        "product": "PENS001",
                        "productname": "CustomPensionProduct"
                    },
                    "classes": "product"
        },
        {
                    "data": {
                        "id": "0dfc4e0a-f0c6-43ac-8bf4-8831430a5108",
                        "templatename": "InfoText"
                    },
                    "classes": "template"
        }
    ]
}

(The rest of the result was omitted)

POST /licensingdistrict


Possible response status:

Status code Description
200 Success
400 Data not properly specified

Example request:

{
    "zulassungsbezirk": "neu"
}

Example result:

{
    "returncode": 0,
    "result": [
        {
            "id": 44,
            "zulassungsbezirk": "KO Korneuburg"
        },
        {
            "id": 64,
            "zulassungsbezirk": "ND Neusiedl/See"
        },
        {
            "id": 65,
            "zulassungsbezirk": "NK Neunkirchen"
        },
        {
            "id": 95,
            "zulassungsbezirk": "WB Wr. Neustadt/Bezirk"
        },
        {
            "id": 98,
            "zulassungsbezirk": "WN Wr. Neustadt BPD"
        }
    ]
}

POST /schema/textlabels/resolve


Clients typically want to store data in their DB like this: person.gender: 2 and not like this: "Gender": "female", yet the labels are needed when displaying the data. This service provides a way to get the appropriate textlabels for all questions/answers in the graph from the API on-demand and in bulk. The results are modified via the following URL parameters:

Parameter Description
country Country. de, at, etc.
locale Language. de, de-DE, en, en-US, es, etc.
labelformat normal or empty for the usual question textlabels, short for the short labels and long for the long labels.
context Context filter

Possible response status:

Status code Description
200 Success
400 Data not properly specified

Example request:

{
    "person.gender": 2,
    "person.birthdate": "1980-02-03"
}

Example result:

{
    "returncode" 0,
    "result": {
        "person.gender": {
            "question": "What is your gender?",
            "answer": "female"
        },
        "person.birthdate": {
            "question": "What is your date of birth?",
            "answer": "03.02.1980"
        }
    }
}

Services under development


POST /projection


Under development. This service is intended to provide a possibility to scale the riskine risk model into the future. Could be used, for example, to warn the user of coming drastic changes in risk or to show additional analytics to the user.

POST /rules


Under development. Intended to be an API accessible rules engine specialized on the insurance sales workflow to manage rules directly in the graph database.

GET /rules


Under development. Intended to be an API accessible rules engine specialized on the insurance sales workflow to manage rules directly in the graph database.

Site automatically generated from md via Parsedown
Version 1.85.0