Case model & lifecycle

A case is one borrower matter carried to an outcome. It stays open until the workforce has closed it — an AI agent moving it forward, or a named person where policy reserves the decision — and it holds everything that outcome will have to be defended with.

That is why it holds more than the current assignee’s task: the reason the work exists, the facts and policy used, what happened, and what remains.

This page is the model. How a case moves is the engine that walks one from its opening signal to its outcome, and Who gets the work is how the work a case needs reaches a named person.

Seven records, and each one owns its own lifecycle

Record	Answers	Example
Case	Why does this matter exist, and when is it resolved?	Harbor is 22 days past due.
Task	Who should do the next unit of work?	The voice agent checks contact eligibility and calls.
Case effect	Which operation did the workflow commit to doing itself?	Cancel autopay on loan 7204.
Interaction	What communication occurred?	Outbound call reached Maya.
Decision	What did policy allow or require?	Voice allowed; three counted calls remain.
Action request	Which approval-required, deferred, manual, external, or unavailable change was opened?	Approve an out-of-guardrail promise.
Evidence	Which facts, versions, and approvals support it?	Delinquency snapshot, rule trace, call recording.

Closing a task never silently closes its case. Each record has its own lifecycle and links through stable IDs — and conflating any two of them hides work, which is the failure the separation exists to prevent.

Case lifecycle

LifecycleServicing case

INTAKEclassify and gather minimum facts

›

OPENworkflow and SLA active

›

RESOLVEDclosure criteria satisfied

›

CLOSEDoutcome finalized

OPEN→WAITING_ON_BORROWERspecific response or evidence requested

OPEN→WAITING_ON_LENDERclient decision or artifact required

OPEN→WAITING_ON_SYSTEMacknowledgement or fresh fact pending

OPEN→SUPERVISOR_REVIEWapproval or exception required

OPEN→COMPLIANCE_REVIEWrule outcome or legal scope unresolved

OPEN→BLOCKEDrequired fact or capability unavailable

CLOSED→REOPENEDnew qualifying event with reason

INTAKE→DUPLICATElinked to surviving case

SNOOZED, ESCALATED, and FAILED_ACTION_REVIEW are also available where a workflow needs them. Transition eligibility comes from the case’s pinned workflow version, and arbitrary status updates are rejected.

Waiting and review states are not parking lots. Each one requires a named dependency, an owner, a deadline, and the condition that will wake it — so a case that is waiting can always answer who it is waiting on and what will end the wait.

Opening a case

The implemented create contract uses numeric servicing IDs, string references to authoritative customer/loan records, and exact source deduplication:

POST /v1/servicing/cases
Idempotency-Key: harbor-delinquency-2027-05-01

{
  "customerRef": "412",
  "caseTypeCode": "COLLECTIONS",
  "reasonCode": "DELINQUENCY_SIGNAL",
  "priority": "HIGH",
  "loanRefs": ["7204"],
  "sourceType": "LMS_EVENT",
  "sourceRef": "signal_2027-05-01_HBR"
}

The response separates caseId: 1001 from a lasting external reference such as externalCaseRef: "LE-CASE-1001" and reports whether the exact source was deduplicated.

Case types and the catalog

LendEasy exposes a broad catalog while letting each tenant enable, rename, route, and configure its workflows.

Domain	Case types
Account service	General support, account correction, statement inquiry, payoff inquiry, document request
Payments	Payment issue, returned payment, card dispute, external payment review, credit balance, refund
Autopay	Enrollment support, authorization dispute, repeated failure, instrument replacement
Collections	Early delinquency, late-stage collections, promise follow-up, hardship, disaster assistance
Legal and compliance	Bankruptcy, cease communications, debt dispute, debt validation, servicemember protection, deceased customer
Identity and authority	Identity theft, suspected fraud, authorized-party review, verification failure
Complaints and privacy	Complaint, privacy request, data correction, communication preference dispute
Merchant servicing	Sales-report exception, remittance recovery, near-breach review, contract breach, merchant support
Operations	Reconciliation drift, failed action, duplicate record, document classification review

Case types do more than label work. Each pins its stages, fact requirements, restriction rules, tasks, allowed actions, approvals, outcome codes, and closure criteria. A bankruptcy case therefore cannot accidentally use a collections workflow just because both concern a past-due loan.

The table above is the catalog LendEasy ships. What a given tenant has actually enabled is read from the API, not assumed: GET /v1/servicing/case-types returns the presentation-safe enabled types with their reasons, routing defaults, and current field definitions — everything an intake form needs to build itself:

{
  "items": [
    {
      "caseTypeCode": "COLLECTIONS",
      "displayName": "Collections",
      "defaultPriority": "NORMAL",
      "serviceLevelMinutes": 1440,
      "defaultQueueCode": "COLLECTIONS",
      "reasons": [
        { "reasonCode": "DELINQUENCY_SIGNAL", "displayName": "Delinquency signal", "handlingMode": "WORKFLOW" }
      ],
      "fieldDefinitions": { "sections": [] }
    }
  ]
}

Drive caseTypeCode, reasonCode, and the configured fields on create from this read. A hard-coded client list drifts the moment a tenant enables a type or retires a reason. The definitions themselves are administered separately — see Servicing configuration.

A case read carries the shape of its flow

So a client never has to guess which stage comes next, or hard-code a sequence that configuration can change. Workflow edits create a new version and active cases stay on the one they started on — see how a case moves for why that is a feature rather than a limitation.

