Case lifecycle & statuses
Your system sees a deliberately simple four-state model — internal operational sub-states are mapped so we can evolve them without breaking you.
| External status | Meaning |
|---|---|
pending | Accepted, awaiting a field partner |
in_progress | Partner assigned / working / payment or verification in flight |
collected | Fully collected — terminal |
closed_unrecovered | Terminal without full recovery (incl. your recall, write-off) |
Visit outcomes
Delivered in visit.completed events:
| Outcome | Meaning |
|---|---|
collected / partial | Money collected (full / part) |
ptp | Promise-to-pay with a committed date (ptpDate) |
delivered_acknowledged | Payment notice delivered and acknowledged |
refused / not_available | Borrower refused / not found this visit |
wrong_address / shifted | Address problem — your cue to push a corrected address (just re-send the row) |
Reading state correctly
- The webhook stream is the narrative;
GET /cases/{loan}is the authoritative snapshot — when in doubt (e.g. a sequence gap), fetch it. - Payment events carry absolute values (
totalCollected,outstandingAfter) — never accumulate deltas yourself.