Get Formulas Structures API

Use this API to get the formulas structure for an insurance product. A structure is composed from all the input parameter keys expected by the all the formulas attached to the specified insurance product. Depending on that product configuration, the structure looks different from a product to another (see the example below).

Different Settings Lead to Different Structures

The API response includes the following details:

  • the structure for the premium calculation formula, attached to the product (if the case),

  • the structure for all the premium calculation formulas for each of the product items (coverages),

  • the structure for the underwriting formula (rules), attached to the product (if the case),

  • the structure for all the underwriting formulas for each of the product items (coverages),

  • the tariff type set on the product,

  • the underwriting type and the underwriting context type set on the product.

If necessary, in the API call you can specify a Validity Date and get the formulas structure that was valid for your product, at that date.

NOTE  
If no underwriting context type is defined, then the API returns an empty array for the uwRulesStructures array.

A user makes a call for the formula structure for a certain insurance product - indicated by a specified product code. The user wants to retrieve the formula structure that was valid at a certain date - respectively, 2021-05-21.

Copy 
let p = { "productCode": "BA_EMB" "validityDate": "2021-05-21"
}
ebs.callActionByNameAsync("FTOS_IP_GetProductFormulasStructuresAPI", p) .then(function(e) { console.log(e) })

The following data parameters must be included in the request:

Parameter Description
productCode The code of the insurance product.
validityDate (Optional) The reference date, prior to the current date, for getting an earlier version of the product formulas structure. When this key is not provided, the API returns the current version of the formula structure. Accepted formats are: yyyy-mm-dd, dd/mm/yyyy, dd-mm-yyyy, or dd.mm.yyyy.

This is an example of a response:

Copy 
{ "isSuccess": true, "errorMessage": null, "errorCode": null, "result": [ { "productCode": "BA_EMB", "tariffType": "perCoverage", "uwType": "perCoverage", "premiumCalculationStructures": [ { "itemCode": "HHR0", // this key is not available for tariff type = per product "formulaVersion": 1.0, "formulaStructure": [ { "key": "risks", "value": null, "masterType": "Collection", "subType": "Object", "objProps": "{\"Risk\":6,\"Module\":6,\"Price\":2}" }, { "key": "propertyInsuredAmount", "value": null, "masterType": "SimpleType", "subType": "Decimal", "objProps": null }, { "key": "propertyConstructionYear", "value": null, "masterType": "SimpleType", "subType": "WholeNumber", "objProps": null } ] }, { "itemCode": "HA", // this key is not available for tariff type = per product "formulaVersion": 1.0, "formulaStructure": [ { "key": "buildingInsuredAmount", "value": null, "masterType": "SimpleType", "subType": "Decimal", "objProps": null }, { "key": "constructionYear", "value": null, "masterType": "SimpleType", "subType": "WholeNumber", "objProps": null } ] } ], "uwRulesStructures": [ { "contextType": "Underwriting", "itemCode": "HA", // this key is not available for uw type = per product "formulaVersion": 1.0, "formulaStructure": [ { "key": "insuredAmount", "value": null, "masterType": "SimpleType", "subType": "Decimal", "objProps": null }, { "key": "seismicZone", "value": null, "masterType": "SimpleType", "subType": "Text", "objProps": null } ] } ] } ]
}

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.
productCode The code of the insurance product.
tariffType The Tariff Type defined on the product level - either perProduct or perCoverage.
uwType The Underwriting Type defined on the product level - either perProduct or perCoverage.
premiumCalculationStructures An array containing the input parameters for the premium calculation formulas attached to the specified product, or product items (coverages).
uwRulesStructures An array containing the input parameters for the underwriting formulas attached to the specified product, or product items (coverages).

The following are the error messages that can be encountered while calling the GetFormulasStructuresAPI:

Code Text Description
ERR.IP.50201 ERR.IP.50201 - 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.50202 ERR.IP.50202 - Invalid validity date! Invalid date for validityDate input parameter.
ERR.IP.50203 ERR.IP.50203 - Invalid key request! Missing parameters in the request or wrong parameter name.
ERR.IP.50204 ERR.IP.50204 - No active product identified! No active insurance product found.
ERR.IP.50205 ERR.IP.50205 - Error! The //code of product// insurance product was not approved at the requested date! No active insurance product found at the date specified in validityDate input parameter.

The FTOS_IP_GetProductFormulasStructuresAPI endpoint validates the API call request, searches for the specified product and returns all the expected input parameter keys for all the formulas attached to that insurance product.

FTOS_IP_InsuranceProductAPIs

From this library, use the GetFormulaInputParameters function (described below). This function wraps all the functions necessary to validate and return the formulas structure results.

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, for describing 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 input parameters formula structure, as described in the response description section.

This function gets the input parameters for the premium calculation formulas attached to the specified product, or product items (coverages). The function also uses other helper functions, implemented in the same library, to get the product details, the list of items, and the formulas attached on items.

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

Output parameters: An array containing objects with the following keys:

  • productCode - The code of the insurance product.

  • tariffType - The tariff type defined on the product (either perProduct or perCoverage).

  • uwType - The underwriting type defined on the product (either perProduct or perCoverage).

  • premiumCalculationStructures - An array containing the following objects:

  • object containing details about the product, or product items (coverages),

  • object containing the item code (when tariff type = perCoverage), the formula version number and an array with objects for each input parameter.

This function gets the input parameters for the underwriting formulas attached to the specified product, or product item - coverage (identified by item code, provided in the request). The function also uses other helper functions, implemented in the same library, to get product details and the underwriting formulas structure.

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

Output parameters: An array containing objects with the following keys:

  • productCode - The code of the insurance product.

  • uwRulesStructures - An array containing the following objects:

  • object containing details about the product, or product items (coverages),

  • object containing the underwriting context type, the item code (when underwriting type = perCoverage), the formula version number and an array with objects for each input parameter.

This function concatenates the results of the getPremiumFormulaStructure and getUWFormulaStructure functions into a single array. The function is called inside the endpoint only if the request passes the validation - namely 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 FTOS_IP_GetProductFormulasStructuresAPI.

Output parameters: An array containing objects with the following keys:

  • productCode - An object from the getPremiumFormulaStructure output parameters.

  • tariffType - The tariff type defined on the product (either perProduct or perCoverage).

  • uwType - The underwriting type defined on the product (either perProduct or perCoverage).

  • premiumCalculationStructures - An object from the getPremiumFormulaStructure output parameters.

  • uwRulesStructures - An object from the getUWFormulaStructure output parameters.