Overview

On Root, you can configure templates for a range of policy documents. These documents serve both as a form of communication with policyholders, and as a human readable record of important policy information.

The document templates are built in HTML, and are converted to PDF by the Root platform. Root enables the use of handlebars to dynamically reference and inject policy, policyholder and claim data into policy documents at execution time.

When each document is created, it is stored on the platform and can be viewed and downloaded on the Root management dashboard (this does not apply to the quote summary).

The (re)creation of each document is triggered by specific events in the policy lifecycle. Where these events also trigger an email notification to the customer, the relevant documents will be attached to the email. Read more about which documents are attached to which emails in the customer notifications overview guide.

📘

Policy documents (except terms file) are automatically regenerated

Policy documents are automatically regenerated by the platform when specific customer notification events (for example, updating a policy) are triggered on Root. The platform will use the document templates associated with the latest live product module definition linked to the policy.

Note, however, that the policy terms file is never regenerated, irrespective of whether a new product module definitions has been deployed since the policy was issued.

Policy document types

Some documents, like the policy schedule and terms file, are required for every product module. Other documents, like the welcome letter and anniversary letter, can be enabled or disabled in the general product settings according to your needs.

You can specify a custom filename for each document when it is sent to the policyholder as an email attachment. Read more about specifying custom policy document filenames in the general settings guide .

Required documents

• Policy schedule: this document is created whenever a new policy is issued or an existing policy is updated or altered. It's seen as the primary contract between the insurer and the policyholder.
• Terms file: this document contains the generic terms and conditions applied across all policies, which are typically also made available on the insurer's website.

Other documents

• Quote summary: if enabled, this document can be manually triggered from the Root management dashboard to send customers a formal document, based on the application data, to review before proceeding to issue a policy.
• Welcome letter: if enabled, this document is generated alongside the policy schedule when a policy payment method is attached (the activation date does not necessarily coincide with the policy issue date).
• Anniversary letter: if enabled, this document is created annually before the anniversary of the policy start date.
• Certificate: if enabled, this document is created whenever a new policy is issued or an existing policy is updated or altered. Apart from being optional, the certificate is functionally equivalent to the policy schedule.
• Member certificate: this document is required for group policies and gets created for each individual member on the policy.

Policy schedule

Required: Yes
Merge variables: policyholder, policy, payment_method

The policy schedule typically contains all the important policy information related to the policyholder, premiums, benefits, cover levels and beneficiaries. It represents the details of the insurance agreement between the policyholder and the insurer, insofar as those details are specific to the individual policy. General terms and conditions are contained in the terms file.

Terms file

Required: Yes
Merge variables: N/A

The terms file is a static PDF file that contains the terms and conditions for the product. This typically includes definitions, exclusions, waiting periods and other aspects of the insurance agreement that apply to all policies issued under your product module. The terms and conditions are typically publicly accessible on the insurer's website.

This document does not allow for policy specific information or other data to be dynamically injected.

Note: The terms file created when a policy is issued is never regenerated.

Supplementary terms files

Required: No
Merge variables: N/A

You can extend the terms file with up to five supplementary terms files. These files behave in the same way as the main terms file, and are attached to the same email notifications. Similar to the main terms file, supplementary terms files are not updated during the policy lifecycle.

Supplementary terms files should be included as PDF documents in the documents > supplementary-terms directory in your local product module directory. The filename (without the extension) of each supplementary terms file will be used as the supplementary terms file type.

Quote summary

Required: No
Merge variables: policyholder, application

The quote summary allows customers to review the premium and any other relevant policy information before confirming that a policy can be issued. This document can be created after the application step has been completed, and references the information saved to the application object.

Unlike the other documents, the quote summary document is not created automatically, and needs to be triggered by the dashboard user processing the application. Since the are created before the policy is issued, they are not stored against the policy.

📘

Quote summaries are typically only used in high-touch call centre sales flows

Quote summaries are typically only used by high-touch call centre sales and not by direct digital sales channels. This is because both the quote and and application objects are returned over the Root API, and the information stored on these objects can easily be displayed to the customer on your own front-end.

Welcome letter

Required: No
Merge variables: policyholder, policy, payment_method

The welcome letter is typically used as a salutary document addressed to the policyholder, highlighting important information from the policy schedule and terms file, and explaining how the policyholder can get in touch with the insurer with queries or complaints. There are no hard content requirements, so you can customise the welcome letter to suit your needs.

To enable welcome letters for your product, you need to switch on the corresponding setting in the general product settings.

Anniversary letter

Required: No
Merge variables: policyholder, policy, payment_method

The anniversary letter is sent to the policyholder annually before the policy anniversary date. This letter can be used, for example, to inform customers about premium increases, or to remind them to review their policy benefits or beneficiary details.

