Get Premium Amount API

Use this API to calculate the premium for each coverage (product item) of an insurance product. For each product item, the input keys expected by formula engine are required. In order to get the premium calculation, the FTOS_IP_PremiumAmountAPI endpoint calls the formulas attached on each item included in the request and identified by its code. If necessary, in the API call you can specify a date and get the price that was valid at that date, for your product item.

A user makes a call for the price (premium amount) for a product item configured on a property insurance product. The user wants the premium amount formula which was valid at a certain date - respectively, 2021-05-21.

Copy 
 var  p = {
    "insuranceTypeName": "Home",
    "productCode": "BA_EMB",
    "validityDate": "2021-05-21",
    "insuranceProductItemDetails": [{
        "code": "HHR0",
        "calculationDetails": {
            "risks": [{
                "Risk": "Earthquake",
                "Module": "M1",
                "Price": 0
            }, {
                "Risk": "Land Slide",
                "Module": "M1",
                "Price": 0
            }, {
                "Risk": "Floods",
                "Module": "M1",
                "Price": 0
            }, {
                "Risk": "Windstorm",
                "Module": "M1",
                "Price": 0
            }],
            "propertyInsuredAmount": 100000,
            "propertyConstructionYear": 1980
        }
    }, {
        "code": "HA",
        "calculationDetails": {
            "buildingInsuredAmount": 23.45,
            "constructionYear": 100
        }
    }]
};

ebs.callActionByNameAsync("FTOS_IP_PremiumAmountAPI",p)
.then(function(e){
    console.log(e)
})

Here is the list of data parameters included in the request:

Parameter Description
insuranceTypeName The name of an Insurance Type configured in the system and stored on the Insurance Type entity.
productCode The code of the Insurance Product.
validityDate The reference date, prior to the current date, for calling an earlier version of the formula. This key is not mandatory. When it is not provided, the API calls the current version of formula. Accepted formats are: yyyy-mm-dd, dd/mm/yyyy, dd-mm-yyyy, or dd.mm.yyyy.
insuranceProductItemDetails Array with details to identify and run the formulas.
code The code of the Item.
calculationDetails Object containing the keys needed to run the formula. The object structure can be different for each item, based on the formula configuration.

This is an example of a response:

Copy 
 {
    "isSuccess": true,
    "errorMessage": null,
    "errorCode": null,
    "result": [
        {
            "insuranceProductItemFormula": "EmbededBankAssurancePremiumAmountFormula",
            "formulaResult": {
                "risks": [
                    {
                        "Risk": "Earthquake",
                        "Module": "M1",
                        "Price": 0
                    },
                    {
                        "Risk": "Land Slide",
                        "Module": "M1",
                        "Price": 0
                    },
                    {
                        "Risk": "Floods",
                        "Module": "M1",
                        "Price": 0
                    },
                    {
                        "Risk": "Windstorm",
                        "Module": "M1",
                        "Price": 0
                    }
                ],
                "propertyInsuredAmount": 100000,
                "propertyConstructionYear": 1980,
                "risksCalculatedPrices": [
                    {
                        "Risk": "Earthquake",
                        "Module": "M1",
                        "Price": 0.0054
                    },
                    {
                        "Risk": "Land Slide",
                        "Module": "M1",
                        "Price": 0.001
                    },
                    {
                        "Risk": "Floods",
                        "Module": "M1",
                        "Price": 0.001
                    },
                    {
                        "Risk": "Windstorm",
                        "Module": "M1",
                        "Price": 0.013
                    }
                ],
                "baseQuotation": 0.0204,
                "premiumAmount": 20.4
            }
        },
        {
            "insuranceProductItemFormula": "HomeAssistance",
            "formulaResult": {
                "buildingInsuredAmount": 23.45,
                "constructionYear": 100,
                "coefHomeAssistancePrice": 0.001,
                "premiumAmount": 0.0002345
            }
        }
    ]
}

Response description:

Key Description
Error code Error code.
Error message Error message.
isSuccess Marks whether the request was successful or not.
result Array of objects containing details about the prices.
insuranceProductItemFormula Name of a record from the Insurance Product Item Formula entity, containing the Formula attached on a Product Item.
formulaResult The result returned by the Formula.
code The insurance product item code.

The following are the error messages that can be encountered while calling the Get Premium Amount API:

Code Text Description
ERR.IP.50101 ERR.IP.50101 - Invalid validity date format! Please, use yyyy-mm-dd or dd/mm/yyyy or dd-mm-yyyy or dd.mm.yyyy! Invalid date format for validityDate input parameter.
ERR.IP.50102 ERR.IP.50102 - Invalid validity date! Invalid date for validityDate input parameter.
ERR.IP.50103 ERR.IP.50103 - Invalid request! Missing parameters in the request.
ERR.IP.50104 ERR.IP.50104 - No active product identified! No active insurance product found.
ERR.IP.50105 ERR.IP.50105 - Error! The //code of product// insurance product was not approved at the requested date! No active insurance product found, for the date specified in the validityDate input parameter.
ERR.IP.50106 ERR.IP.50106 - Product doesn't have any product items configured! The insurance product identified has no insurance items.
ERR.IP.50107 ERR.IP.50107 - Invalid insurance item code. Invalid product item code.

The FTOS_IP_PremiumAmountAPI endpoint calculates the premium amount for the items included in a product configuration. The endpoint runs the formulas assigned to each item, simulating the Test Scenario functionality available on product level, in Innovation Studio.

From the FTOS_IP_InsuranceProductAPIs library, the following functions are used for getting the price for the items:

This function validates the request fields.

Input parameters: inputData - The object containing the keys needed to call the endpoint.

Output parameters: An object containing the following keys to describe the result of the validation:

  • isSuccess - true/ false - The boolean that shows whether the validation is successful.

  • errorMessage - A null value or an error message as described in the error messages list.

  • errorCode - A null value or an error code as described in the error messages list.

  • result = An empty array [] or an array with details about the price, as described in the response description section.

This function runs the formulas attached to the specified items - identified by the code provided in the request. The function uses other helper functions, implemented in the same library, to get the product details on a specific date, the list of items, and the formulas attached to the specified items. The calculatePremium() function is called inside the endpoint only if the isSuccess key from the response of the validateRequest function is true.

Input parameters: inputData - The object containing the keys needed to call the endpoint.

Output parameters: An array containing objects with 2 keys:

  • insuranceProductItemFormula - The name of the formula used to calculate the price for the item.

  • formulaResult - The actual result returned when calling the formula.