Overview

Root allows you to configure basic product setup and some product features as simple settings. These settings relate to features that are generally relevant to all types of insurance products, and are simple enough that they don't need to be configured using code.

More complex product features are configured in the product module code. The product module code also allows you to expand or override logic that would otherwise be governed by settings, where required. For example, you can use lifecycle hooks to configure custom lapse rules for your product if the available settings do not meet your requirements.

There are two types of settings:

• General settings - These settings relate to basic product setup and general features. These are the settings covered in this guide.
• Billing settings - These settings relate to how billing will work for your product. These are the settings covered in a separate guide.

The general settings are organised into four themes:

• Hooks and features - These settings specify the product scheme type (group or individual), and whether specific features and hooks are enabled for your product.
• Policyholders and beneficiaries - This group of settings relates to policyholders and beneficiaries.
• Policy documents - These settings allow you to specify whether a welcome letter, policy anniversary letter and/or certificate are enabled for your product module. You can also specify a custom filename for each document.
• Policy status and lifecycle rules - This group of settings relates to how the status of policies changes (e.g. activated or lapsed) and how certain policy milestones are handled (waiting period and cooling-off period).

The settings covered in this guide relate to product-level settings that are configured using the Root workbench. This excludes organisation-level settings, such as customer notifications settings, configured on the Root management dashboard.

Hooks and features

These settings specify the product scheme type (group or individual), and whether specific features and hooks are enabled for your product.

{
  "settings": {
    "policySchemeType": "individual",
    "dashboardIssuingEnabled": true,
    "canReactivatePolicies": true,
    "canRequote": false,
    ...
  }
}

Policy scheme type

This setting specifies whether this is an individual or group insurance product. In the case of individual insurance, each customer contracts separately with the insurer and receives his or her own policy schedule. In the case of group insurance, the insurer has a single insurance contract with a company or legal entity, and multiple members are added to the same insurance policy (for example, travel insurance for a company's employees).

A number of important Root features function differently for group and individual products.

Dashboard issuing enabled

If you enable this setting, dashboard users will be able to capture the required quote, policyholder and application input parameters via the Root management dashboard, and issue policies. You will need to define the quote and application schemas used to capture this information.

If this setting is disabled, you will only be able to use the corresponding API endpoints for creating quotes, policyholders, applications and issuing policies. The input parameters will need to be captured via an external front-end, or sent from your system.

Reactivation enabled

Enabling this setting allows inactive policies (for example, policies with status lapsed or cancelled) to be reactivated, which changes the policy status to active.

If you enable this setting, you will need to define the reactivation options for the product as part of configuring the reactivation hook.

Policy Number Schema

⚠️

Warning

The schema configuration can limit the total number of unique policy numbers. Once the pool of possible policy numbers is exhausted, new policies cannot be created until the schema is updated.

This setting enables the customization of policy number formats.

If set to null, policy numbers will default to using the character set ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890 with a length of 10.

{
  "settings": {
    "policyNumberSchema": {
      "characterSet": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
      "length": "10",
      "prefix": "",
      "suffix": ""
    },
   	...
  }
}

Requote enabled (deprecated)

This setting enables the requote hook for your product. Note: This feature has been deprecated in favour of alteration hooks, and is only listed here for old product modules that were built with the requote feature.

Policyholders and beneficiaries

This group of settings relates to policyholders and beneficiaries.

Policyholders

These settings specify which types of policyholders are allowed to take out policies under this product module.

{
  "settings": {
    "policyholder": {
      "companiesAllowed": false,
      "individualsAllowed": true,
      "individualsIdAllowed": true,
      "individualsPassportAllowed": true,
      "individualsCellphoneAllowed": true,
      "individualsEmailAllowed": true,
      "individualsCustomIdAllowed": true,
      "customIdName": "UK Driving License",
      "idCountry":"GB",
      "individualPolicyholderFields": {
        "address": {
          "suburb": {
            "required": true
          }
        },
        "dateOfBirth": {
          "required": true
        },
          "gender": {
            "hidden": true
          }
        }
      }
    },
   	...
  }
}

Properties

📘

Beneficiary context

All of the identifiers enabled above will be available as unique identifiers for Beneficiaries except for Cellphone and Email. Beneficiaries have Cellphone and Email available as contact information fields.

Beneficiaries

These settings specify:

• whether beneficiaries can be added to a policy,
• whether the policyholder is automatically added as a beneficiary, and
• how many beneficiaries can be added to a policy.

{
  "settings": {
    "beneficiaries": {
      "makePolicyholderABeneficiary": true,
      "min": 1,
      "max": 2
    },
   	...
  }
}

Properties

Policy documents

These settings allow you to specify whether optional policy documents are enabled for your product module. If enabled, you will need to build an HTML template for the relevant document.

You can also specify a custom filename for each policy document.

Read more about what these documents are used for and how to build dynamic HMTL templates in the policy documents guide.

