# Loan servicing flows: design checklist and decision gate

Companion to [Amazon Connect for loan servicing](/blog/amazon-connect-loan-servicing-lending-2026/). Illustrative design material, not legal or compliance advice, and not run against a live LOS, LMS or Connect instance.

## Run the test

```bash
cd examples/architecture-blog-2026/connect-commerce-context/loan-servicing-flows
node --test
```

`decide.mjs` takes flat string inputs (`intent`, `matchCount`, `verified`, `syncAgeHours`) and returns `{ action, reason }` with `action` one of `disclose`, `verify_first`, `escalate`. It decides nothing about credit. Intent lists and the 24 hour staleness limit are placeholders for your own policy.

## Flow design checklist

- [ ] Servicing and origination are separate queues and separate entry points.
- [ ] The LOS/LMS lookup returns a flat map of strings and a `lookupStatus` the flow branches on.
- [ ] The lookup has a hard time budget below the flow block's 8 seconds and never throws.
- [ ] Two borrowers on one phone number returns `AMBIGUOUS`, never the first row.
- [ ] No loan data is spoken or sent before the caller passes your verification step.
- [ ] Every status reply carries an "as of" time from the source system.
- [ ] Status older than your freshness limit goes to a person.
- [ ] Payment arrangement, hardship, dispute, complaint and credit-decision intents never reach an AI agent.
- [ ] The AI agent has a knowledge base and `Complete`/`Escalate` only; no tool that changes a loan.
- [ ] Every outbound reminder checks consent, suppression and send window before it goes out.
- [ ] Opt-out replies (STOP) are honoured across SMS and logged against the borrower.
- [ ] A reminder is suppressed when the document has already arrived.
- [ ] Recordings, transcripts and contact records use a KMS key and retention you chose.
- [ ] Someone other than the builder has replayed the audit trail for one test loan end to end.

## Escalation triggers (route to a trained agent)

1. Caller mentions difficulty paying, job loss, illness, disaster or bereavement.
2. Caller asks to change, defer, reduce or waive any payment or term.
3. Caller disputes a balance, fee, payment posting or credit report entry.
4. Caller says "complaint", names a regulator, or mentions a lawyer.
5. Caller asks why an application was declined or what decision was made.
6. Caller suspects fraud or identity theft on the loan.
7. Phone matches zero or more than one borrower.
8. Verification fails twice.
9. Lookup returns `FALLBACK`, or the status is older than your freshness limit.
10. The AI agent cannot answer from approved content, or the guardrail blocks a reply.
11. Caller asks for a person, at any point.

## Document-chase Task template fields

Suggested fields for a Connect task template (one Task per missing item). Names are ours; adjust to your LOS.

| Field | Purpose |
| --- | --- |
| `loanRef` | Internal loan or application reference, never the borrower's national ID |
| `borrowerRef` | Internal borrower ID used to find the Customer Profile |
| `documentType` | Pick list from your LOS checklist, for example `payslip`, `bank_statement` |
| `requestedOn` | Date the item was first requested |
| `dueBy` | Date your process needs it by |
| `reminderCount` | Reminders sent so far |
| `lastReminderChannel` | `sms`, `email`, `voice` or `agent` |
| `lastReminderAt` | Timestamp of the last send |
| `consentOnFile` | `yes`/`no` for the channel last used |
| `status` | `open`, `received`, `waived_by_underwriter`, `closed_no_response` |
| `ownerQueue` | Queue that works the task |
| `caseId` | Connect Case that holds the full history |