{
  "workflow": {
    "workflowKey": "COLLECTIONS_STANDARD",
    "version": 2,
    "status": "ACTIVE",
    "currentStageCode": "MONITOR_PROMISE",
    "stages": [
      {
        "stageKey": "INTAKE",
        "displayName": "Intake and route",
        "state": "COMPLETED",
        "enteredAt": "2027-05-04T16:11:02Z",
        "exitedAt": "2027-05-04T18:03:47Z",
        "tasks": [{ "taskId": 2001, "taskTypeCode": "COLLECTIONS_OUTREACH", "status": "COMPLETED", "outcomeCode": "CUSTOMER_REACHED" }]
      },
      { "stageKey": "MONITOR_PROMISE", "displayName": "Monitor the promise", "state": "CURRENT", "enteredAt": "2027-05-05T18:30:00Z", "tasks": [] }
    ]
  },
  "workSummary": {
    "taskCounts": { "COMPLETED": 1, "ACCEPTED": 1 },
    "openTaskCount": 1,
    "nextAction": { "taskId": 2002, "taskTypeCode": "COLLECTIONS_OUTREACH", "queueCode": "COLLECTIONS", "status": "ACCEPTED", "priority": "HIGH" }
  },
  "availableTransitions": ["SNOOZED", "WAITING_ON_BORROWER"]
}

A snapshot proves what was decided, never what is true now

The case header shows current borrower, loan, delinquency, contact, promise, restriction, document, and interaction facts. Material decisions also store a point-in-time snapshot.

For a collection call, the action snapshot includes:

• amount and days past due;
• last posted payment and covering in-flight amount;
• active promise and contact-suppression facts;
• verified contact detail, consent, timezone, and convenient-time facts;
• remaining contact budget by debt and channel;
• bankruptcy, cease, dispute, fraud, and other restrictions; and
• source, asOf, freshness status, and policy versions.

That snapshot answers “why was this allowed then?” without implying it remains allowed now.

Updating a case

PUT /v1/servicing/cases/{caseId} updates routing-safe properties — priority, summary, and the configured fields — and always requires a reason:

{
  "priority": "HIGH",
  "summary": "Customer supplied the requested servicing details.",
  "fields": {
    "contact_outcome": "CUSTOMER_REACHED",
    "follow_up_date": "2027-05-07"
  },
  "reason": "Recorded the result of the customer call."
}

The command receipt reports exactly what moved, including the fieldKeys it accepted:

{
  "caseId": 1001,
  "resourceId": 1001,
  "changes": { "priority": "HIGH", "fieldKeys": ["contact_outcome", "follow_up_date"] }
}

Workflow state is not editable through this route. status changes go through the transition, close, and reopen commands below, so a client cannot reach a state the pinned workflow does not allow by writing a field.

Closing is not a transition

Three separately authorized commands move a case through its lifecycle:

Command	Requires	Permission
POST /v1/servicing/cases/{caseId}/transitions	targetStatus, reason (plus a resumeDate for waiting states)	UPDATE_SERVICING_CASE
POST /v1/servicing/cases/{caseId}/close	outcomeCode, closureReason	CLOSE_SERVICING_CASE
POST /v1/servicing/cases/{caseId}/reopen	reason (optionally priority, ownerQueueCode)	REOPEN_SERVICING_CASE

The transition command applies one transition allowed by the case state machine and the pinned workflow — read availableTransitions from the workspace rather than guessing:

POST /v1/servicing/cases/1001/transitions

{
  "targetStatus": "SNOOZED",
  "reason": "Customer promised to pay on the agreed date.",
  "resumeDate": "2026-08-01"
}

Close and reopen are not transitions. Separating them keeps closure authority distinct from ordinary workflow movement, so a worker who can move a case to a waiting state cannot finalize it. See Case controls & escalation for what each control may and may not do.

A duplicate is linked, never deleted

Cases link rather than merge. POST /v1/servicing/cases/{caseId}/relationships creates a reversible RELATED or POSSIBLE_DUPLICATE link, and the relationship’s own subresources confirm, dismiss, or replace it. Confirming a possible duplicate names the selected duplicateCaseId; the other case stays primary and both histories remain intact. Duplicate detection & linking covers the signals and review model.

For a portfolio-wide event, the structural container is a supercase with linked customer subcases — see Mass cases & subcases.

Notes are revised, never rewritten

Notes have a kind: normal, pinned, sensitive, legal, and internal review. Access policy follows note type, and exports redact fields the caller cannot view. A note cannot serve as the only record of a consent revocation, bankruptcy filing, promise, approval, or loan action; structured records own those facts.

Case notes are revisioned rather than edited, and they are discoverable by case, customer, or loan. Case notes documents the create, revise, link, archive, and redact contracts.

Resolving and closing

Resolving requires an outcome plus satisfied closure criteria. Closing finalizes reporting fields and cancels or completes remaining work under policy. The close command enforces this: it succeeds only after required fields, tasks, action requests, case effects, and the workflow’s own closure criteria are satisfied.

Ownership does not veto a close — every judgement the closure depended on is already recorded against whoever made it. How a case moves sets out why there is deliberately no “finished, but sitting open because it has an owner” state.

POST /v1/servicing/cases/1001/close

{
  "outcomeCode": "PROMISE_KEPT",
  "closureReason": "Customer cured delinquency and no follow-up remains."
}

Examples:

• A collections case resolves promise_kept only after authoritative payment facts satisfy the commitment.
• A payment-return case resolves recovered only after the replacement payment posts.
• A bankruptcy case does not close merely because a task was completed; the workflow requires the appropriate stay/discharge outcome.
• A duplicate case closes duplicate with a surviving case link and preserves its source event.

Reopening creates a new lifecycle segment with trigger, actor, and reason. It never deletes the prior resolution. POST /v1/servicing/cases/{caseId}/reopen re-routes the case under its configured workflow rules — the caller supplies the reason and may suggest priority and ownerQueueCode, but cannot assign the reopened matter to a chosen worker.