{
  "settings": {
    "welcomeLetterEnabled": true,
    "policyAnniversaryNotification": {
    	"daysBeforeToSend": 30
    },
    "policyDocuments": [
      {
        "type": "terms",
        "fileName": "{{ policyholder.first_name }}_terms"
      },
      {
        "type": "certificate",
        "fileName": "{{ policyholder.first_name }}_certificate",
        "enabled": true
      },
      {
      	"type": "supplementary_terms",
        "supplementaryTermsType": "additional-terms-and-conditions",
        "fileName": "{{ policyholder.first_name }}_additional_terms_and_conditions"
      }
    ],
  	...
  }
}

Welcome letter enabled

Policy anniversary notification

Properties

Policy documents

Properties

Policy status and lifecycle rules

This group of settings relate to:

• events that affect the policy status (such as when a policy becomes active and when it lapses),
• when the policy cover starts (such as whether a waiting period applies), and
• the period of time during which a customer can cancel a policy and receive a refund (cooling off period).

Policy active on event

When a policy is activated, cover starts (assuming there is no waiting period) and billing will run against the policy. On Root, a policy does not have to be active when it is issued, and it can be activated at a later date. A policy that has been issued but is not yet activated will have a default status of pending_initial_payment.

This setting allows you to configure which event will trigger policy activation. You can choose one of the following options:

• Policy issued: The policy will be issued with a status of active, even if no payment method has been assigned.
• Payment method assigned: The policy will be activated when a payment method has been assigned.
• First successful payment: The policy will be activated upon the first successful payment.
• None: Platform will not automatically activate policies. You will need to configure custom logic for activating policies using lifecycle hooks, or activate policies from an external system via the reactivate policy endpoint.

{
  "settings": {
    "activatePoliciesOnEvent": "payment_method_assigned",
     ...  
   }     
}

Grace period and lapse rules

The grace period determines under which circumstances missed (failed) payment(s) will cause the policy to lapse. The end of the grace period is the date the policy will lapse. This is specified by means of lapse rules.

📘

Retry payments count towards failed payments

If the retry failed payments setting is enabled, the Root platform will automatically resubmit failed payments for collection. If such an automatic retry attempt fails, it will count towards the total failed (missed) payments on the policy.

For example, assume you have consecutiveMissedPayments set to 3, and failed payments are retried twice. This would mean that a policy could lapse within a single monthly billing cycle if both the initial collection attempt and the two retry attempts fail.

The consecutiveFailedPaymentsAllowed rule must also be taken into account when reviewing the above logic.

Root supports four different lapse rules. To disable a lapse rule, set its value to null. Lapse rules are optional and all four options can be null. You can also configure custom lapse logic using lifecycle hooks.

🚧

Multiple lapse rules

To reduce complexity and allow for predictable billing behaviour, we recommended that you avoid enabling multiple lapse rules for a product module.

If multiple lapse rules have been enabled, the policy will lapse as soon as any one of the lapse rules applies.

{
  "settings": {
    "gracePeriod": {
      "lapseOn": {
        "afterFirstMissedPayment": {
          "period": 15,
          "periodType": "days"
        },
        "consecutiveMissedPayments": {
        	"number": 5
        },
        "missedPaymentsOverPolicyTerm": {
        	"number": 10
        },
        "missedPaymentsWithinPeriod": {
        	"number": 6,
          "period": 12,
          "periodType": "months"
        }
      }
    },
    "lapseExclusionRules": {
    	"lapsePolicyWithProcessingPayment": false
    },
    ...
  }
}

Lapse rules

After first missed payment

Properties

On consecutive missed payments

Properties

On missed payments over policy term

Properties

On missed payments within period

Properties

Lapse Exclusion rules

Lapse exclusion rules provide a way to bypass the lapse criteria defined in the Lapse rules. Essentially, they can prevent a policy from being lapsed.

Lapse policy with processing payment

Not-taken-up rule enabled

This setting governs what happens when a policy's first payment fails or is reversed. If enabled, a policy's status will be changed to not_taken_up if the first payment fails or is reversed. The policy will no longer be active, and no further billing will run against the policy (similar to a policy lapsing).

Note: If this setting is enabled, the grace period will not apply to the first payment.

{
  "settings": {
    "notTakenUpEnabled": true,
    ...
  }
}

Cooling-off period

If the cooling-off period is enabled, and the policy is cancelled within the cooling-off period, the policyholder will be refunded for any premiums that have already been collected. The cooling-off period is calculated from the policy start date.

To disable the cooling-off period, set the value of theFullPolicy to null.

{
  "settings": {
    "coolingOffPeriod": {
      "applyTo": {
        "theFullPolicy": {
          "period": 1,
          "periodType": "months",
          "refundType": "all_premiums"
        }
      }
    },
    ...
  }
}

Properties

Waiting period

If this setting is enabled, and a claim is opened within the policy waiting period, an alert will be displayed on the dashboard (see screenshot below). The alert is displayed based on the current date when the dashboard user is viewing the claim.

📘

Claims blocks offer greater flexibility in handling waiting periods

Claims blocks allow for greater flexibility when handling waiting periods. For example, you can capture the date of loss and display a warning if the date of loss is within the waiting period. You can also configure different warnings for different policy benefits.

To disable the waiting period, set the value of theFullPolicy to null.

{
  "settings": {
     "waitingPeriod": {
        "applyTo": {
          "theFullPolicy": {
            "period": 30,
            "periodType": "days"
          }
        }
     }, 
     ...
  }
}