Claims Management

The @openinsure/claims package manages the complete claims lifecycle from First Notice of Loss (FNOL) through final closure. The module integrates with the billing system for reserve accounting, the document system for attachment management, and the compliance engine for state-specific handling requirements.

Claims Lifecycle

FNOL Filed
    │
    ▼
┌─────────────┐
│  open       │ ◄── Assignment, initial contact, coverage verification
└──────┬──────┘
       │
       ▼
┌─────────────┐
│investigating│ ◄── Field investigation, recorded statements, expert engagement
└──────┬──────┘
       │
  ┌────┴────────────────────────┐
  │                              │
  ▼                              ▼
┌──────────┐              ┌────────────┐
│ reserved │              │  litigated │ ◄── Suit filed, defense counsel assigned
└──────┬───┘              └──────┬─────┘
       │                         │
       ▼                         ▼
┌──────────────┐          ┌────────────┐
│ in_settlement│          │ in_defense │
└──────┬───────┘          └──────┬─────┘
       │                         │
       └──────────┬──────────────┘
                  ▼
            ┌──────────┐
            │  settled │ ◄── Settlement agreement executed
            └──────┬───┘
                   │
                   ▼
            ┌──────────┐
            │  closed  │ ◄── All payments disbursed, file closed
            └──────────┘

At any stage:
  ─── denied ──► closed  (coverage denied)

FNOL — First Notice of Loss

Claims can be filed via the API, the policyholder portal, the producer portal, or by an adjuster directly.

File a Claim

POST /v1/claims
Authorization: Bearer <token>
Content-Type: application/json

{
  "policyId": "pol_01J8...",
  "dateOfLoss": "2025-06-15T14:30:00Z",
  "reportedAt": "2025-06-15T18:00:00Z",
  "lossType": "BODILY_INJURY",
  "lossCause": "SLIP_AND_FALL",
  "lossDescription": "Customer slipped on wet floor in lobby. Treated at ER.",
  "estimatedLoss": 45000,
  "claimant": {
    "name": "Jane Smith",
    "phone": "802-555-1234",
    "address": "123 Main St, Burlington, VT 05401"
  },
  "location": {
    "address": "456 Commerce Dr, Burlington, VT 05401",
    "description": "Lobby entrance"
  }
}

Response:

{
  "id": "clm_01J8...",
  "claimNumber": "GL-2025-000042",
  "status": "open",
  "policyId": "pol_01J8...",
  "assignedAdjusterId": "adj_01J8...",
  "dateOfLoss": "2025-06-15T14:30:00Z",
  "coverageVerification": {
    "policyInForce": true,
    "coverageApplies": true,
    "reservedAmount": 45000,
    "sublimitApplicable": null
  }
}

Assignment Rules

Claims are auto-assigned based on:

1. Line of business — GL claims go to GL-licensed adjusters.
2. Geography — Prefer adjusters licensed in the loss state.
3. Workload — Round-robin among available adjusters below the workload threshold (configurable, default 35 open claims).
4. Severity — Claims above $100,000 are assigned to senior adjusters.
5. Manual override — Supervisors can reassign at any time.

Reserve Management

Case Reserves

Every open claim has a case reserve — the adjuster’s best estimate of the ultimate loss and expense to settle the claim.

POST /v1/claims/:id/reserves
Authorization: Bearer <adjuster_token>
Content-Type: application/json

{
  "indemnityReserve": 35000,
  "expenseReserve": 12000,
  "rationale": "ER bills confirmed at $8,200. Ongoing PT likely. Attorney involved."
}

Reserve changes are logged to claim_reserve_history — no in-place updates. The audit trail shows every reserve movement with adjuster, date, amount, and rationale.

Reserve Adequacy Flags

The system automatically flags reserves that appear inadequate:

Flag	Trigger
ROUND_NUMBER	Reserve is an exact round number (suggests placeholder)
RAPID_INCREASE	Reserve increased >50% in 30 days
EXCEEDED_ESTIMATE	Paid-to-date + reserve exceeds original estimate by >25%
APPROACHING_POLICY_LIMIT	Reserve exceeds 80% of applicable policy limit
IBNR_OUTLIER	Claim’s development pattern is 2+ standard deviations from cohort

IBNR Reserves

Incurred But Not Reported (IBNR) reserves are calculated at the organization level by the actuarial module. OpenInsure provides:

• Chain Ladder method for standard lines
• Bornhuetter-Ferguson method for immature lines with limited data
• Manual IBNR entry for actuary override

GET /v1/analytics/:orgId/ibnr?asOf=2025-06-30

