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:
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:
If there are any flags with
approve
status, underwriting passes and the transaction will transition to the desired state; otherwiseIf there are any flags with
reject
status, underwriting fails and the quote state will be set torejected
; elseIf there are any flags with
decline
status, underwriting fails and the quote state will be set todeclined
; elseIf there are any flags with
block
status, underwriting fails and the quote state will be set tounderwritingBlocked
; otherwise underwriting passes.
Based on this algorithm:
If you never want to block underwriting, just avoid adding any flags or add only
accept
orinfo
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
, ordecline
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 inunderwritingBlocked
state.declined
: The transaction is indeclined
state.rejected
: The transaction is inrejected
state.approved
: The transaction has reachedunderwritten
state and needs no more checks unless the transaction is reset.