Function: calculatePremium

Calculate a premium amount for a policy based on a (minimum) set of required input variables.

Usage: calculatePremium

Within the API-framework a classification is included for the type of process or event for which a premium amount is to be calculated. The table below shows the different variants that can be used. In general the variant will determine the set of input and output data, the required parameters per variant are mentioned in the table.

# Variant Description
1 quickQuote Standard calculation with limited client specific input and some default/average settings.
2 offer Calculation requiring comprehensive client, object and contract input.
3 policyApplication Calculation requiring comprehensive client and object input.
4 policyChange Calculation based on new input combined with policy data.
5 policyRenewal Calculation based on policy data combined with claim or appraisal input.

Premium is calculated according to the actuarial formula for a specific product from a provider of financial products, and uses a dedicated set of parameters. The parameters used depend on the product and on the purpose (variant) for which the premium is calculated. In general, the more exact the premium amount needs to be, the more extensive the set of parameters.

General input parameters refer for example to the insured, a start date to determine the applicable rate version, or the payment term to calculate the corresponding installment. In addition, a calculation will need input with regard to the insured interest. For example:

  • For casualty and life insurance this can be an amount declared by the applicant, or an amount selected from a list of options.
  • When it comes to property insurance, the input will contain information regarding the object to be insured. This can be a registration identification like the license plate of a vehicle, or the address of real estate property. Based on that information, the calculation process may use external services to fetch additional information about the object. For instance the weight and original list price of a car, or the reinstatement value of a building.
  • Information about the (prospective) policy holder can also be required. In the example of car insurance that could be the age of the driver or policy holder, an address to determine regional premium differentiation, and claim history to determine the no-claim discount.

The exact information required depends on the specific provider and the type of financial product. The calculatePremium function offers a maximum of flexibility through the fact that all AFD attributes of choice can be included. The party that offers the API also specifies the set of mandatory and optional input and output parameters for the variants the API has to support.
Information that was derived or collected as part of the calculation process may also be added to the output data as extra information.

NOTE that in order to facilitate a swift and easy user dialogue one can allow for calls with partial filled input messages. This way a premium calculation dialog can be executed in subsequent steps using the validation feedback of the service to get a better dialog. The provider of the service has to specify which subsequent steps are supported and what data has to be specified for each step. This way of working is primarily relevant for more complex products.

Technical specifications: calculatePremium

Input: calculatePremium

All variants of premium calculation require a minimal set of input data, shown in the table below.

Name Variant Type Description
policyStructure
commonFunctional Entity for general information with regard to structure, handling and processing.
entityType all string Set to ‘default’.
dataCatalogVersion all ADNAFM Version of the data catalog on which the message is based.
functionVariant all APIVAR The function variant is used to determine the additional set of required and optional input and output data.
policy With entityType policyDetails.
businessline all ANDBRA Classification of the type of contract. E.g. to be used for addressing within a company.
porCompany all PORMAA The identification of the insurer is necessary to find the correct product and rate combination.
afdDefinitionName all string Name of the AFD-definition.
afdDefinitionVersion all string Version of the AFD-definition.
effectiveDate 3,4,5 date Date on which the data of this entity takes/took effect.
effectiveChangeDate 4 date Date on which the change takes effect. Not intended for the date on which the change is registered by the company / is registered on the contract.
renewalDate 5 date Anniversary of the contract. The following renewal date is included here.
paymentTermInMonths 3,4,5 integer The payment term is necessary to calculate the premium amount for the given term; monthly, bimonthly, quarterly, semesterly.
coverage all The coverage entity is intended for grouping coverage-related data. A coverage is the protection provided by the policy against a certain risk. 
entityType all string Unique identification of an entity.
coverageCode all ADNDEK This standardized code indicates: the type of coverage and the risks against which the coverage has been / will be taken out. Often a collective code of a cover against various risks.
Any additional attributes within the policyStructure.

Output: calculatePremium

The output of calculatePremium is a response body with an AFD structure containing a partial or full dataset. The minimal result is the calculated premium amount, plus possible taxes and costs.
In order to simplify processing it is advised that the input data is returned in the output for reference. Any additional information that was collected as part of the calculation process may also be added to the output for reference.
When used for insurance products from managing general agents (MGA – ‘volmacht’), the return of a premium per coverage of a policy is mandatory.

Name Variant Type Description
policyStructure
commonFunctional Entity for general information with regard to structure, handling and processing.
dataCatalogVersion all ADNAFM Version of the data catalog on which the message is based.
functionVariant all APIVAR The function variant is used to determine the additional set of required and optional input and output data.
policy With entityType policyDetails.
businessline all ADNBRA Classification of the type of contract. E.g. to be used for addressing within an company.
porCompany all PORMAA The identification of the insurer is necessary to find the correct product and rate combination.
afdDefinitionName all string Name of the AFD-definition.
afdDefinitionVersion all string Version of the AFD-definition.
coverage all string The coverage entity is intended for grouping coverage-related data. A coverage is the protection provided
by the policy against a certain risk.
entityType all string Unique identification of an entity.
coverageCode all ADNDEK This standardized code indicates: the type of coverage and the risks against which the coverage has been / will be taken out. Often a collective code of a cover against various risks.
grossPremiumInstallment all decimal Gross premium installment.
Any additional attributes within the policyStructure

Errors

When a negative response is generated, it follows the general rules as described in the Error section of the Status codes and error handling chapter.

Click below to see the Open Api Specification (3.0.0)

Feedback

Thanks for your feedback.

Post your comment on this topic.

Post Comment