Issuing policies


On Root, policies are issued via a five-step process, designed to imitate the process followed in traditional paper-based insurance:

  1. Get a quote - You can create a quote by capturing the minimum required fields to calculate the premium.
  2. Create a policyholder - The policyholder is used to store customer information such as their address, contact details and identification number.
  3. Create an application - On Root, a pending application represents a "draft" policy, with all policy information captured and validated.
  4. Add a payment method - A payment method (such as a debit order or card) is created for a specific policyholder, and can simultaneously be assigned to a pending application (or an issued policy).
  5. Issue a policy - A pending application is turned into a binding policy. No additional information is captured at this step.

The steps themselves are the same for all product modules, but each step (except Step 2) needs to be configured on a per product basis. For example, you need to customise the input parameters expected by your product's quote and application endpoints.

In specific circumstances, some of these steps may be optional. For example, if a policyholder already exists in your organisation on Root, you can skip Step 2 when issuing additional policies to that policyholder. You can also assign an existing payment method to a policy after it has been issued (although we recommend assigning the payment method directly after the application step).


Sandbox mode

New product modules are in sandbox mode by default, which means policies are void and premiums will not be collected (although email notifications will still be sent to policyholders).

You can read more about our sandbox and production environments in the Overview guide.

Digital and traditional channels for issuing policies

Root makes it easy to launch new digital insurance channels. You can use one or more of the following approaches to issue policies to customers.

  1. Integrating your own system or frontend with the API - You can use your own system or frontend to complete the policy issuing flow, interacting with Root only via our API. This gives you the most freedom in designing and implementing a customer onboarding workflow to suit your needs.
  2. Root Embed - Root Embed allows you to add a white-labelled, self-service onboarding flow and policy management solution to your existing digital customer journey. All workflow components are pre-built, which makes this the easiest and fastest option to set up, while still giving you the flexibility to configure the look and feel. See our Dinosure implementation as an example, and our Embed guides for configuration details.
  3. Root management dashboard - Root also enables you to issue policies via traditional channels such as call centre sales. Agents or other internal staff can use the Root management dashboard to complete the policy issuing workflow on behalf of customers. To enable this channel, you need to configure quote and application schemas for your product module.

Step 1: Get a quote

Is this step configurable? Yes.
Is this step optional? No.

The first step in issuing an insurance policy is to create a quote to present to the customer. You can customise the rating factors and the pricing logic to calculate the premium and benefits. The quotes endpoint is designed to be light-weight, fast, and is used to generate and display new quotes rapidly on a customer-facing front-end.


Quote packages expire after one week

Quote packages are designed to be low-fidelity and fast to generate. They expire after one week. If a quote package has expired, you can create a new one via the same endpoint.