To enable anniversary letters for your product, you need to switch on the corresponding setting in the general product settings. You can also configure how long before the anniversary the letter will be sent.

Certificate

Required: No
Merge variables: policyholder, policy, payment_method

The certificate is proof of the existence of the policy, and summarises the key aspects and conditions of the policy. It typically contains details of the specific policy and policyholder, and is generated whenever a new policy is issued or an existing policy is updated or altered.

Apart from being optional, the certificate is functionally equivalent to the policy schedule. If enabled, it is regenerated and attached to emails based on the same rules as the policy schedule.

Member certificate

Required: Yes (for group products)
Merge variables: policyholder, policy, member

In the case of group products, there is only a single policy schedule representing the agreement between the insurer and the group entity, and each additional member added to the policy receives a member certificate. This document certifies that an individual member has been added to a group policy, and typically sets out what is covered under the policy insofar as this information relates to the individual member.

Member certificates are required if the policy scheme type is set to group in the general product settings.

HTML templates

Root supports building dynamic policy document templates in HTML. When a policy document is created, the Root platform converts HTML templates to PDF. The PDF is linked to a specific policy, stored on the platform, and attached to any relevant email communications.

The PDF documents are created with an A4 page size (210mm x 297mm) and a fixed margin of 20mm on all sides. However, the a magnification factor is applied to the underlying template, causing the usable page size (excluding margins) on the template to be smaller than A4, at approximately 130mm x 198mm.

Policy document templates are built in a single HTML file, which must also contain all CSS. The HTML templates can reference external URLs for images and fonts. Note: The HTML to PDF conversion engine only supports CSS Level 2. Certain advanced features from CSS Level 3 onwards (such as Flexbox) are not supported.

📘

External images and fonts should be hosted in a stable location

External images should be hosted in a stable location, to ensure availability when policy documents are generated. For external fonts, we recommend using a hosted font from Google Fonts if possible.

Handlebars

Policy document templates dynamically reference policy and policyholder data by means of handlebars. This allows you to inject the policyholder's name, surname and other details, and any relevant policy data such as the premium, sum assured, selected benefits and other product-specific fields into the document.

Root also enables the use of a range of custom handlebars helpers to format and manipulate data before it is injected into the document. Root helper functionality includes basic formatting of strings, currencies and data values, basic arithmetic and date manipulation, conditional logic and basic control structures.

The available data objects ("merge variables") varies from one document type to another. For example, the policy schedule references the policyholder and policy objects, while the quote summary references the policyholder and application objects.

The handlebars guide thoroughly documents how to use handlebars in your document templates with comprehensive code snippets and examples.

Starter template

We suggest using the example below as a starting point for building a policy document template. Using this structure helps to make document templates robust.

<html lang="en">
  <head>
    <meta charset="utf-8">
    <style type="text/css">
      .page {
        width: 13cm;
        min-height: 19.8cm;
        position: relative;
        page-break-after: always;
      }
      .page.no-break {
        page-break-after: auto;
      }
    </style>
  </head>
  <body>

    <div class="page"> <!-- Page 1 start -->
      <div style="position: absolute; left: 0; top: 0;">
        Top left of first page
      </div>
      <div style="position: absolute; bottom: 0; right: 0;">
        Bottom right of first page
      </div>
    </div> <!-- Page 1 end -->

    <div class="page no-break"> <!-- Page 2 start -->
      <div style="position: absolute; left: 0; top: 0;">
        Top left of second page
      </div>
      <div style="position: absolute; bottom: 0; right: 0;">
        Bottom right of second page
      </div>
    </div> <!-- Page 2 end -->

  </body>
</html>

The starter template wraps the contents of each page in a parent div. Setting the width and min-height properties of this div to 13cm and 19.8cm respectively ensures that the div occupies the full usable page area.

The position property of the parent div is set to relative, while the position of child elements is set to absolute. This allows you to position child elements at fixed positions on the page, for example to position a footer at the bottom of the page.

Setting the page-break-after property to always creates a page break in the PDF after the page div. This is useful if you want a new section of the document to start on a new page. On the last page, the page-break-after property is set to auto to prevent creating a blank page at the end of the document.

Since only the min-height property is set on the page div, one div can span multiple pages in the document (this will happen if the content exceeds the height of the div). You can prevent this by setting the height and overflow properties of the page div instead of min-height.

This configuration is only recommended as a starting point, and you can adjust the configuration of these properties to suit your needs.

📘

Make your document templates robust to variable content length

The dynamic data injected into your document can result in content of variable length. For example, one policyholder's address could occupy two lines, while another policyholder's address could occupy four lines. One policy may have three nominated beneficiaries, while another policy may have none.

It's important to take this into account in the design and testing of your template, and ensure the document structure is robust to dynamic content of variable length.