Underwriter Functions¶

Functions for automated underwriting decisions, referrals, and risk assessment.

Overview¶

The Underwriter subsystem manages:

Automated decisions - Accept, decline, or refer quotes
Multi-level referrals - Route to appropriate authority levels
Endorsements - Add policy conditions and exclusions
Decision tracking - Maintain audit trail of underwriting decisions

Decision Functions¶

`$AddUnderwriterDecision`¶

Records an underwriting decision.

Signature

$AddUnderwriterDecision(decision, code, message, authorityLevel)
// OR
$AddUnderwriterDecision(decisionObject)

Parameters

decision (string) - Decision type: "Valid", "Declined", "Referred"
code (string) - Decision code for categorization/tracking
message (string) - Decision reason/message
authorityLevel (string, optional) - Authority level required (default: "NoAuthority")

Alternatively, pass a single decision object with properties: decision, code, message, authority

Returns

null

Environment Variables Updated

UnderwriterDecisions - Array of decision objects

Example

// Accept automatically
$AddUnderwriterDecision("Valid", "STD-001", "Standard risk profile", "NoAuthority");

// Require manual review
$AddUnderwriterDecision("Referred", "HVC-002", "High value claim history", "UnderwriterAuthority");

// Decline
$AddUnderwriterDecision("Declined", "AGE-001", "Applicant below minimum age", "NoAuthority");

// Using object notation
let decision = {
    decision: "Declined",
    code: "RISK-HIGH",
    message: "Unacceptable risk level",
    authority: "NoAuthority"
};
$AddUnderwriterDecision(decision);

`$Decline`¶

Declines a quote with a code and reason.

Signature

$Decline(code, reason)

Parameters

code (string) - Decline code for categorization
reason (string) - Decline reason/message

Returns

null (adds decision to UnderwriterDecisions)

Example

if (customerAge < 18) {
    $Decline("AGE-MIN", "Applicant must be 18 or older");
}

if (previousClaims > 5) {
    $Decline("CLM-EXCESSIVE", "Excessive claim history - unacceptable risk");
}

if (!hasValidLicense) {
    $Decline("LIC-INVALID", "Valid driving license required");
}

`$Referral`¶

Refers a quote for manual underwriting review.

Signature

$Referral(code, reason, authorityLevel)

Parameters

code (string) - Referral code for categorization
reason (string) - Referral reason/message
authorityLevel (string) - Authority level required (e.g., "UnderwriterAuthority", "SeniorAuthority")

Returns

null (adds referral decision)

Example

if (itemValue > 10000) {
    $Referral("VAL-HIGH", "High value item - requires underwriter approval", "UnderwriterAuthority");
}

if (unusualRisk) {
    $Referral("RISK-UNUSUAL", "Non-standard risk profile", "UnderwriterAuthority");
}

if (complexCase) {
    $Referral("CASE-COMPLEX", "Multiple risk factors require senior review", "SeniorAuthority");
}

Multi-Level Referrals¶

For complex organizational hierarchies, route to specific authority levels:

`$Level1Referral`¶

Routes to Level 1 underwriter (basic authority).

Signature

$Level1Referral(code, reason)

Parameters

code (string) - Referral code for categorization
reason (string) - Referral reason/message

Returns

null

Example

if (premium > 5000) {
    $Level1Referral("PREM-L1", "Premium exceeds Level 1 authority limit");
}

if (minorModifications) {
    $Level1Referral("MOD-MINOR", "Vehicle modifications require Level 1 review");
}

`$Level2Referral`¶

Routes to Level 2 underwriter (mid-level authority).

Signature

$Level2Referral(code, reason)

Parameters

code (string) - Referral code for categorization
reason (string) - Referral reason/message

Returns

null

Example

if (premium > 10000) {
    $Level2Referral("PREM-L2", "Premium exceeds Level 2 authority limit");
}

if (significantClaimHistory) {
    $Level2Referral("CLM-SIG", "Significant claim history requires Level 2 review");
}

`$Level3Referral`¶

Routes to Level 3 underwriter (senior authority).

Signature

$Level3Referral(code, reason)

Parameters

code (string) - Referral code for categorization
reason (string) - Referral reason/message

Returns

null

Example

if (premium > 25000) {
    $Level3Referral("PREM-L3", "Premium requires senior underwriter approval");
}

if (exceptionalCircumstances) {
    $Level3Referral("CASE-EXCEPTIONAL", "Exceptional case requires senior authority");
}

Endorsements¶

`$AddEndorsement`¶

Adds an endorsement (special condition or exclusion) to the policy.

Signature

$AddEndorsement(code, description)

