5.1.1. Overview of the API-framework

The API-framework is designed in four levels to find the right API in a few steps. The four levels of the API-framework are:

• Category
• Cluster
• Operation
• Variant
  

In the remainder of this section all elements will be explained.

Category

The category is the highest level of the API-framework. It is divided into functional and technical functions. The functional category contains domain specific operations, for example about insurances and pensions, or comparison and advice. In this context, ‘domain’ means the financial services domain.
The technical category contains supporting operations for data exchange and process flows like sending and retrieving messages or initiating a session in a browser. The clusters, operations and variants in the technical category are described in chapter Technical functions.

Clusters

Within the categories, clusters are defined. A cluster is a domain with the same focus and working area, containing all (relevant) operations. SIVI considers clusters as the core elements within the API framework. SIVI built the processes of the functions around this framework. The clusters defined within the functional category in the API-framework are:

• Claim
• Contract
• Object
• Party
• Table
• Task
• Ticket

The clusters are concentrated around AFD structures. For example, the cluster claim is linked to the claimStructure. Thus, a cluster already indicates to a certain extent which data will be communicated.

Operations

Operations are the activities defined for a specific cluster and the associated datasets modeled in the AFD Structures. An operation is a request for a specific action. The actions include adding, changing and retrieving data. There are a few special actions on the data like renewal and termination of contracts, handling special limits of contracts and validation of objects.

Currently, the following operations are available in the API-framework:

• new: for adding new entries and performing rate calculation.
• change: for changing existing entries, this can be an entire dataset or sub part of an entry.
• retrieve: for getting information about stored entries.
• renewal: for periodic renewal of a contract
• specialLimit: for handling outside the standard boundaries of a contract.
• termination: for terminating or closing contracts and offers.
• validation: for validating objects with given attributes.
  

Variants

An operation may be performed in multiple ways. For example, a premium calculation can be executed for a new premium, a change of policy premium or a renewal premium. Each operation has a default variant, this variant handles most of the requests.
Variants are defined to specify a certain action in order to connect to operational processes within the API-owning organization. Each variant uses a subset of all attributes available. SIVI describes which attributes are mandatory in combination with a certain variant.

The variants currently available in the API-framework:

• <default>: Apply standard operation on the specified cluster.
• agent: Replace the current agent by a new agent.
• appraisal: Establish the value of a (potentially) insured object.
• basedOnOffer: Conversion of an offer into a contract.
• correction: Replace the entire input by a new version due to wrong input.
• correctionOffer: Replace the entire offer by a new version due to wrong input.
• detail: Apply a partial change.
• documentList: Obtain reference information of all available documents according to a query statement.
• documentRange: Obtain details of multiple documents based on a range of unique references.
• list: Obtain reference information of available data.
• loanList: Obtain reference information of available loans for a party.
• lossAdjustment: Determine recovery/repair or replacement cost of an insured object.
• masterAgreementList: Obtain reference information of available masterAgreements.
• notification: Notification of insurance information under special limit conditions.
• offer: All operations (new, change, retrieve, termination) performed on data of an offer.
• offerList: Obtain reference information of all available offers.
• offerOncontract: Offer for a change of an existing contract.
• offerRange: Obtain details of multiple offers based on a range of unique references.
• pensionList: Obtain reference information of available pensions for a party.
• policyList: Obtain reference information of available policies for a party.
• range: Obtain details of multiple available data based on a range of unique references.
• rate: Calculation rate for a contract on new of changed data.
• rateOffer: Calculation rate for an offer for a contract.
• rateOfferQuick: Calculate rate for an offer for a contract based on limited input.
• registration: Registration of operations taken of an underwritten contract or claim.
• repair: Repair or partially replace a (damaged) insured object.
• repatriation: Transport of a person, goods or vehicle back to the place of residence of the insured.
• financialMidTermChange: Obtain financial booking resulting from the mid-term change of a contract.
• riskAssessment: Evaluate risk exposure of a (potentially) insured person or object.
• salvage: Salvage a damaged insured object.
• status: Obtain of change the status of a contract, claim of ticket.
• statusOffer: Obtain status information of an offer of a contract by a unique reference.
• surrender: Terminate a contract with restitution of the surrender value (life insurance).
  

For each combination of AFD structure and operation the applicable variants are shown in the table below. If a cell is empty, no operation acts on that AFD structure. An operation can refer to more than one AFD structure: