Managing policies
Overview
Once a policy has been issued, its lifecycle is governed by standard Root platform rules, as well as custom rules configured for your product module. Root enables flexible policy management to make changes to policies, both via the API and on the Root management dashboard.
This guide explains the different statuses a policy can have on Root, and how it progresses through the policy lifecycle. It also summarises the available Root features for managing policies, from cancelling or reactivating policies to making policy amendments.
Billing and payments are discussed separately in the billing & payments guide.
Policy lifecycle
The product specific rules for policy activation, lapse and other status changes are configured in the general product module settings. When a policy is issued, it can have a status of active or pending_initial_payment, depending on whether you have configured your product module to activate policies on issue.
From pending_initial_payment, a policy's status will change to active when the selected policy activation event is triggered. This could be when the payment method is assigned, when the first successful payment is received, or based on a custom rule configured in the product module code.
If the "not taken up" setting is enabled for your product, and the first premium collection attempt fails, the policy status will change to not_taken_up (an inactive status).
Once an active policy has reached its start date, cover becomes active and regular collection attempts will run against the policy. (Note that collections can also be attempted against a policy with a status of pending_initial_payment, if the activation event is the first successful payment).
Active policies can become inactive by lapsing, being cancelled or expiring. Inactive policies can be reactivated again if this feature has been enabled for your product module.
| Policy status | Description |
|---|---|
pending_initial_payment | If a policy is not active on issue, it is issued with a status of pending_initial_payment.The policy will become active depending on the activation rules defined in the product module settings. From this status, a policy's status typically changes to not_taken_up or active. |
not_taken_up | This status is only relevant if the "not taken up" rule is enabled in the product module settings. Policies that are active or pending_initial_payment can be marked as not_taken_up.If this setting is enabled, and the policy's first payment fails, it will be marked as not_taken_up, and no further collections will be attempted against the policy. |
active | Policies can become active from any other status, either through the initial activation event, or by being reactivated. If a policy is active and it has reached its start date, cover is active and regular collection attempts will run against the policy. The status of an active policy can change to not_taken_up, lapsed, cancelled or expired. |
lapsed | An active policy will lapse if any of the lapse rules, as configured in the product module settings, are triggered. These lapse rules are also referred to as the "grace period". Once a policy lapses, cover stops and no further collections will be attempted against the policy. The status of a lapsed policy can change to active if it is reactivated. |
cancelled | An active policy can be cancelled by the policyholder or the insurer. If the policy is still within the cooling-off period, as defined in the product module settings, the policyholder will be refunded any premiums that have already been collected. The status of a cancelled policy can change to active if it is reactivated. |
expired | Once an active policy reaches its end date, as configured in the policy issue hook, its status will be changed to expired by the platform.Policies can be issued with an end date of null, in which case the policy will not expire.The status of an expired policy can change to active if it is reactivated (although this will require that the end date on the policy also be changed). |
Cancelling policies
A policyholder is entitled to cancel their policy at any time and request a refund. Policy cancellations can also be initiated by the insurer under certain conditions. When cancelling a policy, the reason for the cancellation is captured.
If the cancellation occurs within the cooling-off period, as defined in the product module settings, the policyholder will be eligible for a refund of premiums that have already been collected.
Policy cancellation is a standard feature across all product modules and no configuration is required (except for the duration of the cooling-off period).
Policies are cancelled via the cancel a policy endpoint. Agents can also cancel policies on the Root management dashboard.
Cancelling a policy also cancels pending payments
When a policy is cancelled, all premium payments with a status of
pendingwill automatically be cancelled. This is to ensure that policyholders are not billed after cover has ceased.
Reactivating policies
All inactive policies (except those with a status of pending_initial_payment) can be reactivated. You need to enable reactivation in the product module settings, and configure the reactivation hook for your product module.
Policies are reactivated via the reactivate policy endpoint, which requires you to provide a reactivation option, as defined in the reactivation hook. You can also reactivate a policy by selecting one of the reactivation options you have configured on the Root management dashboard.
Policy alterations
Alteration hooks are used to apply ad hoc or customer initiated amendments to policies. They allow for flexible updates of policy data through a simple interface with minimal required fields.
For example, should a customer want to correct the name of one of the lives covered under a funeral policy, this can be enabled by defining an alteration hook to capture the new information, and apply it to the existing policy. You could also configure an expanded alteration hook to allow for a full policy requote or endorsement, recapturing all rating factors and other required information, and recalculating the premium and other variable amounts.
To amend a policy, you need to first create an alteration package, and then apply the alteration package to the policy. This allows the customer to review all relevant details, including the new premium, before the amendment is applied. This workflow can also be completed on the Root management dashboard, provided you have defined an alteration schema for each hook.
To enable alterations for your product module, you need to configure one or more alteration hooks.
Automated policy updates and actions
Root allows you to register automated actions to run against existing policies. These actions can be triggered either by a predefined event in the lifecycle of the policy (lifecycle hooks), or on a time-based schedule (scheduled functions).
These actions can be used to update policy data, change policy status, and credit or debit the policy balance on the ledger, among others. A reference for all supported actions is provided in the actions guide.
Lifecycle hooks
Lifecycle hooks are predefined events that can occur during the lifecycle of a policy. When an event is triggered, you can specify certain actions to be performed automatically in relation to the policy. Examples of lifecycle events include afterPaymentSuccess, beforePolicyReactivated, and afterClaimApproved, among others.
These are useful for things like dynamic cover changes or complex lapse rules. For example, you can use the afterPaymentSuccess hook to define custom activation logic for policies, or the afterClaimApproved hook to change the benefits available on a policy. You can also use these hooks to validate and restrict the completion of certain actions, such as reactivation.
For more details, see the guide on lifecycle hooks.
Scheduled functions
As the name implies, scheduled functions run at regular, specified intervals. These functions perform recurring actions against existing policies, as defined in the product module code. For example, you could configure a scheduled function to calculate and apply premium increases on the policy anniversary.
For more details, see the guide on scheduled functions.
Updated 3 months ago