General settings

Complete your product's basic setup without touching any code

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. Read more about group policies in the group policies guide (work in progress).

SettingDefinition
policySchemeTypeString. The policy scheme type. One of ["individual", "group"].

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.

SettingDefinition
dashboardIssuingEnabledBoolean. Indicates whether policies can be issued via the Root management dashboard.

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.

SettingDefinition
canReactivatePoliciesBoolean. Indicates whether inactive policies can be reactivated.

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.

SettingDefinition
canRequote (deprecated)Boolean. Indicates whether the requote hook is enabled for this product.

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
        }
      }
    },
   	...
  }
}

Properties

SettingDefinition
companiesAllowedBoolean. Whether legal persons such as companies are allowed to take out policies
individualsAllowedBoolean. Whether individuals (natural persons) are allowed to take out policies.

If this setting is true, one or more of individualsIdAllowed and individualsPassportAllowed must be true.
individualsIdAllowedBoolean. Whether an ID number is allowed as a unique identifier for policyholders.
individualsPassportAllowedBoolean. Whether a Passport number is allowed as a unique identifier for policyholders.
individualsCellphoneAllowedBoolean. Whether a Cellphone number is allowed as a unique identifier for policyholders.
individualsEmailAllowedBoolean. Whether an Email address is allowed as a unique identifier for policyholders.
individualsCustomIdAllowedBoolean. Whether a custom identifier is allowed as a unique identifier for policyholders.
customIdNameString. The name of your custom identifier and will render on the Root dashboard policy issuing workflow.
idCountryString. The
ISO Alpha-2 country code used to pre-populate the country input for the ID, cellphone and address on the Root dashboard policy issuing workflow.
individualPolicyholderFieldsObject. Make specific fields on an individual policyholder optional or required for issuing policies on your product module. policyholder.date_of_birth and policyholder.address.suburb are supported.

The policyholder data will be validated against these settings when a policyholder is created in the dashboard issuing flow and embed. When issuing policies over the API, the policyholder data is validated at the application step.

📘

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
    },
   	...
  }
}
SettingDefinition
beneficiariesObject or null. Whether or not beneficiaries can be added to policies. If set to null, adding beneficiaries will be disabled.

Properties

SettingDefinition
makePolicyholderABeneficiaryBoolean. If enabled, the policyholder will automatically be added as the first beneficiary when a policy is issued.
minInteger. The minimum number of beneficiaries that have to be added to a policy.
maxInteger. The maximum number of beneficiaries that can be added to a policy.

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

SettingDefinition
welcomeLetterEnabledBoolean. Whether a welcome letter will be sent to the policyholder when the policy is activated. Read more about the welcome letter.

Policy anniversary notification

SettingDefinition
policyAnniversaryNotificationObject or null. Whether an anniversary notification letter will be sent to the policyholder before each anniversary of the policy start date. Read more about the policy anniversary letter.

To disable the policy anniversary letter, set this parameter to null.

Properties

SettingDefinition
daysBeforeToSendInteger. The number of days before the policy anniversary date that the anniversary letter will be generated and sent to the policyholder.

Policy documents

SettingDefinition
policyDocumentsArray of Objects. Used to specify custom file names for policy documents, and to enable the optional certificate policy document.

Properties

SettingDefinition
typeString. One of ['policy_schedule', 'terms', 'welcome_letter', 'policy_anniversary', 'certificate', 'supplementary_terms'].
supplementaryTermsType
optional
String. Required if type is supplementary_terms, forbidden otherwise. Must match the filename of a PDF document in documents > supplementary-terms, without the file extension.
fileName
optional
String. Used to specify a custom filename for the document. Handlebars may be used to dynamically reference policy specific data. The merge variables available to the filename are the same as those available to the policy document. The file extension must be omitted.

Defaults to policy_{{ policy.policyNumber }}_{{ file_type }}.
enabled
optional
Boolean. Required when type is certificate, forbidden otherwise. Set to true to enable the certificate.

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",
     ...  
   }     
}
SettingDefinition
activatePoliciesOnEventString. The event that activates a policy. One of ["policy_issued", "payment_method_assigned", "first_successful_payment", "none"].

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

SettingDefinition
afterFirstMissedPaymentObject or null. If enabled, the policy will lapse a specified period after the first missed payment.

To disable this lapse rule, set this parameter to null.

Properties

SettingDefinition
periodInteger. The number of days, months or years to lapse the policy after the first missed payment.
periodTypeString. One of ["days", "months", "years"].

On consecutive missed payments

SettingDefinition
consecutiveMissedPaymentsObject or null. If enabled, the policy will lapse after the specified number of consecutive missed payments.

Note: Failed retry payments count towards total missed payments.

To disable this lapse rule, set this parameter to null.

Properties

SettingDefinition
numberInteger. The number of consecutive missed payments that will cause the policy to lapse.

On missed payments over policy term

SettingDefinition
missedPaymentsOverPolicyTermObject or null. If enabled, the policy will lapse after the specified number of missed payments, calculated from when the policy was issued.

Note: Failed retry payments count towards total missed payments.

To disable this lapse rule, set this parameter to null.

Properties

SettingDefinition
numberInteger. The number of missed payments, calculated from when the policy was issued, that will cause the policy to lapse.

On missed payments within period

SettingDefinition
missedPaymentsWithinPeriodObject or null. If enabled, the policy will lapse if the number of missed payments within a specified period exceed a specified number.

Note: Failed retry payments count towards total missed payments.

To disable this lapse rule, set this parameter to null.

Properties

SettingDefinition
numberInteger. The number of missed payments, calculated over the defined period, that will cause the policy to lapse.
periodInteger. The number of days, months or years over which the missed payments will be calculated.
periodTypeString. One of ["days", "months", "years"].

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

SettingDefinition
lapsePolicyWithProcessingPaymentData Type: Boolean or null.

When this rule is set to false, a policy that meets the criteria for lapsing, according to the Lapse rules, will not be immediately lapsed if it has a payment associated with it that is in one of the following states: Pending, Processing, or Submitted. Instead, the policy will only be considered for lapsing once the processing payment transitions to a finalised state, such as Successful, Failed, or Cancelled.

By default, this rule is set to false, meaning that policies with processing payments will not be lapsed. If this setting is left undefined or null, the API will behave as if it is set to false.

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,
    ...
  }
}
SettingDefinition
notTakenUpEnabledBoolean. If enabled, the policy status will be changed to not_taken_up if the first payment fails.

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"
        }
      }
    },
    ...
  }
}
SettingDefinition
theFullPolicyObject or null. Whether or not to apply a cooling-of period to policies.

To disable the cooling-off period, set this parameter to null.

Properties

SettingDefinition
periodInteger. The number of days, months or years from the policy start date that the cooling-off period will apply.
periodTypeString. One of ["days", "months", "years"].
refundTypeString. Must be "all_premiums".

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.

609
{
  "settings": {
     "waitingPeriod": {
        "applyTo": {
          "theFullPolicy": {
            "period": 30,
            "periodType": "days"
          }
        }
     }, 
     ...
  }
}
SettingDefinition
theFullPolicyObject or null. Whether or not to enable the waiting period warning notification in the claims workflow.

To disable the warning, set this parameter to null.
SettingDefinition
periodInteger. The number of days, months or years from the policy start date that the waiting period will apply.
periodTypeString. One of ["days", "months", "years"].

What’s Next