# Returns:
{
  "asOfDate": "2025-06-30",
  "method": "CHAIN_LADDER",
  "ibnrByLine": {
    "GL":    { "ibnr": 285000, "confidence": "HIGH" },
    "CYBER": { "ibnr": 140000, "confidence": "MEDIUM" }
  },
  "totalIBNR": 425000
}

Subrogation Workflow

When a third party is responsible for the loss, the claims module tracks subrogation recovery.

POST /v1/claims/:id/subrogation
Authorization: Bearer <adjuster_token>
Content-Type: application/json

{
  "potentialRecovery": 28000,
  "responsibleParty": {
    "name": "Green Valley Maintenance LLC",
    "insurer": "Acme Insurance",
    "claimNumber": "ACI-2025-887621",
    "adjusterContact": "bob.jones@acmeins.com"
  },
  "subroStatus": "DEMAND_SENT",
  "demandAmount": 35000,
  "demandDate": "2025-08-01"
}

Subrogation status codes:

Status	Description
IDENTIFIED	Third party identified, evaluating recovery potential
DEMAND_SENT	Demand letter sent to third party or their insurer
NEGOTIATING	Counter-offer received, negotiating
RECOVERED	Full or partial recovery received
CLOSED_NO_RECOVERY	Recovery not pursued or pursuit exhausted

Litigation Tracking

When a claimant files suit, the claim transitions to litigated status and triggers defense counsel assignment.

POST /v1/claims/:id/litigate
Authorization: Bearer <adjuster_token>
Content-Type: application/json

{
  "suitFiledDate": "2025-07-20",
  "courtJurisdiction": "Chittenden County Superior Court, VT",
  "caseNumber": "23-CV-0481",
  "defensePanel": "auto",   // use program's panel counsel, or provide counsel_id
  "trialDate": "2026-03-15"
}

Litigation features:

• Defense billing management — Counsel submits invoices via the portal, adjuster approves against litigation budget.
• Diary management — Automated reminders for deposition deadlines, discovery cutoffs, mediation dates.
• Coverage position letters — Template-driven reservation of rights and coverage denial letters.
• Verdict/settlement tracking — Record outcome, final payment amounts, and close litigation file.

Settlement Negotiation

POST /v1/claims/:id/settle
Authorization: Bearer <adjuster_token>
Content-Type: application/json

{
  "settlementAmount": 27500,
  "expenseAmount": 9800,
  "claimantName": "Jane Smith",
  "releaseType": "GENERAL_RELEASE",
  "payeeName": "Jane Smith",
  "payeeAddress": "123 Main St, Burlington, VT 05401",
  "paymentMethod": "CHECK"
}

Settlements above the adjuster’s authority level require supervisor approval:

Adjuster Level	Authority Limit
Associate	$10,000
Adjuster II	$25,000
Senior Adjuster	$75,000
Supervisor	$250,000
Manager	Unlimited (carrier authority applies)

Payment Disbursement

Once a settlement is approved, payment is disbursed via the billing module:

POST /v1/claims/:id/payments
Authorization: Bearer <admin_token>
Content-Type: application/json

{
  "paymentType": "SETTLEMENT",
  "amount": 27500,
  "payeeType": "CLAIMANT",
  "payeeName": "Jane Smith",
  "paymentMethod": "CHECK",
  "memo": "Settlement of claim GL-2025-000042 per release dated 2025-09-01"
}

Payment types:

Type	Description
SETTLEMENT	Final settlement payment to claimant
MEDICAL	Medical expense payment (direct to provider)
DEFENSE_EXPENSE	Defense counsel invoice payment
EXPERT_EXPENSE	Expert witness, IME, or appraiser fees
SUBROGATION_RECOVERY	Recovery received from third party (negative — income)

Claim Closure

POST /v1/claims/:id/close
Authorization: Bearer <adjuster_token>
Content-Type: application/json

{
  "closureReason": "SETTLED",
  "finalPaidIndemnity": 27500,
  "finalPaidExpense": 9800,
  "closingNotes": "Settled for $27,500. Release executed 2025-09-01. File closed."
}

On closure, the system:

1. Sets all reserves to zero (closed with final payments known).
2. Posts the final paid amounts to the loss run.
3. Updates the organization’s loss ratio statistics.
4. Triggers a bordereaux update for claims reporting.

Document Management

See the Claims Attachments API for file upload and retrieval. Supported types: PDF, JPEG, PNG, TIFF, DOCX. Max 10 MB per file.

POST /v1/claims/:id/attachments
Content-Type: multipart/form-data

file=@police_report.pdf
documentType=police_report

GET /v1/claims/:id/attachments
# Returns: { data: Document[], total: number }