Premium Amount API

Use this API to get premium calculation results, such as:

  • the premium amount for an insurance product (total premium amount),

  • the premium amount for different product items (coverages) included in an insurance product,

  • the premium amounts for each coverage, based on the premium coverage split percentages defined at the product level,

  • the price result that was valid at a certain date, for a specified insurance product, or product item (coverage).

NOTE  

Starting with the 4.6.0 release, this API is compatible with the OpenAPI v3.0 standard.

The Premium Amount API endpoint runs the premium calculation formulas assigned to each product, or product item (coverage), simulating the Test Scenario functionality - available for users in FintechOS Studio.

The results are in line with the Tariff Type set at the product level. An insurance product can have the tariff type set either to perProduct or perCoverage.

For a valid API request, include all the formula Input Keys expected by the Business Formulas engine (see below). When needed, use the Validity Date key to get the price result that was valid at that date, for the specified product, or product item (coverage).

All the requests through this API and their responses can be saved into the Product Interogation History entity. This action is available if the system parameter Product Interogation History Enablelog value is set to 1.

A user makes a request for calculating the price (premium amount) for two product items (coverages) 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 
{
    "insuranceTypeName": "Personal Accidents",
    "productCode": "PA",
    "validityDate": "2022-12-05",
    "sourceRecordName": "P7857",
    "sourceRecordId": "0AFE8D0B-F423-44F4-9638-DEE696BF0B0E",
    "premiumCalculationDetails": [{
        "itemCode": "DPA", 
        "calculationDetails": {
            "age": 30,
            "coverage": "Death by accidents",
            "frequency":"annually",
            "sumInsured":3000
        }
    },{
        "itemCode": "PDA", 
        "calculationDetails": {
            "age": 30,
            "coverage": "Permanent Disability",
            "frequency":"annually",
            "sumInsured":3000
        }
    },
            {
        "itemCode": "ICPA", 
        "calculationDetails": {
            "age": 30,
            "coverage": "Income Compensations",
            "frequency":"annually",
            "sumInsured":3000
        }
    },
            {
        "itemCode": "MEACC", 
        "calculationDetails": {
            "age": 30,
            "coverage": "Medical Expenses",
            "frequency":"annually",
            "sumInsured":3000
        }
    }
]
}

The following data parameters must be included in the request:

Parameter Description
calculationDetails Object containing the keys needed to run the formula. The object structure is used for testing the formula attached to the specified product item (coverage). The structure differs from item to item, based on the formula configuration.
insuranceTypeName The name of an Insurance Type configured in the system and stored on the FTOS_IP_InsuranceType entity.
itemCode The code of the product item (coverage). This key is not available for products which have the Tariff Type set to perProduct.
premiumCalculationDetails Array with details to identify and run the formulas.
productCode The code of the Insurance Product.
sourceRecordId The Id of the record that the system is calculating the premium for.
sourceRecordName Text identifying the record that the system is calculating the premium for.
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.

This example contains calculation details for two coverages:

Copy 
{
  "isSuccess": true,
  "errorMessage": null,
  "errorCode": null,
  "result": [
    {
      "totalPremiumAmount": 216,
      "tariffType": "perCoverage",
      "premiumCalculationResults": [
        {
          "itemCode": "DPA",
          "premiumAmount": 4.8
        },
        {
          "itemCode": "PDA",
          "premiumAmount": 57.6
        },
        {
          "itemCode": "ICPA",
          "premiumAmount": 96
        },
        {
          "itemCode": "MEACC",
          "premiumAmount": 57.6
        }
      ],
      "formulaDetails": [
        {
          "itemCode": "DPA",
          "formulaResult": {
            "age": 30,
            "coverage": "Death by accidents",
            "frequency": "annually",
            "sumInsured": 3000,
            "BaseRate": 0.002,
            "CoefFrequency": 0.8,
            "CoefAge": 1,
            "CoefAmountInsuredItem": 1,
            "ItemPremiumAmount": 4.8,
            "PA_Final_Premium": 4.8
          }
        },
        {
          "itemCode": "PDA",
          "formulaResult": {
            "age": 30,
            "coverage": "Permanent Disability",
            "frequency": "annually",
            "sumInsured": 3000,
            "BaseRate": 0.024,
            "CoefFrequency": 0.8,
            "CoefAge": 1,
            "CoefAmountInsuredItem": 1,
            "ItemPremiumAmount": 57.6,
            "PA_Final_Premium": 57.6
          }
        },
        {
          "itemCode": "ICPA",
          "formulaResult": {
            "age": 30,
            "coverage": "Income Compensations",
            "frequency": "annually",
            "sumInsured": 3000,
            "BaseRate": 0.04,
            "CoefFrequency": 0.8,
            "CoefAge": 1,
            "CoefAmountInsuredItem": 1,
            "ItemPremiumAmount": 96,
            "PA_Final_Premium": 96
          }
        },
        {
          "itemCode": "MEACC",
          "formulaResult": {
            "age": 30,
            "coverage": "Medical Expenses",
            "frequency": "annually",
            "sumInsured": 3000,
            "BaseRate": 0.024,
            "CoefFrequency": 0.8,
            "CoefAge": 1,
            "CoefAmountInsuredItem": 1,
            "ItemPremiumAmount": 57.6,
            "PA_Final_Premium": 57.6
          }
        }
      ]
    }
  ]
}

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.
formulaDetails Array with details - either the result returned by the formula attached on the product level OR the results returned by the formulas attached to product items (coverages), and their item codes.
premiumCalculationResults Array with objects, containing the item code and the premium amount.
tariffType The Tariff Type defined on the product level. The available options are either perProduct or perCoverage.
totalPremiumAmount The total premium amount for the product.

The following are the error messages that can be received 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 (coverages) configured! The insurance product identified has no insurance items (coverages).
ERR.IP.50107 ERR.IP.50107 - Invalid insurance item code. Invalid product item (coverage) code.
ERR.IP.50108 ERR.IP.50108 - sourceRecordName is mandatory for premium calculation! Source record name is mandatory.
ERR.IP.50109 ERR.IP.50109 - sourceRecordId must be uniqueidentifier type! If transmitted, it has to be a GUID.

The FTOS_IP_PremiumAmountAPI endpoint runs the formulas assigned to each product, or product item (coverage), in line with their defined tariff type.

For perProduct tariff type, the endpoint runs the formula assigned to the product and returns the total premium amount and, also, the premium amounts for the product items (coverage), according to the premium coverage split percentage set on each coverage.

For perCoverage tariff type, the endpoint runs the formulas assigned to each product item (coverage), returns the result for each coverage and, also, returns the total premium amount for the specified product, summing up the premium amounts of all coverages.

Insurance Product APIs

From this library, for getting prices for the products, or product items (coverages), use the following functions:

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 products or coverages - 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 (coverages), and the formulas attached to the specified coverages. 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 the following keys:

  • totalPremiumAmount - The total premium amount for the product.

  • tariffType - The Tariff Type defined on the product level. The option set values are: perProduct and perCoverage.

  • premiumCalculationResults - An array with objects containing item codes and premium amounts.

  • formulaDetails - An array with the result details - either the result returned by the formula attached on the product level OR the results returned by the formulas attached to product items (coverages), and their item codes.