Background

Understanding policy status change is the key to using any policy administration-related API.

From a business operation perspective, there can be different types of status change due to the different nature of business. For example, a quick online transaction might only experience a “quotation -> payment -> issuance” three-stage in which even quotation is just pure rating without persistence. While complex commercial insurance might go through more statuses such as “quotation -> proposal -> underwriting -> bind -> issuance”.

Due to such business flexibility, our platform API will only focus on key atomic behavior such as persistence or issuance while not paying too much attention to different status transitions.

Proposal Status

The key field to focus on before a policy is issued is “ProposalStatus”, whether a proposal or quotation API is being called.

The ProposalStatus must be a code table and you can find platform-recommended code values via the “Data Dictionary -> Data Table” menu as below:

Except for the “3 - Issued” status which you must call issuance API only, for the rest of the status change, you can choose to override the platform table and put any value in the “Policy Object - ProposalStatus field” via request body to achieve your status change when calling platform persistence API.

If no ProposalStatus value is detected in the request body, if it’s proposal API, the system will always default as “1 - Entry” while if it’s quotation API, the system will always default as “10 - Quotation in Progress”.

Endorsement Status

After the policy is issued, “ProposalStatus” will always be “Issued” and no longer be important.

If you want to change the policy information after issuance, there can be only three methods:

1. Call endorsement API to have a new policy version and change. For more details, see Endorsement JSON Creation Guide.
2. Call policy other APIs to put some of the fields as non version-related. For more details, see Policy Non Version Information/Other Info Guide.
3. Prepare data script to conduct data patch. This can always be a way but not recommended because backend data change might lead to any unforeseen situation to happen. See Policy Data Patch Guide first while you still need to seek the InsureMO support team to help before carrying out any patch process.

In terms of endorsement, the platform provides a comprehensive set of endorsement APIs and most of the URL paths are similar to proposal API with only a change of domain URL.

Similarly, the platform provides a default code table/data table called “EndorsementStatus” for our recommended code value. Except for endorsement issuance which has a specific API, you can override the table and pass whatever your recommended values in API - “Endorsement Object - EndoStatus field” via the request body to achieve your endorsement business flow.

If no EndoStatus value is detected in the request body and it is for the proposal API, the system will always default as “120 - Entry”.

For endorsement API, there are two basic restrictions:

1. There can be always one pending endorsement at one time. No multiple pending endorsements are allowed at any condition.
2. The effective date of the new endorsement must be always equal to or later than the previous endorsement. No out-of-sequence endorsement is allowed.

For out-of-sequence endorsement, it’s a complex topic. Although there’s no hard stop validation via platform API, we suggest you not carry out such practice as the first option. Now InsureMO platform team is investigating a new method to achieve out-of-sequence in an incoming version which will support basic OOS sequence without premium change involvement and will update the document in time.

Policy Status

Unlike proposal or endorsement status which only exists at one model and does not interact much with our API, PolicyStatus is a more important field that exists at all policy component levels with more complex system behaviors, especially during endorsement.

You can find our platform default value in the code table/data table menu with the table name “PolicyStatus”:

• During proposal transaction

Normally you do not need to pass anything. At the policy level, the system will always return values for “1 - Not Effective” and “2 - Effective” at the rest of the policy component levels.

• Upon policy issuance

After calling the policy issuance API, the system will then set the value for all levels to “2 - Effective” and keep them.

• During endorsement transaction

At the policy level, the value will always be “2 - Effective”.

However, for each policy component level, you must pay special attention to whether any components need to be removed due to business transactions. If any of the components such as a risk is removed from the policy, you must always set the value to be “4 - to be removed” via the request body.

• After endorsement issuance

At the policy level, the value will still be “2 - Effective” if the endorsement is not cancellation and it will be “3 - Cancelled” if the endorsement type is cancellation.

At each policy component level, if there’s any component flagged as “4 - to be removed”, it will be automatically updated to “3 - Cancelled” after endorsement is effective.

Interaction With Workflow API

Also, you must bear in mind that policy API will only work with status changes related to the policy object body only. However, in real business, there might be another concept called “Workflow Status” which is more focused on system flow and different user-assigned tasks.

For such task-related change, see Workflow Engine first to understand how to define flows and call workflow API.

From a platform perspective, policy API and workflow API are different separate domain APIs and different offerings. If you want to deliver a workflow feature to the end business user, you must wrap your own iComposer API to combine both policy & workflow API.

Take-Up Policy Handling

The existing GIMO platform functions can support the requirements for a “Take Up Policy.” The specifics are as follows:

1. GIMO supports two methods for policy entry:

• migrate: Supports migrating policies and endorsements. In Migrate, the transaction is issued directly without involving any intermediate states.
• normal: A standard proposal save, which can be saved multiple times, triggering logic like rules and calculations, and then issued.

2. For this Take-Up Policy, the “normal” method can be used, i.e., calling the proposal save API to enter it and perform subsequent operations.

• On the Policy object, there is an IsTakeUpPolicy field to identify if it is a “Take Up” Policy, and a DcPolicyNo field to identify the original PolicyNo from the external system. Of course, if needed, you can additionally configure Policy Level fields in the Policy Common DD, such as SchemaID.

3. The atomic APIs of the GIMO platform have no special handling logic for Take Up Policies; all operations are the same as for normal policies.

4. In the renewal batch job, the normal Policy query API can be called to query Take Up Policies for subsequent operations like creating Renewal Proposals.

5. Logic specific to Take Up Policies can be implemented at the Business API level. If Policy.IsTakeUpPolicy=Y, then:

• When saving a proposal, query in advance based on DcPolicyNo to check if an identical Take Up Policy already exists. If it does, it indicates a duplicate.
• Do not transmit billing/collection/payment data.
• Do not allow the creation of Endorsements.
• Do not generate eDocs.
• Do not generate Invoices or Debts.
• Do not send information to the Customer.

7. Logic specific to Take Up Policies can also be controlled at the Rating configuration level. If Policy.IsTakeUpPolicy=Y, then:

• The Premium should be returned directly from the value entered on the policy.
• Do not perform Tax/Fee calculations.
• Do not perform Commission calculations.

8. Each time a Proposal is saved, a new RevisionId is generated in the GIMO Policy to identify the version of the Proposal, thus meeting the Audit Trail requirements:

• /pa/core/policy/v1/getPolicyRevisions?policyId=xxx to get all revisions.

• /pa/core/policy/v1/loadPolicyAtRevision?policyId=xxx&revisionId=yyy to get the Policy data for a specific revision.

• By using a Json Diff, you can compare the differences between revisions to achieve the purpose of an Audit Trail.

FAQ

1. Policy Status Still Shows “Effective” After Expiry？

Question: Why does the policy still appear as “Effective” once it falls outside the policy period, and the renewal API call does not throw the expected error when the policy is expired?

Answer: To ensure absolute stability of policy data after issuance, the original policy cannot be directly modified once issued. If changes are necessary, they should be processed by creating an endorsement. Regarding whether a policy has expired, it can be determined based on the Expiry Date in the UI. We recommend that tenants implement relevant logic in the tenant UI to display expired policies as “Expired”. In addition, whether renewal is allowed after a policy expires may vary among tenants (e.g., some tenants allow renewal within a grace period). Therefore, entrusting these two aspects of logic to tenants avoids modifications to policy core data in the database and allows flexibility for tenants to adjust according to their business rules (such as grace periods, renewal conditions, etc.).