Concept
Policy renewal is the process of extending an insurance policy beyond its original term. Typically occurring annually, it offers an opportunity for both the insurer and the policyholder to reevaluate the agreement. The insurance company will issue a renewal notice that outlines any changes to the premium or terms and conditions. The policyholder may then decide whether to accept the new terms and continue coverage, seek a new policy, or decline renewal.
API Introduction
InsureMO treats all renewal transactions equally as new business proposals. Therefore, all proposal transactional APIs are applicable for both cases.
The policy renewal API handles the pre-transaction processes:
- Query Policies Due for Renewal
- Create renewal proposal
Query Policies for Renewal
Query Policies for Renewal - Business Usage
- To provide a high-performance, flexible query interface for batch renewal programs to retrieve policies due for renewal.
- To replace the previous database-based query, overcome its limitations in queryable fields and performance issues, and leverage Elasticsearch (ES) to enable queries across all indexed policy fields.
Query Policies for Renewal - API Path
{{server}}/platform/pa/core/policy/batch/data/query/v1/queryPolicyForRenewal?prePolicyId={{prePolicyId}}&fromExpiryDate={{fromExpiryDate}}&toExpiryDate={{toExpiryDate}}
Query Policies for Renewal - API Detail
This API queries the policy index in Elasticsearch to retrieve policies eligible for renewal. The core logic is as follows:
-
Policy Is Renewable Check: API will not return any record if policy level field Is Renewable is flagged as “N”.
-
ES-Based Query: The query is performed on the ES policy index, allowing for flexible search conditions on any indexed field. A mandatory condition is the policy
expiryDaterange. -
Pagination:
- Results are paginated to handle large datasets, returning a maximum of 1000 records per call.
- The result set is sorted by
policyId. - For subsequent pages, the caller must pass the
policyIdof the last record from the previous response in theprePolicyIdquery parameter (the new search will start after this ID).
-
Continuation Flag:
- It’s possible that all policies returned by an ES query have already been renewed. In this case, the API will return an empty list (record count is 0).
- However, the response will include a special flag (
hasMoreRecords) to indicate whether there are more potential records in ES to be queried. - The batch program must check this flag to decide whether to continue requesting the next page.
-
Performance Consideration: To prevent timeouts, the API will not perform multiple ES queries within a single call. The client (batch program) is responsible for iterating through the pages.
-
Reduced Payload: The request body can specify
IncludeFieldsto limit the number of fields returned for each policy, reducing network payload and improving performance.
-
Sample Request
```json{"Conditions": {"ProductCode": "TBTI"},"IncludeFields": ["PolicyId","PolicyNo","ExpiryDate","ProductCode"]}```
Renewal Proposal Creation
Renewal Proposal Creation - Business Usage
- A customer wants to start a renewal before the batch generation day.
- A customer requests the renewal of a policy which failed the batch renewal validation rule within the grace period.
Renewal Proposal Creation - API Path
- {{server}}/proposal/renewal/v1/manualRenew/byPolicyNo?policyNo={{PolicyNo}}
Renewal Proposal Creation - API Detail
After API is called, the system will create a new renewal proposal based on the following logic:
- Create a new policy by duplicating the old one
- Process Policy Status
- Build proposal number
The system will abort the process under the following conditions:
- The policy Number does not exist
- The policy has already expired
- The policy is non-renewable
- The policy renewal proposal is already created
- Sample Response
{
"AdjustedPremium": 37.69,
"AnnualPremium": 910,
"AutoUwResultCode": "2",
"BeforeVatPremium": 34.9,
"BookCurrencyCode": "SGD",
"BusinessCateCode": "1",
"BusinessObjectId": 3517051304219,
"Commission": 3.49,
"CommissionRate": 0.1,
"DuePremium": 37.69,
"EffectiveDate": "2024-05-15",
"ExpiryDate": "2025-05-14",
"FirstDataEntryDate": "2024-05-07T15:05:02",
"GrossPremium": 37.69,
"InterestRate": 0,
"IsPremiumCalcSuccess": "Y",
"IsRenewable": "Y",
"IsRenewalPolicy": "Y",
"IsTakeUpPolicy": "N",
"IssueUserId": XXXXX0006XXXXX,
"IssueUserRealName": "xxxxxx.xxxx@insuremo.com",
"LastPolicyId": "10429830004,0C0949D97CD1974730D905A32D6E96B6",
"LocalCurrencyCode": "SGD",
"MaxUwLevelCode": "1",
"OrgCode": "10001",
"POIRate": 1,
"PolicyElementId": 10429850004,
"PolicyId": "10429850004,4940D49392DE30290912FCA9E6CDE99B",
"PolicyLobList": [
{
"AdjustedPremium": 37.69,
"BeforeVatPremium": 34.9,
"BusinessObjectId": 351861068,
"DuePremium": 37.69,
"GrossPremium": 37.69,
"PolicyElementId": 10429850006,
"PolicyId": "10429850004,4940D49392DE30290912FCA9E6CDE99B",
"PolicyRiskList": [
{
"AdjustedPremium": 37.69,
"Age": 35,
"BeforeVatPremium": 34.9,
"BusinessObjectId": 351861075,
"DateOfBirth": "1988-10-01",
"DuePremium": 37.69,
"GrossPremium": 37.69,
"IdNo": "888666888",
"IdType": "1",
"PolicyCoverageList": [
{
"AdjustedPremium": 37.28,
"AnnualPremium": 900,
"BeforeVatPremium": 34.52,
"BusinessObjectId": 351861078,
"CoverageName": "Accident Death & Dismemberment",
"DuePremium": 37.28,
"GrossPremium": 37.28,
"PolicyElementId": 10429850008,
"PolicyId": "10429850004,4940D49392DE30290912FCA9E6CDE99B",
"PolicyStatus": 2,
"ProductElementCode": "C100416",
"ProductElementId": 351926024,
"SequenceNumber": 1,
"SumInsured": 300000,
"Vat": 2.76
},
.....skip....
],
"PolicyElementId": 10429850007,
"PolicyId": "10429850004,4940D49392DE30290912FCA9E6CDE99B",
"PolicyStatus": 2,
"ProductElementCode": "R10007",
"ProductElementId": 351926021,
"RiskName": "Alice",
"SequenceNumber": 1,
"SumInsured": 750000,
"TempData": {
"Mask-IdNo": "4LGgRe2xYylgnm7I6r7O2w==",
"IdNo": "4LGgRe2xYylgnm7I6r7O2w==",
"MaskAfter-IdNo": "888666888"
},
"Vat": 2.79
}
],
"PolicyStatus": 2,
"ProductCode": "TBTI",
"ProductElementCode": "TBTI",
"ProductElementId": 351925023,
"ProductId": 351925022,
"ProductLobId": 351925023,
"SequenceNumber": 1,
"SumInsured": 750000,
"TechProductCode": "TR_POC",
"TechProductId": 3516410623456,
"Vat": 2.79
}
],
"PolicyStatus": 1,
"PolicyType": "1",
"PremCalcFactorHash": "20240507_150508_769,R2LgLtTE1nGY5rcgx3ulnI9PZqH+QB17K5I+iCoK2HY=",
"PremCalcResultHash": "20240507_150508_775,sFs/QKJMx4hNS/3VIccX0BPFENiUYeopHyGdud3ehk0=",
"PremiumBookExchangeRate": 1,
"PremiumCurrencyCode": "SGD",
"PremiumInterest": 0,
"PremiumLocalExchangeRate": 1,
"ProductCode": "TBTI",
"ProductId": 351925022,
"ProductVersion": "1.0",
"ProposalDate": "2024-05-07",
"ProposalNo": "PABTBTI0001316875",
"ProposalStatus": "1",
"SchemaVersion": 2,
"SumInsured": 750000,
"TaxInterest": 0,
"TechProductCode": "TR_POC",
"TechProductId": 3516410623456,
"TotalInterest": 0,
"TotalPremium": 37.69,
"Vat": 2.79,
"VatRate": 0.08,
"VersionSeq": 1
}Renewal Policy Data Copy
Renewal Policy Data Copy – Business Usage
- A client wants to preview or manually adjust renewal data before the official renewal proposal is created.
- A client needs to duplicate the current policy information, tweak certain fields, and then perform its own downstream operations (quote, validation, etc.).
Note: This API does not apply to group-policy renewals.
Renewal Policy Data Copy – API Path
- {{server}}/pa/core/renewal/v1/copyPolicyDataForRenewal?policyId={{PolicyId}}
Renewal Policy Data Copy – API Detail
Calling this API will:
- Fetch the policy identified by
policyId. - Duplicate the policy data into an in-memory object.
- Apply the minimal field adjustments required for renewal (example: reset policy status to “Entry”, clear previous proposal numbers, etc.).
- Return the transformed JSON payload to the caller.
Nothing is persisted—the client receives a ready-to-use renewal dataset and may proceed with its own custom logic (further editing, validation, pricing, or eventual proposal creation through other endpoints).
Sample Response – Success (200 OK)
{
"@type": "Policy-POLICY",
"AdjustedPremium": 0,
"AgentCode": "XXXXX0000000XXXXX",
"AutoUwResultCode": "1",
"BeforeVatPremium": 0,
"BookCurrencyCode": "CNY",
"BusinessCateCode": "1",
"BusinessObjectId": 3517051304219,
"Commission": 0,
"DuePremium": 0,
"EffectiveDate": "2025-12-05",
"ExpiryDate": "2026-12-04",
"FirstDataEntryDate": "2025-12-04T15:42:15",
"GrossPremium": 0,
"IsPremiumCalcSuccess": "Y",
"IsRenewable": "",
"IsRenewalPolicy": "Y",
"IsTakeUpPolicy": "N",
"IssueUserId": XXXXX0809XXXXX,
"IssueUserRealName": "xxxxxxxx",
"LastPolicyId": "11658780137,41CF2BE927AF4BB0500111EDEFCB0E9B",
"LocalCurrencyCode": "CNY",
"MaxUwLevelCode": "0",
"OrgCode": "10002",
"PolicyStatus": 1,
"PolicyStatusForDisplay": 1,
"PolicyType": "1",
"PremCalcFactorHash": "{V3,11658780139}0VrRaE1km1qWm9zDzj46IbHRzDbydqRNs6S8oKiwKkE=",
"PremCalcResultHash": "{V3,11658780139}PVThA6O/yjkSfEMofWkRwSFFWcAfQ5XcxoQ/+RK+wl4=",
"PremiumBookExchangeRate": 1,
"PremiumCurrencyCode": "CNY",
"PremiumLocalExchangeRate": 1,
"ProductCode": "TBTI",
"ProductId": 351925022,
"ProductVersion": "1.0",
"ProposalDate": "2024-07-22",
"ProposalStatus": "3",
"QuotationDate": "2025-12-04T15:42:15",
"SchemaVersion": 2,
"SumInsured": 900000,
"TechProductCode": "TR_POC",
"TechProductId": 3516410623456,
"TerminateCode": "2",
"TerminateDate": "2025-12-04T15:42:26",
"Vat": 0,
"VersionSeq": 2,
"AnnualPremium": 930,
"CommissionDelta": -10.7,
"CommissionRate": 0.3,
"InterestRate": 0,
"POIRate": 1,
"PolicyCommissionRateList": [
{
"@type": "PolicyCommissionRate-PolicyCommissionRate",
"BusinessObjectId": 316589,
"DefaultRate": 0.3,
"ParentElementType": "POLICY",
"PolicyStatus": 2,
"SequenceNumber": 1
}
],
"PolicyCustomerList": [
{
"@type": "PolicyCustomer-PolicyCustomer",
"BusinessObjectId": 1000000290,
"CustomerName": "Customer",
"DateOfBirth": "1988-10-01",
"IdNo": "IdNo",
"IdType": "1",
"IsInsured": "N",
"IsOrgParty": "N",
"IsPolicyHolder": "Y",
"ParentElementType": "POLICY",
"PolicyStatus": 2,
"SequenceNumber": 1,
"TempData": {
"Mask-IdNo": "Jmf1vghdrScrTdpdeyKu7w==",
"MaskAfter-IdNo": "IdNo"
}
}
],
"PolicyDeliveryAddressList": [
{
"@type": "PolicyDeliveryAddress-PolicyDeliveryAddress",
"Address": "Address1",
"BusinessObjectId": -1100000235,
"ParentElementType": "POLICY",
"PolicyStatus": 2,
"PostCode": "210012",
"Recipient": "Recipient1",
"SequenceNumber": 1
}
],
"PolicyLobList": [
{
"@type": "PolicyLob-TR_POC",
"AdjustedPremium": 0,
"BeforeVatPremium": 0,
"BusinessObjectId": 351861068,
"Commission": 0,
"DuePremium": 0,
"ExpiryDate": "2025-12-04",
"GrossPremium": 0,
"ParentElementType": "POLICY",
"PolicyStatus": 3,
"ProductCode": "TBTI",
"ProductElementCode": "TBTI",
"ProductElementId": 351925023,
"ProductId": 351925022,
"ProductLobId": 351925023,
"SequenceNumber": 1,
"SumInsured": 900000,
"TechProductCode": "TR_POC",
"TechProductId": 3516410623456,
"TerminateDate": "2025-12-04T15:42:26",
"Vat": 0,
"CommissionDelta": 0,
"PolicyRiskList": [
{
"@type": "PolicyRisk-R10007",
"AdjustedPremium": 0,
"BeforeVatPremium": 0,
"BusinessObjectId": 351861075,
"Commission": 0,
"DuePremium": 0,
"ExpiryDate": "2025-12-04",
"GrossPremium": 0,
"ParentElementType": "POLICY_LOB",
"PolicyStatus": 3,
"ProductElementCode": "R10007",
"ProductElementId": 351926021,
"RiskName": "InsuredName",
"SequenceNumber": 1,
"SumInsured": 900000,
"TerminateDate": "2025-12-04T15:42:26",
"Vat": 0,
"Age": 37,
"CommissionDelta": 0,
"CustomerName": "Customer",
"DateOfBirth": "1988-10-01",
"IdNo": "IdNo",
"IdType": "1",
"PolicyCoverageList": [
{
"@type": "PolicyCoverage-PolicyCoverage",
"AdjustedPremium": 0,
"AnnualPremium": 900,
"BeforeVatPremium": 0,
"BusinessObjectId": 351861078,
"Commission": 0,
"DuePremium": 0,
"ExpiryDate": "2025-12-04",
"GrossPremium": 0,
"IsFinalLevelCt": "Y",
"ParentElementType": "INSURED",
"PolicyStatus": 3,
"ProductElementCode": "C100416",
"ProductElementId": 351926024,
"SequenceNumber": 1,
"SumInsured": 300000,
"TerminateDate": "2025-12-04T15:42:26",
"Vat": 0,
"CommissionDelta": 0,
"CoverageName": "Accident Death & Dismemberment"
},
{
"@type": "PolicyCoverage-PolicyCoverage",
"AdjustedPremium": 0,
"AnnualPremium": 10,
"BeforeVatPremium": 0,
"BusinessObjectId": 351861078,
"Commission": 0,
"DuePremium": 0,
"ExpiryDate": "2025-12-04",
"GrossPremium": 0,
"IsFinalLevelCt": "Y",
"ParentElementType": "INSURED",
"PolicyStatus": 3,
"ProductElementCode": "C100692",
"ProductElementId": 351926030,
"SequenceNumber": 2,
"SumInsured": 300000,
"TerminateDate": "2025-12-04T15:42:26",
"Vat": 0,
"CommissionDelta": 0,
"CoverageName": "Baggage Loss or Damage"
},
{
"@type": "PolicyCoverage-PolicyCoverage",
"AdjustedPremium": 0,
"AnnualPremium": 20,
"BeforeVatPremium": 0,
"BusinessObjectId": 351861078,
"Commission": 0,
"DuePremium": 0,
"ExpiryDate": "2025-12-04",
"GrossPremium": 0,
"IsFinalLevelCt": "Y",
"ParentElementType": "INSURED",
"PolicyStatus": 3,
"ProductElementCode": "C100715",
"ProductElementId": 351926027,
"SequenceNumber": 3,
"SumInsured": 300000,
"TerminateDate": "2025-12-04T15:42:26",
"Vat": 0,
"CommissionDelta": 0,
"CoverageName": "Travel Delay"
}
],
"TempData": {
"Mask-IdNo": "Jmf1vghdrScrTdpdeyKu7w==",
"MaskAfter-IdNo": "IdNo"
}
}
],
"TotalInsuredCount": 1
}
],
"PolicyPaymentInfoList": [
{
"@type": "PolicyPaymentInfo-PolicyPaymentInfo",
"BusinessObjectId": 520259,
"InstallmentPeriodCount": 1,
"InstallmentType": "1",
"IsInstallment": "Y",
"ParentElementType": "POLICY",
"PayModeCode": "30",
"PayRate": 1,
"PolicyStatus": 2,
"SequenceNumber": 1,
"InstallmentList": [
{
"@type": "Installment-Installment",
"BeforeVatPremium": 35.67,
"BeforeVatPremiumLocal": 35.67,
"BusinessObjectId": 200001394,
"Commission": 10.7,
"CommissionLocal": 10.7,
"FeeSeq": 1,
"InstallmentAmount": 38.52,
"InstallmentAmountLocal": 38.52,
"InstallmentDate": "2025-11-27",
"InstallmentPeriodSeq": 1,
"ParentElementType": "POLICY_PAYMENT",
"PolicyStatus": 2,
"SequenceNumber": 1,
"Vat": 2.85,
"VatLocal": 2.85,
"DuePremium": 38.52,
"DuePremiumLocal": 38.52,
"PremiumInterest": 0,
"PremiumInterestLocal": 0,
"TaxInterest": 0,
"TaxInterestLocal": 0,
"TotalInterest": 0,
"TotalInterestLocal": 0
}
]
}
],
"PremiumInterest": 0,
"TaxInterest": 0,
"TotalInterest": 0,
"TotalPremium": 38.52,
"VatRate": 0.08
}Testing Multiple Future Renewals
InsureMO GI does not provide an out-of-the-box function to automatically simulate multiple future renewal cycles (e.g., 5 cycles) in one shot. However, you can achieve this using the following approaches:
Method 1: Historical Policy Approach (Simple)
The simplest way to test multiple renewal cycles:
- Issue a policy with an effective date 5 years ago (or as far back as needed)
- Run the renewal batch repeatedly, each time advancing the policy through one renewal cycle
- Continue until you have simulated the desired number of renewal cycles
Advantages:
- No configuration changes required
- Works with existing batch jobs and APIs
- Easy to understand and execute
Considerations:
- Requires historical product configurations to be valid for old dates
- May need to handle date-specific rules or rates
Method 2: Time Offset Approach (Advanced)
Use the platform’s global time offset mechanism to simulate future dates without modifying actual policy data. This mechanism works across the entire platform, including Batch processing, API calls, and business logic.
Configuration
-
Enable time offset for the tenant:
In
SystemConfigTable, set:Key: tenant.batch.offsetdays.enableValue: true -
Configure organization offset:
In
OrgOffsetDaystable:Key: <OrgCode> (e.g., 10001)Value: <offset_in_days> (e.g., 3650 for ~10 years)- Positive value: simulate future dates
- Negative value: simulate past dates
- Maximum: ±100 years
Usage Scenarios
For Batch Processing:
- Scheduled batches will use the offset date as “today”
#FirstDueTimeand#LastDueTimeparameters are automatically adjusted- Run renewal batch as usual; it will process policies as if it were the future date
For API Calls:
- All APIs that rely on system time will reflect the offset
- Useful for testing time-sensitive business logic (e.g., effective date validation, age calculation)
For Business Rules:
- Rating and validation rules that use current date will use the offset date
- Enables full end-to-end testing of future scenarios
Clean Up After Testing
-
Disable time offset:
Set tenant.batch.offsetdays.enable = false -
Clear batch execution records (optional, in pub database):
delete from t_pub_batch_def_ext;delete from t_pub_batch_exec_his;delete from t_pub_batch_exec;
caution
Time offset testing can cause confusion with normal business data in test environments. Always clean up after testing.
Reference
- Global Parameter Configuration
- Batch-V2 Framework - Time Offset