# Underwriting
import Image from 'next/image';
This article provides an **overview of underwriting** in the Socotra Insurance Suite.
Overview [#overview]
In the Socotra Insurance Suite, **underwriting** is a process that determines whether a quote or policy transaction is worthwhile from a business standpoint.
Typically, underwriting utilizes an **underwriting plugin**. The underwriting plugin uses custom logic (written in Java) to analyze a transaction.
Based on its analysis, the underwriting plugin assigns **underwriting flags** to the transaction.
What is an underwriting plugin? [#what-is-an-underwriting-plugin]
An **underwriting plugin** is a module that contains custom logic (written in Java) to perform underwriting checks.
The underwriting transaction is capable of adding and clearing (removing) underwriting flags.
The plugin determines if the transaction passes underwriting. If so, the flow continues. If not, the transaction diverts to a blocked state.
What is an underwriting flag? [#what-is-an-underwriting-flag]
An **underwriting flag** is a marker that can be added to a transaction. Underwriting flags are either:
* Added manually (via the API or web app)
* Added programmatically (via an underwriting plugin)
There are five types of underwriting flags:
* `approve`
* `block`
* `decline`
* `info`
* `reject`
Once underwriting flags have been applied to a transaction, the system performs an **evaluation** process to analyze whether the transaction should proceed.
Post-underwriting Evaluation [#post-underwriting-evaluation]
After a transaction goes through pricing, the typical next step is for it to go through an underwriting plugin. The underwriting plugin adds or clears any flags on the transaction.
The next step is **evaluation**, where an algorithm determines the appropriate course of action for a transaction given its assigned flags. Then, the transaction is assigned an **underwriting status**.
Evaluation algorithm [#evaluation-algorithm]
The **evaluation algorithm** examines the remaining uncleared flags on a quote. The system makes the following checks in order:
1. If there are any `approve` flags assigned to the quote, underwriting *passes*. The transaction will transition to the desired state.
2. If there are any `reject` flags assigned to the quote, underwriting *fails*. The quote state will be set to `rejected`.
3. If there are any `decline` flags assigned to the quote, underwriting *fails*. The quote state will be set to `declined`.
4. If there are any `block` flags assigned to the quote, underwriting *fails*. The quote state will be set to `underwritingBlocked`.
5. Otherwise, underwriting passes.
Tips [#tips]
Based on the algorithm described above, we suggest the following tips:
* **If you never want to block underwriting**, avoid adding any flags (or only add `approve` or `info` flags).
* If your **decision making logic is in a system external to Socotra**, fetch that system's result in the underwriting plugin. Based on result, add an `approve`, `reject`, or `decline` flag. Evaluation will proceed as described above.
* If you **have a system where you also need to accomplish certain checks** (e.g. property inspection or manual review), you can add (and subsequently clear) `block` flags for each task.
Underwriting status [#underwriting-status]
Every quote has an `underwritingStatus` property that indicates the underwriting decision applied to the quote.
* `approved`
* `blocked`
* `declined`
* `none`
* `rejected`
The `rejected` underwriting status is terminal. You cannot reset a transaction of its underwriting status when it is rejected. If this is not acceptable, we recommend using the `decline` or `block` flags as alternatives.
Example Underwriting Scenario [#example-underwriting-scenario]
A commercial auto quote advances to underwriting, and the [Underwriting Plugin](/configuration/plugins/underwriting) adds a `block` flag to the vehicle schedule element, resulting in the following :
```javascript
{
"quoteLocator": "01JHN92K8KJTRV8ZBHKN9QAF41",
"accountLocator": "01JHG7ZM32ET1R1JFRRB80BXSS",
"quoteState": "underwrittenBlocked",
"productName": "CommercialAuto",
// ...,
"underwritingStatus": "blocked",
"underwritingFlags": [
{
"locator": "01JHN9AQD6JS0Q67MNGCQSZ2Z5",
"level": "block",
"referenceType": "quote",
"referenceLocator": "01JHN92K8KJTRV8ZBHKN9QAF41",
"note": "Vehicle schedules with TIV over $100K must be reviewed by an underwriter",
"tag": "uw_rule_01",
"elementLocator": "01JHN92K8KZCSHX4QEJMBRTKAS",
"createdTime": "2025-01-15T15:29:21.318840Z"
}
]
}
```
The quote is currently `blocked`.
Later, an underwriter decides that this quote looks acceptable and should be advanced to `underwritten`. She decides to clear the flag while also adding an additional informational flag to the vehicle schedule element. Here's the body of the corresponding , exemplifying underwriting via the API:
```javascript
{
"addFlags": [
{
"level": "approve",
"elementLocator": "01JHN92K8KZCSHX4QEJMBRTKAS",
"note": "Acceptable risk"
}
],
"clearFlags": [
"01JHN9AQD6JS0Q67MNGCQSZ2Z5"
]
}
```
The manual underwriting update results in the following :
```javascript
{
{
"quoteLocator": "01JHN92K8KJTRV8ZBHKN9QAF41",
"flags": [
{
"locator": "01JHN9R36S986XH99HDVABM5EW",
"level": "approve",
"referenceType": "quote",
"referenceLocator": "01JHN92K8KJTRV8ZBHKN9QAF41",
"note": "Acceptable risk",
"elementLocator": "01JHN92K8KZCSHX4QEJMBRTKAS",
"createdBy": "dc68c494-6918-487a-bf08-58c2983175dc",
"createdTime": "2025-01-15T15:36:39.385573Z"
}
],
"clearedFlags": [
{
"locator": "01JHN9AQD6JS0Q67MNGCQSZ2Z5",
"level": "block",
"referenceType": "quote",
"referenceLocator": "01JHN92K8KJTRV8ZBHKN9QAF41",
"note": "Vehicle schedules with TIV over $100K must be reviewed by an underwriter",
"tag": "uw_rule_01",
"elementLocator": "01JHN92K8KZCSHX4QEJMBRTKAS",
"createdTime": "2025-01-15T15:29:21.318840Z",
"clearedBy": "dc68c494-6918-487a-bf08-58c2983175dc",
"clearedTime": "2025-01-15T15:36:39.385009Z"
}
]
}
}
```
Since the `block` flag has been cleared, and there are no other uncleared blocking flags, the quote can proceed to `underwritten` when the underwriter attempts to underwrite the quote again.
See also [#see-also]
* [Policy Transaction Underwriting API](/api/policy-management/policy-transactions#policyTransactionUnderwritingApi)
* [Quote Underwriting API](/api/quotes/quotes#quoteUnderwritingApi)