Automated Underwriting

Socotra supports automatically accepting or rejecting a risk based on underwriting guidelines. If guidelines exist in the configuration, Socotra will only allow a policy transaction to be issued when the underwriting decision is accept.

The underwriting check is executed for the following transactions, before they will become quoted:

  • New Business

  • Endorsements

  • Renewals

  • Reinstatements

Configuration

The underwriting decision can be made using a plugin written in JavaScript.

Input: Data Object

The plugin will be provided a data object that looks like this:

UnderwritingPluginData
required
operation string new_business | endorsement | renewal | reinstatement
policy PolicyResponse
policyholder PolicyholderResponse

The policy data will reflect pending changes for the transaction being processed.

Return Object

The plugin function should return an object that looks like this:

UnderwritingPluginResponse
required
decision string accept | reject | none
notes [string]

Example: Hello World Underwriting Decision Plugin

Sample underwriting decision plugin implementation:

// in underwriter.js
function getUnderwritingResult(data)
{
  console.log("Hello underwriting world!");

  return {
    "decision": "accept",
    "notes": [ "Everyone wins!" ]
  };
}
exports.getUnderwritingResult = getUnderwritingResult;

Workflow

When you finalize a policy using either the UI or the API, the following occurs:

  1. The policy is locked from any further updates.

  2. Socotra calculates and saves the policy pricing.

  3. Underwriting guidelines are run and the resulting decision and notes are saved for the policy.

  4. If the underwriting result is accept, invoices and all policy documents are generated. The policy can then be issued. If the result is reject or none, no invoices or documents are generated and nothing further can be done to the policy except discard it.

Automated Underwriting Results in the UI

After a policy is finalized, the automated underwriting decision is in the “Details” section of the page.

Automated Underwriting Results in the API

The AutomatedUnderwritingResultResponse, which is in the PolicyModificationResponse, contains the decision, the time at which it was made, and any notes saved during the process.

Using the API to test automated underwriting logic

The fetch underwriting result endpoint allows you to run automated underwriting against a policy and see the result without saving any data onto the policy. This endpoint can be used on any policy, regardless of whether it has been finalized or issued.

Configuration (Legacy)

Warning

Liquid for underwriting is considered Legacy. Socotra recommends using the plugin for underwriting.

With Liquid, underwriting guidelines are configured at the product level, in policy/underwriting.guidelines.liquid. This template has the same data available to it as do Document Templates.

set_underwriting_decision

This Liquid filter sets the underwriting decision. If you call this filter multiple times, the last call sets the decision. It takes one of two possible values:

  • accept

  • reject

add_underwriting_note

Use this Liquid filter to add underwriting notes to the policy. It can be used repeatedly to add more notes, and is not linked to usage of the set_underwriting_decision filter. It takes a string as input.

Note

Underwriting notes do not need to be human-readable. You can use codes, as shown in the example below, to facilitate automation and integrations with external systems.

Example: Default Value

Socotra recommends setting a default value and then using conditional statements to overwrite that decision as necessary.

{{ "accept" | set_underwriting_decision }}
{% if vehicle_value > 100000 %}
 {{ "reject" | set_underwriting_decision }}
     {{ "Exotic_vehicles_are_notinsurable_(UW-008)" | add_underwriting_note }}
{% endif %}

Note that in this snippet, if vehicle_value is more than 100,000, set_underwriting_decision is called twice, with the second call determining the decision.