The parameters for generating a quote can either be captured from the user, or they can be inferred from data already available in your system (for example, the customer's age). Apart from the required rating factors, you do not need to capture any customer information to generate a quote.

To create a quote, you need to call the create a quote endpoint. The type parameter is required in the request body, and is used by the platform to identify the product module to generate the quote(s) for. The other parameters (usually rating factors) expected by this endpoint need to be customised as part of configuring the quote hook for your product.

If dashboard issuing is enabled for your product, and you have defined a quote schema, you can also create quotes via the Root management dashboard.

This endpoint returns an array of quote packages, each with their own unique quote_package_id. After the customer has approved a quote, you will need to reference this value when creating an application.


The quote step determines whether a policy is linked to the live or draft version of a product module

To test product module changes, you can issue policies using the "draft" version of a product module. Whether a policy is linked to the live or draft product module definition is determined at the quote step.

You can read more about testing changes using the draft product module definition in the Product modules overview guide.

Step 2: Create a policyholder

Is this step configurable? No.
Is this step optional? Yes - if the policyholder already exists in your organisation on Root.

A policyholder is a customer who takes out an insurance policy. On Root, a policyholder can be a natural person or a company. For natural persons, you you will only need their name, contact details and their identification details. If they are a South African resident, this will be their RSA ID number. If they do not have a South African ID, you will need to capture their passport number and country of origin.

To create a policyholder that is a company, you will need the company name and registration number, as well as the name and contact details of a natural person within the company.

The fields stored against policyholders are standard across all products, so no customisation is required for this step.

You can create a policyholder by calling the create a policyholder endpoint. You can also upsert a policyholder, which will allow you to complete the same flow multiple times for the same customer. These endpoints return a policyholder object with its own unique policyholder_id. You will need this ID to create an application and to add a payment method for the policyholder.

If dashboard issuing is enabled for your product module, you will also be able to create new policyholders via the Root management dashboard.

On Root, new policyholders are independent entities, and can be linked to (multiple) applications, payment methods and policies through further API calls.

Step 3: Create an application

Is this step configurable? Yes.
Is this step optional? No.

An application represents a "draft" policy, with all information captured and validated. To create an application, you need to reference an existing quote package and policyholder using their quote_package_id and policyholder_id.

This step also allows you to capture any additional information to the policy. Typically this will be information that needs to be stored against the policy, but was not required to calculate the premium at the quote step. You need to customise these application parameters as part of configuring the application hook for your product.

You can also configure the application hook to perform any additional validation, such as validating the policyholder's date of birth against their age captured at the quote step.

To create an application, you need to make a call to the create an application endpoint. This endpoint returns an application object with its own application_id. You will need to reference this value to issue the policy.

If dashboard issuing is enabled for your product, you can also create applications on the Root management dashboard, provided you have defined an application schema to capture the application parameters. As an optional feature, dashboard users can also send a quote summary PDF to the policyholder via email at this step.

Applications persist on Root and can be reviewed and managed on the Root management dashboard, they don't expire. This allows you to complete any underwriting checks before issuing the policy. To make changes to an application, you can requote it by applying a new quote package.

Step 4: Add a payment method

Is this step configurable? Yes.
Is this step optional? Yes - you can also link a payment method after the policy has been issued.

A payment method is what allows a policyholder to pay their recurring monthly premiums. A payment method is created for a specific policyholder, and can then be linked to multiple applications or policies.

Root natively supports debit orders and card payment methods for recurring premium collections. You can also configure external payment methods to collect premiums using your own customer accounts system, or via a third party provider. EFT payment methods are also supported for ad hoc payments.

You can reed more about the different payment method types supported on Root, and how to configure them, in the billing settings guide.

Payment methods are created via the create payment method endpoint. Once a payment method has been created, it needs to be linked to a policy or payment method. You can do this simultaneously with creating the payment method by including the optional policy_ids or application_id fields in the request body, or you can assign a payment method to a policy separately.

You can also create payment methods via the Root management dashboard.

Step 5: Issue the policy

Is this step configurable? Yes.
Is this step optional? No.

After an application has been created (and any reviews or underwriting checks have been completed), it can be issued as a binding policy. On Root, applications and policies are separate entities.

Policies are issued via the issue a policy endpoint. No further information is captured at the step, you only need to provide the application_id in the request body. This endpoint returns a Policy object with its own policy_id.

When the policy is issued, the policy schedule and terms file are generated and sent to the policyholder via email (provided that the "policy issued" notification event is enabled in the product modules' notifications configuration).

Depending on the product module settings, cover may not be active immediately when the policy is issued. For cover to start and for collections to run against the policy, two conditions need to be met:

  1. The policy needs to be active - Policies can be issued with an active or inactive status. The events that trigger policy activation can be configured in the product module settings.
  2. The policy must reach its start date - You can use the policy issue hook to configure whether policies are issued with a start date equal to the date of issue, or a start date in the future.

Once the policy is active and the start date has been reached, cover commences and regular collections will run against the policy.

You can read more about how to manage policies after they have been issued in the managing policies guide.