Parameters

code (string) - Endorsement code
description (string) - Endorsement description

Returns

null

Environment Variables Updated

Endorsements - Array of endorsement objects

Example

// Add exclusion
$AddEndorsement("EX01", "Flood damage excluded");

// Add special condition
$AddEndorsement("SC05", "Alarm system required - certificate must be provided within 14 days");

// Multiple endorsements
$AddEndorsement("EX03", "Professional use excluded");
$AddEndorsement("SC12", "Maximum single item value: £2,500");

Complete Underwriting Workflow¶

// Underwriting rules engine
fn UnderwriteQuote(customer, items, premium) {

    // Age validation
    if (customer.Age < 18) {
        $Decline("AGE-MIN", "Applicant must be 18 or older");
        return;
    }

    if (customer.Age > 80) {
        $Level1Referral("AGE-MAX", "Applicant age over 80 - requires review");
        return;
    }

    // Claim history check
    if (customer.ClaimCount > 3) {
        $Level1Referral("CLM-MULTIPLE", "Multiple previous claims - " + $ToString(customer.ClaimCount) + " claims");
        return;
    }

    if (customer.ClaimCount > 5) {
        $Decline("CLM-EXCESSIVE", "Excessive claim history - unacceptable risk");
        return;
    }

    // High value items
    let highValueItems = $Filter(items, fn(item) => item.Value > 5000);
    if ($Count(highValueItems) > 0) {
        $Level2Referral("VAL-HIGH", "High value items present - requires valuation");
        $AddEndorsement("SC20", "Proof of value required for items over £5,000");
    }

    // Premium thresholds
    if (premium > 25000) {
        $Level3Referral("PREM-L3", "Premium exceeds £25,000 - senior approval required");
        return;
    } else if (premium > 10000) {
        $Level2Referral("PREM-L2", "Premium exceeds £10,000");
        return;
    }

    // Security requirements
    if (customer.SecurityLevel < 3) {
        $AddEndorsement("SC08", "BS3621 locks required on all external doors");
        $AddEndorsement("SC09", "Burglar alarm required - certificate of installation needed");
    }

    // Professional use check
    if (customer.ProfessionalUse) {
        $Level1Referral("USE-PROF", "Professional use declared");
        $AddEndorsement("EX05", "Business use excluded unless specifically agreed");
    }

    // Accept if no issues
    $AddUnderwriterDecision("Valid", "STD-ACCEPT", "Standard risk - auto-accepted", "NoAuthority");
}

// Execute underwriting
UnderwriteQuote(Customer, Items, PricingMatrix.Premium);

Decision Priority¶

When multiple decisions are added, the most restrictive takes precedence:

Decline - Quote cannot proceed
Level 3 Referral - Requires senior approval
Level 2 Referral - Requires mid-level approval
Level 1 Referral - Requires basic approval
Referral (generic) - Requires underwriter review
Accept - Quote can proceed automatically

// Multiple decisions - Decline takes precedence
$AddUnderwriterDecision("Valid", "LOW-RISK", "Low risk profile", "NoAuthority");
$Decline("ELIG-FAIL", "Ineligible applicant");
// Result: Quote declined (decline overrides accept)

// Multiple referral levels - highest level required
$Level1Referral("REF-A", "Reason A");
$Level3Referral("REF-B", "Reason B");
// Result: Level 3 referral required

Accessing Decisions¶

// Check if quote was declined
let declined = $FindEquals(UnderwriterDecisions, "decision", "Declined");
if (declined != null) {
    $Log("Quote declined [" + declined.code + "]: " + declined.message);
}

// Check for any referrals
let referrals = $Filter(UnderwriterDecisions, fn(d) =>
    d.decision == "Referred"
);

if ($Count(referrals) > 0) {
    $Log("Quote requires referral");
    // Display referral reasons
    for (let ref in referrals) {
        $Log("[" + ref.code + "] " + ref.message + " (Authority: " + ref.authority + ")");
    }
}

// Get all endorsements
if (Endorsements != null) {
    for (let endorsement in Endorsements) {
        $Log("Endorsement " + endorsement.Code + ": " + endorsement.Description);
    }
}

Complex Decision Logic¶

