Underwriting

Overview

In Socotra, Underwriting is the process to manage whether the business embodied in the transaction is worthwhile from an appetite and risk standpoint.

The basic structure is that a set of “flags” can be added to a quote or policy transaction, either manually or with a plugin, and then these flags are interpreted by the system to come to a decision.

Note

The underwriting process is the same for quotes and policy transactions. In this topic the word transaction can refer to either a quote or policy transaction.

The underwriting process looks like this, within the larger state flow of the transaction:

../_images/underwriting_flow.png

The underwriting plugin can alter the state of flags on the transaction, and then the check is done. If it succeeds, the flow continues; otherwise the flow is diverted to one of the blocked states.

Underwriting Flags

Underwriting Flags are simple entities that are collected as part of the quote or transaction process. There are five types of flags that can be added:

  • approve

  • reject

  • decline

  • block

  • info

Flags can be created either manually (via the API or a UI) or automatically in a plugin that is fired before the underwriting evaluation is done. They have a type as described above, and an optional note, which is a short string that can be used to store or evaluate other information associated with the flag. Flags can be cleared, which means they no longer have an effect, and a clearedTime property will store when the clearance happened.

Flags aren’t formally ordered but they do have a createdAt timestamp.

Plugin

The Underwriting Plugin is called immediately before the underwriting check is conducted. It has the context of the quote or policy transaction and can use that information to evaluate whether the business should continue. It also has access to the flags that have been added, and it can add other flags or clear those that already exist, based on your underwriting logic.

The plugin is always called immediately before the Evaluation step (see below). If a quote is diverted to underwritingBlocked or declined state, the plugin will be called again immediately before the re-evaluation.

Evaluation

After pricing, the client may attempt to transition the transaction to underwritten status, either directly, or by attempting a downstream action such as accept or issue. Immediately before this, two things will happen:

  • First, the plugin will be called which may add or clear flags

  • Then, the system will evaluate the collection of uncleared flags on the quote with the following algorithm:

  1. If there are any flags with approve status, underwriting passes and the transaction will transition to the desired state; otherwise

  2. If there are any flags with reject status, underwriting fails and the quote state will be set to rejected; else

  3. If there are any flags with decline status, underwriting fails and the quote state will be set to declined; else

  4. If there are any flags with block status, underwriting fails and the quote state will be set to underwritingBlocked; otherwise underwriting passes.

Based on this algorithm:

  • If you never want to block underwriting, just avoid adding any flags or add only accept or info flags.

  • If your main decision is made in a system external to Socotra, just fetch that result in the underwriting plugin and based on that, add an accept, reject, or decline flag and the evaluation will proceed as described above.

  • If you have a system where you also need to accomplish certain checks, say, a property inspection or manual review, you can add (and subsequently clear) flags of type block for each such task.

Important

The rejected state is terminal; the transaction may not be reset if the underwriting status becomes rejected. If this is not acceptable, use flags of type decline or block for those situations.

Underwriting Status

To understand the state of the underwriting decision without inferring it from the quote state, there is the underwritingStatus property on the quote, which has one of the following values:

  • none: Underwriting has not yet been checked.

  • blocked: The transaction is in underwritingBlocked state.

  • declined: The transaction is in declined state.

  • rejected: The transaction is in rejected state.

  • approved: The transaction has reached underwritten state and needs no more checks unless the transaction is reset.

See Also