Function: changePolicy

Partial or complete replacement of the data from an existing policy.

Usage: changePolicy

This function has a broad range of functional variants, but there are also technical variants in the choice of implementation.
Changing an entity can be done by completely overwriting it with a new version, or by changing only part of the existing information and leaving the rest untouched. More information on the available choices can be found in this section.

Another functional choice with implications for the technical implementation is the ‘delete’ option. For financial products there are often regulations which impose a certain period over which certain information (advice, offer, policy) needs to be kept available for audit purposes. Because of that reason, the termination or expiration of a policy is grouped under the changePolicy function.

Changing a policy can have a wide variety of reasons; when something changes in the circumstances of the risk covered by the policy (new car, new house, marriage, divorce) it can lead to a mid-term update of the policy. Then there are factors inherent to the policy itself which can be a reason for an update, like installments, renewal and expiration. Another group has to do with factors external to the policy like voluntary suspension of coverage because, for example, a long term stay abroad, or a forced suspension of coverage due to payment problems.
A policy can be linked to a package or master agreement, and those links can be undone. Finally, a policy can be terminated on request of the policy holder for a number of reasons, through selling or loss of the property or a change of situation regarding life insurance, to name a few.

All these situations have their own requirements in terms of required data for in- and output, and workflow handling to initiate the change and process it. The functionVariant parameter is provided to indicate the specific circumstances in order to enable more detailed arrangements for the use of the API-function.

# Variant Description
1 correction Replace the entire policy by a new version.
2 installment Update the installment date of the policy.
3 policyRenewal Update the renewal date and relevant renewal properties.
4 update Processing of a mid-term policy modification.
5 packageInclude Add an existing single policy to a package policy.
6 packageExclude Turn a policy from a package policy into a single policy.
7 changeAgent Replace the current agent reference by a new agent reference.
8 startSuspension Change the policy status from active to to suspended.
9 stopSuspension Change the policy status from suspended to active.
10 premiumSuspension Suspend the premium installments of the policy (life insurance).
11 reinstatement Reactivate a terminated policy.
12 midTermTermination Terminate the policy before the renewal date (with premium settlement).
13 terminationAtRenewal Terminate the policy per renewal date (no premium settlement).
14 terminationAtEffectDate Terminate the policy per effect date (undo policy).
15 expiration Terminate the policy per expiration date (life insurance).
16 surrenderPermanentLife Terminate the policy with restitution of the surrender value (life insurance).

Technical specifications: changePolicy

Input: changePolicy

The changePolicy function uses the base-url and endpoint to address a specific policy, and the unique policy identification is part of the endpoint.
From a functional point of view there are no mandatory attributes, the body section can be used to provide a complete or partial set of policy information.
The required attributes for the different variants are 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 ADNBRA 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.
effectiveChangeDate all 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 3 date Date on which the current term expires and the new term starts.
paymentTermInMonths 2 integer The payment term of the premium amount; monthly, bimonthly, quarterly, semesterly.
packageNumber 5, 6 integer packageNumber.
brokerNumber 5 integer Broker number.
contractNumber all string The identifying characteristic assigned by a company or underwriting agent.
status all integer Indication of the current status.
object Object with any entityType.
coverage Coverage with any entityType.
party Party with any entityType.
Any additional attributes within the policyStructure.

Output: changePolicy

There are three basic types of output which are described in the Output section of the Design principles chapter.

A positive response for the changePolicy function always contains a dataset. The minimal result is a transactionReference or transactionReferenceNumber.
In order to simplify processing it is advised that the input data is returned in the output for reference. As mentioned in the Usage section, any additional information that was collected during the transaction may also be added to the output for reference.

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 ADNBRA 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.
contractNumber all string The identifying characteristic assigned by a company or underwriting agent.
referralNumber string The number assigned to refer. The insurer / underwriting agent can determine which attribute is used for this.
effectiveChangeDate all 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 3 date Date on which the current term expires and the new term starts.
paymentTermInMonths 2 integer The payment term of the premium amount; monthly, bimonthly, quarterly, semesterly.
packageNumber 5, 6 integer packageNumber.
brokerNumber 5 integer Broker number.
status 12, 13, 14, 15, 16 integer Indication of the current status.
object Object with any entityType.
coverage Coverage with any entityType.
party Party with any entityType.
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