Overview

Issuing a policy is analogous to flicking a switch to turn an application into a binding contract. No additional input data is saved to the policy at this step.

Policies are issued using the policies endpoint. Only one field is required for the request payload: the application_id. This is standard across all product modules and requires no further configuration or validation.

The application_id is returned by the application endpoint when an application is created.

{
  "application_id": "616782ef-6397-4faa-af5d-dc48fc1ed3e9"
}

You also do not need to configure the dashboard workflow for the policy issue step, which is standard for all product modules.

Configuring the getPolicy() function

To allow policies to be issued, your product module code needs to include a getPolicy() function (example below). It takes as arguments the application object, the policyholder object, and the billing day.

const getPolicy = (application, policyholder, billing_day) => {
  const policy = new Policy({
    policy_number: generatePolicyNumber(),
    package_name: application.package_name,
    sum_assured: application.sum_assured,
    base_premium: application.base_premium,
    monthly_premium: application.monthly_premium,
    start_date: moment().add(1, 'day').format(), // start tomorrow
    end_date: moment().endOf('month').add(1, 'year').format(), // in 1 year
    charges: application.module.charges,
    module: {
      ...application.module
    },
  });
  return policy;
}

The billing day is an integer representing the day of the month that the customer will be billed. The billing day is specified when a payment method is added to a policy. If no payment method has been added at the time of policy issue, the billing day defaults to 1.

See the policy object API reference for more information on the standard fields that need to be included on the policy object, and what they represent. The product-specific information, taken from the application object created previously, is saved under the module object.

The policy object returned by this function is saved to the platform, and returned over the API. The returned policy object has both a policy number (for example 1HFCT1CDBJ), and a policy_id (for example 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e.

The policy number is a more easily readable reference for use in policy documents, the management dashboard and customer notifications. The policy_id is a UUID and can be used to query the policy over the API.

📘

Working with dates

The start and end date of a policy are specified in the getPolicy() function. To make working with dates easier, Root enables the use of the moment.js library.

We recommend specifying dates as ISO 8601 strings using moment().format().

Charges and commissions

Any premium paid is usually constructed from different components like reinsurance premium, commission, other intermediary fees, risk premium, and so on. Root allows you to track this on a per-policy and per-payment level through the use of "costs and charges", stored as charges: [...] on a policy.

This allows the premium breakdown to be referenced in policy documents and disclosures, and more importantly in the policy's payment data. Whenever a payment is created (including payment reversals), the charges saved to the policy are applied to the payment amount and saved to the payment object.

This means that a data export created from the payment data (such as the "costs and charges" data source) can show a breakdown of each payment between the different costs and charges, and the balance remaining.

To enable this, you need to define the charges array saved to the policy. An example of the required format is included below.

Each object within the charges array must have the following fields:

• name - The name of the charge.
• description - A description of the charge.
• type - One of [variable, fixed, balance]. Variable charges are applied as a proportion of the total payment amount. Fixed charges are applied as an absolute currency value in cents. The balance is the balance of the payment total after all charges have been applied.
• amount - Either a proportion of the total premium (if the type parameter is variable), or a currency amount (if the type parameter is fixed). Not allowed if the type is balance.

{
  charges: [
    {
      type: 'fixed',
      name: 'Collection fees',
      description: 'Debit order collection fees (fixed)',
      amount: 322,
  	}, 
    {
      type: 'variable',
      name: 'Risk premium',
      description: 'Risk and claims component of the premium',
      amount: 0.4,
  	}, 
    {
      type: 'variable',
      name: 'Admin fees',
      description: 'Admin and claims handling fees',
      amount: 0.09,
  	}, 
    {
      type: 'variable',
      name: 'Commission',
      description: 'Sales and channel commission',
      amount: 0.2,
  	}, 
    {
      type: 'balance',
      name: 'Profit',
      description: 'Remaining amount',
  	}
  ],
}

Charges are typically calculated during the quote step in the policy issue process within the quote hook when the premium is calculated. This also allows relevant charges to be displayed to the customer as part of the quote if required. In this case the array of charges would be carried over from the quote module to the application module, and finally saved in the top-level charges field of the policy.