Mass cases & subcases

A disaster, provider incident, statement defect, or policy remediation can affect thousands of customers. A mass case manages the common cause; one subcase preserves each customer’s facts, controls, actions, and outcome.

The implemented supercase

A supercase is a container for a portfolio event and one shared subcase type. It carries no bulk-action authority of its own:

curl -X POST "$BASE/v1/servicing/supercases" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LendEasy-Tenant: demo-lender" \
  -H "Content-Type: application/json" \
  -d '{
    "supercaseType": "FEMA",
    "displayName": "July wildfire assistance",
    "subcaseCaseTypeCode": "HARDSHIP",
    "createdSignalRef": "fema-event-2027-05",
    "sensitive": false
  }'

{
  "supercaseId": 8001,
  "externalSupercaseRef": "LE-SUPERCASE-8001",
  "status": "ACTIVE",
  "resourceId": 8001
}

supercaseType is a closed set — GENERIC, FEMA, or REMEDIATION — and subcaseCaseTypeCode must name an enabled case type. Fixing one subcase type per supercase is what stops a disaster container from quietly accumulating unrelated regulated matters.

Each affected customer is added as an ordinary case that is structurally linked to the container:

POST /v1/servicing/supercases/8001/subcases

{
  "customerRef": "123",
  "reasonCode": "DISASTER_ASSISTANCE",
  "priority": "HIGH",
  "loanRefs": ["456"],
  "ownerQueueCode": "HARDSHIP"
}

The response is a normal case creation result — caseId, externalCaseRef, status, and deduplicated — because that is exactly what it is. A subcase follows the full case model: its own workflow, tasks, compliance decisions, evidence, and closure criteria.

Reading the container

GET /v1/servicing/supercases lists bounded structural summaries, filterable by supercaseType, status, caseTypeCode, sensitive, and creation window. GET /v1/servicing/supercases/{supercaseId} adds status counts and a canonical link to the subcases themselves:

{
  "supercaseId": 8001,
  "supercaseType": "FEMA",
  "displayName": "July wildfire assistance",
  "status": "ACTIVE",
  "subcaseCaseTypeCode": "HARDSHIP",
  "subcaseCount": 12,
  "subcaseStatusCounts": { "OPEN": 10, "CLOSED": 2 },
  "subcasesHref": "/v1/servicing/cases?supercaseId=8001"
}

Detailed subcases are read through the case collection at subcasesHref, not through the supercase. The container reports structure and counts; the cases remain the system of record for the work. All four routes take MANAGE_SERVICING_SUPERCASE, which grants container management — never a bypass of the permissions each subcase’s own operations require.

Hierarchy

mass case: provider outage on 2027-08-04
  ├─ population version 1: 18,420 candidate loans
  ├─ subcase Maya / Harbor
  ├─ subcase customer B / BNPL
  ├─ subcase merchant C / advance
  └─ aggregate work, progress, exceptions, and evidence manifest

The parent cannot satisfy a subcase’s individual deadline or compliance requirement. Each subcase has exactly one managing mass case and otherwise follows the normal case model.

Versioned population

Population definitions pin source, query/criteria, as-of time, included IDs, exclusions, checksum, creator, and version. If the affected cohort expands, create version 2 and record added/removed reasons; do not mutate version 1.

Fan-out model

One proposed mass action becomes N individual action intents:

template + population version
        ↓ fan out
customer fact resolution
        ↓
individual compliance/eligibility decision
        ↓
idempotent execution or explicit skip
        ↓
individual acknowledgement and reconciliation

One blocked customer does not fail the entire population, and one allowed customer does not authorize another.

Safe rollout

Run a dry preview with outcome counts and amount totals, require approval of the frozen population and template, execute a small canary, compare observed outcomes, then expand in bounded batches. A kill switch stops new dispatch but does not pretend already accepted provider or financial effects were recalled.

Aggregate status

The mass case reports counts by proposed, eligible, approval-required, blocked, missing-facts, submitted, completed, failed, drifted, and skipped. Counts reconcile to the frozen population version, and amount-based actions reconcile amounts separately.

Common failures

• a customer pays after population selection;
• a new cease or bankruptcy control appears before contact;
• a document or address changes before rendering;
• the core is stale for one cohort;
• provider acceptance is partial;
• an idempotent retry returns prior success;
• a population criterion accidentally crosses legal entities or products.

Each becomes an individual outcome or controlled incident, never a silent bulk override.