// Territory-based underwriting
fn UnderwriteByTerritory(territoryCode, riskFactors) {
    if (territoryCode == "HIGH_RISK") {
        // High risk territory rules
        if (riskFactors.SecurityScore < 7) {
            $Decline("SEC-INSUFF", "Insufficient security in high-risk area");
            return;
        }

        $AddEndorsement("SC15", "24-hour alarm monitoring required");
        $Level2Referral("TERR-HIGH", "High risk territory - enhanced security confirmed");

    } else if (territoryCode == "MEDIUM_RISK") {
        // Medium risk territory
        if (riskFactors.SecurityScore < 5) {
            $Level1Referral("SEC-MED", "Security below threshold for medium-risk area");
        }

        $AddEndorsement("SC08", "BS3621 locks required");

    } else {
        // Low risk territory - standard acceptance
        $AddUnderwriterDecision("Valid", "TERR-LOW", "Low risk territory", "NoAuthority");
    }
}

UnderwriteByTerritory(Customer.TerritoryCode, RiskFactors);

Integration with Quote Flow¶

// Complete quote with underwriting
fn ProcessQuote() {
    // Calculate premium
    $CalculatePremiumAdditive("NewBusiness");

    // Run underwriting
    UnderwriteQuote(Customer, Items, PricingMatrix.Premium);

    // Check decision
    let declined = $FindEquals(UnderwriterDecisions, "decision", "Declined");
    if (declined != null) {
        return {
            Status: "Declined",
            Code: declined.code,
            Reason: declined.message,
            Premium: null
        };
    }

    let referrals = $Filter(UnderwriterDecisions, fn(d) =>
        d.decision == "Referred"
    );

    if ($Count(referrals) > 0) {
        return {
            Status: "Referred",
            Reasons: $Map(referrals, fn(r) => { code: r.code, message: r.message, authority: r.authority }),
            Premium: PricingMatrix.Premium,
            Endorsements: Endorsements
        };
    }

    // Accepted
    return {
        Status: "Accepted",
        Premium: PricingMatrix.Premium,
        Endorsements: Endorsements,
        MonthlyPayment: Output.Monthly.MonthlyPayment
    };
}

let result = ProcessQuote();

Best Practices¶

1. Clear Decline Reasons¶

Always provide specific, actionable decline reasons with meaningful codes:

// ✅ Good - specific code and clear message
$Decline("AGE-UNDER18", "Applicant age 17 - must be 18 or older to purchase policy");

// ❌ Poor - vague code and message
$Decline("ERR", "Age issue");

2. Appropriate Referral Levels¶

Route to the correct authority level with appropriate codes:

// Minor issues → Level 1
if (premium > 5000) {
    $Level1Referral("PREM-STD", "Premium over standard limit");
}

// Significant issues → Level 2
if (claimCount > 3) {
    $Level2Referral("CLM-ASSESS", "Multiple claims require assessment");
}

// Major issues → Level 3
if (premium > 25000) {
    $Level3Referral("PREM-HIGH", "High value policy requires senior approval");
}

3. Document Endorsements¶

Use clear endorsement descriptions:

// ✅ Good - actionable
$AddEndorsement("SC08", "BS3621 locks required on all external doors - certificate required");

// ❌ Poor - unclear
$AddEndorsement("SC08", "Locks");

4. Order Decisions Logically¶

Check for decline conditions first:

// ✅ Good - declines checked first
if (age < 18) { $Decline("AGE-MIN", "Below minimum age"); return; }
if (premium > 10000) { $Level2Referral("PREM-L2", "Premium exceeds limit"); return; }
$AddUnderwriterDecision("Valid", "STD-ACCEPT", "Standard acceptance", "NoAuthority");

// ❌ Poor - might accept then decline
$AddUnderwriterDecision("Valid", "STD", "Accepted", "NoAuthority");
if (age < 18) { $Decline("AGE", "Too young"); }  // Too late!

Environment Variables¶

Variable	Type	Description
`UnderwriterDecisions`	Array	All underwriting decisions
`Endorsements`	Array	Policy endorsements/conditions

Next Steps¶

Quote Calculation Functions - Integrate underwriting with pricing
Examples - Complete underwriting workflow

Underwriter Functions¶

Overview¶

Decision Functions¶

$AddUnderwriterDecision¶

$Decline¶

$Referral¶

Multi-Level Referrals¶

$Level1Referral¶

$Level2Referral¶

$Level3Referral¶

Endorsements¶

$AddEndorsement¶

Complete Underwriting Workflow¶

Decision Priority¶

Accessing Decisions¶

Complex Decision Logic¶

Integration with Quote Flow¶

Best Practices¶

1. Clear Decline Reasons¶

2. Appropriate Referral Levels¶

3. Document Endorsements¶

4. Order Decisions Logically¶

Environment Variables¶

Next Steps¶

`$AddUnderwriterDecision`¶

`$Decline`¶

`$Referral`¶

`$Level1Referral`¶

`$Level2Referral`¶

`$Level3Referral`¶

`$AddEndorsement`¶