Loan Collections

Complete guide to managing loan collection cases — tracking delinquent accounts, logging collection activities, assigning agents, and closing resolved cases.

Navigation: Loan Accounts → Operations → Collections

Overview

The Collections module provides a structured workflow for managing overdue loan accounts. When a loan enters arrears, a Collection Case can be opened to track all recovery efforts until the account is brought current or written off.

Key Concepts

• Collection Case — A trackable record linked to a loan account, with status, priority, severity, and an assigned agent
• Collection Activity — Individual actions taken on a case (calls, visits, emails, SMS, legal notices)
• Collection Strategy — A planned approach for recovering the debt (contact frequency, assigned agent, priority level)
• Early Warning Flags — Automated flags raised by the arrears engine (HIGH_DPD, REPEATED_PARTIAL_PAYMENTS, REDUCED_CASHFLOWS)

Collection Cases

Creating a Case

1. Navigate to Loan Accounts → Operations → Collections
2. Click New Collection Case
3. Fill in:
   • Loan Account (lookup — search by account number)
   • Priority — LOW, MEDIUM, HIGH
   • Severity — LOW, MEDIUM, HIGH
   • Reason Code — PAST_DUE, BROKEN_PTP, SKIP_TRACE, LEGAL_ACTION, VOLUNTARY_DEFAULT, OTHER
   • Assigned Agent (optional — lookup by user name)
   • Opened Date (defaults to today)
4. Click Submit (or Add to Batch for multiple cases)

Case Statuses

Status	Description
OPEN	Active case — collection efforts ongoing
ON_HOLD	Temporarily paused (e.g. restructuring in progress)
CLOSED	Case resolved — account current, written off, or settled

Editing a Case

Use the row action Edit Case to change:

• Status (OPEN → ON_HOLD → CLOSED)
• Priority / Severity
• Reason code
• Assigned agent

Closing a Case

Use the row action Close Case to mark a case as resolved. This sets case_status = CLOSED and closed_date = today.

Filtering

Use the status and priority dropdowns above the table to filter cases:

• Status — OPEN, ON_HOLD, CLOSED
• Priority — LOW, MEDIUM, HIGH

Collection Activities

Logging an Activity

1. On a collection case row, click Log Activity
2. Fill in:
   • Activity Type — CALL, SMS, EMAIL, VISIT, FIELD_VISIT, LEGAL_NOTICE, NOTE, OTHER
   • Contact Method — Free text (e.g. "Mobile", "Office Phone")
   • Outcome — PTP, NO_ANSWER, LEFT_MESSAGE, REFUSED, PAID, PARTIAL_PAYMENT, DISPUTE, OTHER
   • Next Action Date — When to follow up
   • Notes — Free text description of the interaction
3. Click Submit

Viewing Activity History

Switch to the Activity Log tab to see all collection activities across all cases, sorted by date descending. The table shows:

• Activity type, date, contact method
• Outcome and notes
• Next action date
• Who performed the activity

Collection Strategies

Strategies define the planned approach for a specific loan account:

• Strategy Type — e.g. "SOFT_COLLECTION", "HARD_COLLECTION", "LEGAL"
• Priority Level — Numeric priority (1 = highest)
• Contact Frequency — e.g. "DAILY", "WEEKLY", "BIWEEKLY"
• Next Contact Date — When the next outreach should happen
• Assigned To — The responsible agent

Early Warning Flags

The system automatically generates early warning flags during the nightly arrears update (update_arrears_status). These are stored in the loan_early_warning_flag table and can trigger proactive collection actions.

Flag Types

Flag	Trigger Condition	Severity Logic
HIGH_DPD	Days in arrears ≥ 30	30+ = MEDIUM, 60+ = HIGH, 90+ = CRITICAL
REPEATED_PARTIAL_PAYMENTS	1+ partially paid past-due installments	1 = LOW, 2+ = MEDIUM, 4+ = HIGH
REDUCED_CASHFLOWS	Last 3 paid installments have avg payment ratio < 90%	< 75% = MEDIUM, < 50% = HIGH

Automated Flag Details

Each flag stores JSON details with context:

• HIGH_DPD: days_in_arrears, arrears_bucket, overdue_amount, next_due_date
• REPEATED_PARTIAL_PAYMENTS: total_partial_payments, latest_partial_date
• REDUCED_CASHFLOWS: installments_analysed, avg_payment_ratio, min_payment_ratio, trend (DECLINING/STABLE)

Permissions

Permission	Description
VIEW_COLLECTION_CASES	View collection cases and activities
CREATE_COLLECTION_CASE	Create new collection cases
UPDATE_COLLECTION_CASE	Edit existing cases (status, priority)
CREATE_COLLECTION_ACTIVITY	Log collection activities
CREATE_COLLECTION_STRATEGY	Create collection strategies

API Endpoints

Method	Path	Description
GET	/api/loans/collections/cases	List collection cases
POST	/api/loans/collections/cases/create	Create collection case
PUT	/api/loans/collections/cases/update	Update collection case
GET	/api/loans/collections/activities	List activities
POST	/api/loans/collections/activities/create	Log activity
POST	/api/loans/collections/strategies/create	Create strategy

Database Tables

Table	Purpose
collection_case	Main case tracking (status, priority)
collection_action_log	Legacy action log (per-case)
collection_activity_log	Activity log (per-loan-account)
collection_agent_assignment	Agent assignment history
collection_promise_to_pay	Promise-to-pay tracking
collection_strategy	Strategy definitions
loan_collection_routing	Hybrid group collection routing
loan_early_warning_flag	Automated early warning flags