# Policy API Overview
Policy management is the most important domain for the insurance industry. To help development teams to develop policy related application (app) in a faster and easier way, InsureMO GI provides a set of atomic APIs which cover the whole general insurance policy lifecycle.
By using our ready-to-use atomic APIs, since almost all complex business scenarios around GI business have been considered, the efforts of developing policy transaction and management related app will be much lower and system maintainability will be much easier.
## Key API Stage and Microservices
Basically, our policy API can be divided into four sub-sets according to the transactional sequence. Each sub-set corresponds to a backend microservice on the InsureMO GI platform.
- Proposal
- Endorsement
- Policy
- Quotation
Below is a basic illustration flow of how these APIs can be used during policy transaction.
### Proposal
A proposal is designed specifically for traditional business which is normally operated offline with stable business volume within certain scope.
The proposal APIs provide a list of actions, such as creating, saving, calculating, underwriting, and versioning. It can be used to handle the basic transaction scenarios in insurance proposal business.
From business perspective, the current API supports single policy, package policy, and master policy for all direct business and related activities through different request/response payload in the API.
Product configuration is a prerequisite for the use of these APIs because you need different product elements to configure the APIs. Moreover, you need to understand policy model in order to use these APIs under this section.
Policy Lob and risk levels are mandatory for the creation of a proposal. There can be many steps involved before a policy is finally issued.
Currently, three typical types of issuance flow are supported, with digital business flow especially considered:
* Direct issuance: request from the channel system to issue the policy directly.
* App issuance: calculate the premium, bind the proposal, and issue the policy with payment in the e-commerce purchase process.
* Traditional issuance: for agent/broker/staff portal. It carries through a series of internal information update and underwriting.
An API with an **Accelerator** tag indicate that the API can facilitate the building of the first two scenarios mentioned above. It combines certain atomic proposal APIs together. If not all combined functions are required, developers can still use the atomic APIs to build all required functions.
### Endorsement (Endo)
There could be continuous business amendments to be made after an existing insurance policy is issued. The amendment is called an endorsement which includes operations like adding or removing coverage, changing policy limits, and altering other policy provisions.
Similar to proposal APIs for new business, endorsement transactions also have a set of basic APIs to perform actions such as creating, saving, calculating, underwriting, and versioning.
As a prerequisite, you need to know the endorsement model to use the endorsement APIs. For the basic information endorsement, the policy model is an essential part to understand because new policy information is passed into the request.
### Policy (PA)
A policy contains more than core policy transactions. In order to issue a policy, there are some independent scenarios which can be applied across all transactions, such as underwriting history, master policy, etc.
For such scenarios, it's considered as "Policy" which is irrelevant of any of the three transaction steps mentioned above.
### Quotation
A quotation is typically provided by an insurance company in response to an inquiry from a potential customer. It entails details such as the premium, coverage limits, and any exclusions or deductibles that may apply.
The purpose of a quotation is to allow potential customers to know the cost of insurance coverage, without committing to anything.
Nowadays, insurance business is conducted more and more in a digital way. Customers can easily get an insurance quotation through various channels to make pricing comparison or even satisfy mere curiosity.
The concept of quotation in InsureMO is slightly different from others. It has a special focus on digital channel related business.
The typical characteristic of such quotations is its high business volume and yet low conversion rate. Take some big aggregators for example.
There could be a huge number of API calls within a short period, but only a small portion of them can be converted to real business deals. This is different from our ***Proposal*** concept, which is meant for traditional business with a stable business volume and much higher conversion rate.
Quotation is an optional process. Although the proposal API can do everything the quotation API can do, the key to differentiating and adopting quotation API is its processing volume and system performance. If the digital process volume is too high and frequent, we recommend you adopt quotation API for its excellent system performance and lower infrastructure cost.
Only when quotation is about to be issued or to be reviewed manually by the internal team, does it need to be converted to a proposal for further processing. Once a quotation is converted to a proposal, it will be kept in the proposal stage and cannot return to a quotation.
### Micro Insurance (Mass)
Microinsurance is a type of insurance designed to cater for those innovation products designed specifically for digital usage. One of the typical examples is the personal accident product which can be sold via digital channels like uber tip or online railway tickets.
Transaction for such type of insurance is quite straightforward while the volume can be huge. A good system response performance is highly required for such scenario.
In addition, from an insurance company perspective, although they will store the micro policy, usually for downstream purpose like bcp or reporting, the policy needs to be combined to a couple of summary policy in order to reduce the system pressure.
## Key API Atomic Behavior
### Policy Persistence
***Data persistence***, which can also be referred as ***"CRUD - Create, Retrieve, Update, Delete"***, is the most important behavior of our atomic API.
The general insurance policy model can be very complex. There can be different sets of persistent data for different product lines.
Facilitated by our product factory and data dictionary engine, all these business line data variances can be dynamically configured. Our data persistence API can instantly accommodate to model changes without changing system source code.
Although both quotation and proposal have persistence related API, the way they are achieved is quite different.
Technically, the most important aspect of proposal is all of its policy element ID. Unlike quotation which is organized in a soft way, the proposal API must have policy element ID passed in each layer to facilitate data persistence.
API example: /proposal/core/proposal/v1/createEx, /proposal/core/proposal/v1/updateEx, /proposal/core/proposal/v1/load
### Policy Search
If there are too many policies to be created or issued, you may encounter severe performance issues at a certain point in time. The key reason can be endless database pressure which is hard to tackle.
Now ***"Read-write separate"*** mode is adopted on our platform. For any transaction, it can visit search engine first. Only when specific transaction number is identified, can it interact with database. In this way, database pressure can be considerably reduced.
Also, facilitated by our search engine and Elasticsearch (ES) server, policy can be quickly searched out by key fields in a configurable way. We have developed some APIs which allow query results to be exported as Excel to facilitate your check.
API example: /proposal/v1/queryPolicy, /proposal/v1/exportPolicy
### Policy Versioning
Policy can constantly change according to business requirements. It can often happen through final policy/endorsement issuance or experience frequent changes during proposal and endorsement entry stage.
It's mandatory to keep all those issued versions and it's encouraged to keep all changes for audit and troubleshooting purpose.
Currently, on our GI platform, all such proposal or endorsement changes are properly tracked, even for those changes made during the entry stage. Although such sophisticated changes are being tracked every day, there will not be any performance issue at any transactional points. It's all being supported by underlying platform APIs.
API example: /proposal/core/proposal/v1/updateEx, /proposal/core/proposal/v1/issuePolicyEx, /endo/core/endo/v1/issueEndorsementEx
### Policy Numbering
Each business transaction needs a unique reference number.
In terms of policy admin, system generates a quotation number, a proposal number, a policy number and an endorsement number corresponding to different business transaction stages.
As a default system behavior, policy numbering is generated when persistence related API is called for each stage for the first time.
If the default number does not satisfy the business requirement, developers can either extend the number by numbering configuration module or manually pass the right number in the request body.
API example: /proposal/core/proposal/v1/generatePolicyNo, /proposal/core/proposal/v1/generateProposalNo
### Policy Calculation and Rule Check
Our atomic APIs not only tackle those data related aspects, but also interact with our configuration engine to achieve automatic premium calculation or business rule check.
In summary, below is a list of key aspects supported:
1. Calculation (Logic defined in rating engine)
1.1) Full Calculation: calculate the whole policy rating based on new business/endorsement transaction rating node.
1.2) Partial Calculation: calculate one specific calculation node for partial premium or fee calculation
2. Rule Check (Logic defined in rule engine)
2.1) Underwriting Rule: perform underwriting rule check and throw underwriting message.
2.2) Validation Rule: perform validation rule check and throw validation message.
2.3) Auto Attachment Rule: auto-attach specific element based on business condition.
2.4) Endorsement Content: auto-generate endorsement change content.
API example: /proposal/core/proposal/v1/autoUnderWriting, /proposal/core/proposal/v1/validate
## Complex Business Scenario Handling
### Product Bundling
Each product or risk belongs to one specific category. More and more insurance products tend to combine risks of different categories together as a bundle for sale.
Based on our rich industry experience, from the perspective of system modeling, we have noticed these bundles can consist of components from different layers:
* Coverage Bundle
* Risk Type Bundle
* Product Bundle
* Policy Bundle
It's our design to make policy API flexible enough to support component assembly for each of these layers.
| Policy Level | Can Bundle Different Lines | How to Bundle |
| ---- | ---- | ---- |
| Policy | Yes | Call policy submission API to combine different policies together. |
| PolicyLob | Yes | Define multiple products in product factory and link to policylob level. |
| PolicyRisk | Yes | Define multiple risk types in product factory for one product and link to policyrisk level. |
| PolicyCoverage | Yes | Define multiple coverage with different types in product factory for one product and link to policycoverage level. |
### Group Policy
Group policy stands for the ones which include hundreds, thousands even to millions of insured risks. Unlike life business which generally distinguish single and group policies as different types of business, it's a common practice to support both single and group transactions in one general insurance system.
Group policy handling is always complex. Without a proper architecture in place, a lot of business implementations are very likely to fail under performance pressure and develop into tricky problems.
For group policy handling, based on different business volume and transaction pattern, different system solutions and APIs needs to be imposed. From the InsureMO GI prospective, we have summarized all kinds of structural variances and provided corresponding atomic APIs. You need to completely understand the business scenarios and pick the right API for your business requirement.
| | Single & Multiple Insured | Group - Schedule | Group – Insured | Master | Micro Insurance | Submission |
|--|--|--|--|--|--|--|
| Sample Product Type | Family Health, Family Travel Workaround similar to group | Workers compensation or engineering with employee schedule
Agriculture insurance with animal schedule | Motor fleet
Group Health, Group Travel
Group Property | Marine Cargo
Group Health | Flight delay
Package return
Trip accident | Motor Fleet |
| Structure | Policy
- Lob
- Risk
- Coverage
- Schedule | Policy
- Lob
- Risk (Risk/Virtual Insured/Coverage Group)
- Coverage
- Schedule (Detached) | Policy
- Lob
- Risk (Detached)
- Coverage Group (Not Risk, Direct Add in DD)
- Coverage | Master Policy
- Lob
- Coverage Group (Not Risk, Direct Add in DD)
- Coverage
Certificate Policy (Detached)
- Lob
- Risk
- Coverage | Follow single policy
quotation scenario with simplified persistence method | Multiple Policy connected by Submission |
| Insured As Max Number of Insured | Risk in Policy
Risk <100
Schedule < 500 | Risk or Detached Schedule
Risk/Coverage/Group < 100
Detached Schedule > 10,000 | Detached Risk
Risk/Coverage/Group < 100
Detached Risk > 10,000 | Risk Certificate Policy
Certificate Policy >10,000 | Risk in Micro
Micro Policy > 1,000,000 | Risk in Policy
Normal Policy > 1,000,000 |
| Different Expiry Date | No | No | No | Yes | Yes | Yes |
| UI Operation Experience | Together | Together | Together | Separate | Independent with API & Upload | Separate or Together |
| Premium Calculated | At coverage and schedule not participate | At coverage and schedule not participate | At detached Coverage then accumulate to group
Or coverage under group directly | At Certificate not sum up to master | No need, fixed premium logic | At Coverage and no - sum up calculation |
| Performance If volume high | Bad | Excellent | Excellent | Good | Super Excellent | Excellent |
| Implementation Cost | Low | Medium High | High | High | High | High |
| API Set | Standard Proposal API | Standard Proposal API
Detached Schedule API | Standard Proposal API
Detached Risk API | Standard Proposal API | Standard Micro Insurance API | Standard Proposal API with Submission API |
| Suggestion | Applicable to most of the scenarios | Applicable to scenarios where any of the object item is too many while it doesn't participate in calculation individually.
Schedule doesn't suggest having individual effective date unless totally irrelevant to premium | Applicable to scenario where insured number is too many while requiring operating together and individual coverage group doesn't suggest changing or deleting during endorsement | Applicable to scenario where business transaction is decoupled | Applicable to scenario where business volume is super high | Frequently used in some regulated market that each motor policy must be processed as an independent policy |
### Pricing Comparison
Pricing comparison is another common business scenario. In order to compare the prices, the system is required to generate multiple versions and calculate premium for each of them.
It could be just coverage level comparison handled by plan concept or entire proposal comparison by different proposal versions.
API example: /proposal/core/proposal/v1/quotationVersion/createNewQuotationVersion, /proposal/core/proposal/v1/quotationVersion/updateQuotationVersionInfo
| Characteristics | Policy Plan | Multiple Proposal Version |
| --- | --- | --- |
| Structure Illustration | Policy
- PolicyRisk (Select One Plan)
- PolicyCoverage
- PolicyBenefit
- PolicyPlan
- PolicyCoverage
- PolicyBenefit | Policy (Version 1)
- PolicyRisk
- PolicyCoverage
Policy (Version 2)
- PolicyRisk
- PolicyCoverage |
| API Set to Use | Standard Quotation/Proposal API | Additional ProposalVersion API |
| Within Single Proposal | Y | N |
| Change Scope | Only coverage/benefit/form under policy risk | Whole proposal |
| Business Prospective | Consumer Business Mostly | Commercial Business Mostly |
### Underwriting
Basically, there are two types of underwriting:
* Auto Underwriting
* Manual Underwriting
Auto underwriting is quite simple to achieve. We provide several atomic APIs which can check API request body based on underwriting rule configuration. These API will throw underwriting message if any rule fails.
As compared, manual underwriting is a super more complex process. To get a manual underwriting process working, system needs to combine behaviors of different domains:
1. Policy domain to get risk details and change after review.
2. Underwriting domain to record underwriting comments and history.
3. URP domain to get user authority for check.
4. Workflow domain to send and maintain the task.
Now there's no single core API which can complete all above tasks. Instead, we provide core API for each of the above-mentioned domains. They need to be orchestrated to achieve the full underwriting features.
API example: /proposal/core/proposal/v1/updateEx, /proposal/core/proposal/v1/autoUnderWritingDecision, /pa/autoUnderWriting/v1/manual/load
### Branch Segregation
In a big organization, there is always a requirement that transaction performed by each branch should be segregated with each other. Usually, a transaction performed by the target branch will be viewed by this branch and all its parent branch. Meanwhile, the subordinate branch should not view this transaction.
By default, the platform does not have a branch validation embedded in core API, because some organizations might have specifically different rules in this area. But there are some mechanisms provided at the platform level which help address this issue more easily.
Take UI for example. Our platform provides a common UI business component "BranchTreeSelect". With this component, by selecting a certain branch, the user can see the branch itself and its subordinate branch.
Take policy API for example. There are usually the following key user behaviors:
1. Create Policy Action
Create UI: Adopt branch component.
Create Core API：Save self branch in object/DB. Save self and all parent branches in ES.
Create iComposer API: Validate branch in the allowed list against user profile to avoid data tempering.
2. Search Policy Action
Search UI: Adopt branch component.
Search Core API: Search in ES by your currently operating branch in the request. API will return transaction either for the mentioned branch itself (index field = orgCode) or for the mentioned branch and its subordinate branch (index field = fullOrgCode).
Search iComposer API: Validate branch in the allowed list to avoid data stealing.
3. Load Policy Action
Load UI: Adopt branch component.
Load Core API: Load by ID secured by entity signature returned from search to avoid data stealing.
4. Save Policy Action
Save UI: Set the branch field as read-only.
Save Core API: Update ID secured by entity signature returned from search to avoid data tempering.
### BCP Fee Integration
When there's a requirement for policy admin to integrate with third-party BCP system for prepayment and billing, it needs to generate policy fee information and store it before actual integration.
Although the actual fee to be generated can be very different from client to client, the structure of the fee information persistence is quite common and standard among different carriers.
To facilitate the process, policy fee related API is provided by the platform for developers to persist such information. This type of API is a separate set irrelevant with policy key transaction APIs.
API Example: /pa/core/policyFeeInfo/v1/createEx, /pa/core/policyFeeInfo/v1/update
### Other Policy Information
In real business scenarios, there can be information irrelevant to policy version. Take whether policy is allowed for renewal as an example. Normally, if we add a field, changing the field always means creating a new endorsement. This change is considered as part of policy version change via standard endorsement API.
However, in some cases, if you want to flag and change it without creating a separate endorsement, this field cannot be put in the standard policy object. It must be configured at another separate policy object. If it's configured, another separate policy API will be called to load and update the information.
It helps simplify the policy version control. Do remember that development will get complicated because it fires additional API calls to accommodate.
API Example: /proposal/core/proposal/v1/policyOtherInfo/updateEx, /proposal/core/proposal/v1/policyOtherInfo/loadByPolicyId
## Extendability and Configuration Support
One of the strengths of InsureMO GI API is its flexibility. Supported by the rich configuration capabilities offered by the InsureMO technical platform, a lot of API behaviors can be adjusted such as:
### Product Configuration
Impact Area: All API Payload
The policy API payload can be dynamically generated based on the product structure and its component configuration.
It's a prerequisite that product must be configured in product configuration module and data dictionary is synchronized at technical product level. During API usage, it's important that all the policy element code should match with the product definition.
### Data Model and Field Configuration
Impact Area: All API Payload
All data objects and fields in policy API payload can be viewed in data dictionary. In addition, you can add more dynamic objects and fields for more personalized information to be captured via API.
It's a prerequisite that a product must be configured in product configuration module, and data dictionary is synchronized at technical product level. During API usage, it's important that all the JSON lists should match with the data dictionary object definition and the attached relationship should match with the product component hierarchy.
### Code Table and Data Table Configuration
Impact Area: Validation APIs and Load APIs
Code table configuration is beneficial not only in UI dropdown list generation, but also helps for the validation APIs to check whether code value matches business logics in the API payload and throw business exception if any of additional undefined value is passed in.
In addition, for all load APIs, the system supports showing the backend system data value and user-friendly UI display value to facilitate JSON creation process like printing and integration.
### Index Field Configuration
Impact Area: Search APIs
Quick and fuzzy search is supported in search engine. Our query API will come with a default set of search field conditions. When you want to add more search conditions even based on new dynamic fields, you are allowed to configure more index fields by our index definition and search out the policy based on various conditions after configuration. Please pay special attention that if an existing field is flagged for search, you need to manually trigger the index rebuilt in batch UI to rebuild all index data for past transactions.
### Numbering Configuration
Impact Area: Numbering Field in all API Payload
All business numbers in APIs, such as proposal and policy number, have a default system generation rule and the default rule is quite simple. If you want to set a more complex rule, you can alter via numbering template configuration.
### Rating Configuration
Impact Area: Rating APIs
Business calculation logic can be configured via rating configuration. It plays a role not only in annual risk premium calculation, but also in some common calculation such as commission, installment, policy period adjustment and endorsement calculation.
During the API calculation, the system will run according to the script-based rating logic definition and invoke certain rate table in the calculation process.
### Rule Configuration
Impact Area: Underwriting/Validation/Auto Attachment/Endorsement Content Generation/Form Content Generation APIs
Business rule logic can be configured via rule configuration. It functions not only in underwriting check, but also in other check process such as validation and attachment of some additional clauses or forms.
During the API rule check, the system will run according to the script-based rule logic definition and invokes certain rate table in the rule execution process.
### Message Configuration
Impact Area: Underwriting/Validation APIs
If any rule fails, it's important to display relevant messages in the response. All message bodies can be defined in message configuration in a multi-language way.
### Upload Configuration
Impact Area: Group Policy Upload APIs
There's a need to upload a list of risks and schedules for group policy handling. The list of field can be dynamically defined via uploading template configuration for import/export.
## Accelerator API
Although primary focus of our platform is to provide atomic API for front-end apps, there's a need for the front-end to orchestrate by combining multiple APIs together. We do find some of the combination which is frequently used and happening.
In order to accelerate development, as part of the platform settings, we provide a limited set of APIs which are not atomic but contain multiple behaviors. A typical example is "/proposal/core/proposal/v1/submitPolicy", which contains several atomic behaviors including auto attachment, validation, calculation and issuance.
These APIs are considered as **Accelerators**. Users must be careful to select such API when using.
## Platform API vs iComposer API
Since our policy atomic API focuses on atomic CRUD, there's always a need to introduce iComposer (Backend for Frontend) API if users want to really build a system application.
Based on our rich project experience, for each implementation, there might be more requirement items primarily around topics like:
1. Workflow - like all the proposal status change and approval flow
2. Integration – like integration with claim or bcp system
2. Batch jobs – like batch renewal or batch cancellation
3. Letter - like proposal form or policy document/email/sms
3. Report – like operational or reconciliation report
4. Authority - like poicy task or query authority
5. Upload - like policy upload via excel
All these requirements vary highly from client to client and region to region. It’s very hard to make a standard API set reusable for other client/market and we need iComposer layer to handle all such issues.
Such iComposer can be based on existing client tech-stack or InsureMO native appframework. If users want to learn more about how to develop iComposer leveraging our appframework, they can refer to our InsureMO appframework training serie.
## Q&A
#### If my client want to migrate some legacy policies into InsureMO, how can I do it?
Basically, there are several approaches you can import policies into InsureMO:
1. If the volume is small, the most economical way is to persuade client to manually input the policies to any of the apps and give some kind of legacy flags.
2. If the volume is medium, the most efficient way is to use GIMO issuance APIs to import these legacy policies.
3. If the volume is high, the most costly way is to construct a data migration team to do it.
For approach 1 and 2, project team can directly handle it with customer, while for approach 3, project team might need someone with data migration knowledge and approaches to do it.
#### If I have an excel with many policies to be issued, how to achive?
From InsureMO platform, we have a couple of basic components:
1. Individual policy issuance API – by proposal (standard volume) or by micro-insurance (huge volume)
2. [Upload template configuration framework](https://docs.insuremo.com/ics/app_framework/upload) – Allow to extract/save data from excel file and transform each line record into configurable json format
3. [Batch framework](https://docs.insuremo.com/ics/app_framework/batch-v2) – Allow to define batch process
For such requirement, we would suggest using iComposer to wrap leveraging above components to develop an API:
1. Take excel file as input.
2. Process all excel file data and save them.
3. Start a batch process.
4. Read sliced records from the file and transform into policy object.
5. Issue it concurrently via proposal or micro-insurance.
6. Finish batch and send notification.