> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nyumbazetu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Worklist and cases

> Work the ranked arrears queue and run a collection case from first contact to closure.

**Finance → Collections → Worklist → `/collections/worklist`** <sup>Beta</sup>

The worklist is the officer's day. It is one ranked grid of open cases with quick-view chips over
it; the case workspace is where each one is actually worked.

## The worklist grid

| Column             | Meaning                                                             |
| ------------------ | ------------------------------------------------------------------- |
| **Lease**          | The indebted lease. Opens the case.                                 |
| **Property**       | Branch / property the lease belongs to.                             |
| **Unit**           | The unit under the lease.                                           |
| **Band**           | Collectability band, A (most collectable) to E.                     |
| **Score**          | Collectability score 0–100.                                         |
| **Net Balance**    | Gross due less unallocated wallet money — the figure triggers use.  |
| **Gross Due**      | Contractual debt before wallet is netted.                           |
| **Wallet**         | Cash received but not yet allocated to an invoice.                  |
| **Days Past Due**  | Age of the oldest overdue item.                                     |
| **Status**         | Case status: open, on hold, closed.                                 |
| **Treatment**      | Active, promise, dispute, hardship, or legal flagged.               |
| **Contact**        | Not contacted, contacted, unreachable, or right party.              |
| **Assigned To**    | The officer who owns the case.                                      |
| **Pending Action** | The ladder step currently staged and waiting on a human.            |
| **Next Follow-up** | When the officer said they would come back to it.                   |
| **Priority**       | Ranking value — net balance weighted by how unlikely collection is. |
| **Opened**         | When the case entered collections.                                  |

### Quick views

Chips above the grid apply named filters. They are combinable, clearable, and written into the
URL, so a filtered queue can be bookmarked or shared.

| Chip                | Shows                                                                                         |
| ------------------- | --------------------------------------------------------------------------------------------- |
| **Follow-ups due**  | Cases whose follow-up date falls today or earlier, measured against the Nairobi calendar day. |
| **Pending actions** | Cases with a staged ladder action waiting for confirmation.                                   |
| **On hold**         | Cases paused by an officer, with a reason.                                                    |

Other operational queues are filters over the same grid rather than separate screens: my cases,
new, broken promises, not yet contacted, unreachable, high value, pending approval, and recently
paid (clearing).

<Tip>
  Sort by **Priority** and work top-down. Priority already blends size of debt with likelihood of
  recovery, so it beats sorting by balance alone.
</Tip>

## The case workspace

**`/collections/cases/{uuid}`**

The case header shows the tenant and unit, gross due **and** wallet, net balance, oldest due date,
aging bucket, band with a plain-language explanation of the score, the assignee, the treatment
state and the next action.

### Tabs

| Tab                | Contents                                                                                                                                              |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Overview**       | Case summary, staged action, score explanation, key dates.                                                                                            |
| **Debt breakdown** | The debt split by service type / invoice: original amount, outstanding, oldest due date, days past due. Read-only — it is a projection of the ledger. |
| **Timeline**       | One merged, chronological record: case events, officer interactions, communications sent, promises, and linked IoT enforcement events.                |
| **Promises**       | Commitments recorded against this case and how they were evaluated.                                                                                   |
| **Documents**      | Demand letters and other generated documents, with issue and delivery state.                                                                          |
| **Related**        | Other leases held by the same tenant, so you do not chase one and ignore two.                                                                         |

### Actions on a case

| Action                | What happens                                                                                                                         |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Confirm**           | Executes the staged ladder step — sends the message, issues the letter, applies the fee. Shows a rendered preview before the click.  |
| **Skip**              | Skips the staged step with a mandatory reason, recorded on the timeline.                                                             |
| **Assign**            | Hands the case to an officer. Assignment history is kept, not overwritten.                                                           |
| **Hold** / **Resume** | Pauses the ladder with a reason (for example, a payment arrangement being negotiated) and restarts it.                               |
| **Override score**    | Manually sets priority with a reason. Recorded and audited; the next engine refresh proposes but never silently reverts an override. |
| **Log interaction**   | Records a contact attempt — see below.                                                                                               |
| **Open legal matter** | Hands the case to the [legal register](/guides/collections/legal-register).                                                          |
| **Close case**        | Closes with a reason: resolved, written off, handed over, or cancelled. Write-off closure routes for approval.                       |

### Logging an interaction

Every contact attempt is recorded so any officer can pick the case up cold.

* **Channel** — call, SMS, WhatsApp, email, letter, visit, meeting, or note.
* **Direction** — inbound or outbound.
* **Contact person** and the number or address actually used.
* **Right party** — whether you actually reached the person responsible.
* **Outcome** — no answer, unreachable, wrong number, delivered, read, contacted, disputes,
  requests statement, promises, unable to pay, requests restructure, paid, third party, or follow
  up.
* **Follow-up date**, notes, and attachments.

Outcomes drive the workflow, they are not just a log:

* **promises** deep-links into recording a [Promise to Pay](/guides/collections/promise-to-pay) and
  pauses the ladder;
* **disputes** flips the treatment state and takes the disputed amount out of ladder triggers;
* **follow up** puts the case in your *follow-ups due* queue on that date.

<Note>
  Messages the engine sends automatically log an interaction too, so the timeline is complete
  without anyone entering the same thing twice.
</Note>

## Case lifecycle

```
open → active ⇄ on hold → clearing → closed (resolved | written off | handed over | cancelled)
```

* An **active promise** pauses ladder steps that are marked to pause on promise.
* A **broken promise** resumes the ladder, raises severity and stages a follow-up task.
* A payment that drops net balance below the exit threshold moves the case to **clearing**; it
  closes after a confirmation window, with hysteresis so a case does not flap open and closed on
  small movements.
* **Reopening** creates a *new* case linked to the previous one, rather than resurrecting the old
  one — so per-cycle metrics stay honest.

## Approvals and audit

High-impact actions route to the [approvals inbox](/guides/approvals) rather than firing directly:
issuing a demand letter, handover, fee waiver, hardship restructure, and closing a case with a
write-off. Approval or rejection lands on the case timeline with the decider and their reason.

Every console mutation is audited. Hold, skip and score override require a reason before they will
save.

## Working a case: recommended sequence

<Steps>
  <Step title="Read the debt breakdown first">
    Know whether you are chasing rent, utilities, or a penalty — the conversation differs, and so
    does what the tenant will accept.
  </Step>

  <Step title="Check the wallet figure">
    If there is unallocated cash, the fix may be an [allocation](/guides/allocations), not a
    collection call.
  </Step>

  <Step title="Check Related">
    A tenant with three leases should get one conversation, not three.
  </Step>

  <Step title="Contact, then log the interaction immediately">
    The outcome you pick is what schedules your next step.
  </Step>

  <Step title="Record any commitment as a promise">
    A promise in the notes field is invisible to the engine; a recorded promise pauses the ladder
    and is evaluated automatically.
  </Step>

  <Step title="Confirm or skip the staged action">
    Leave nothing staged and unattended — a stale staged action is the most common reason a case
    stalls.
  </Step>
</Steps>