Case notes

A case note carries the human context no structured field can hold — what the borrower sounded like, why the team chose one option over another — kept as revisions that can be corrected, linked and, when free text goes wrong, redacted to the last word. It is the one place in servicing where anyone can write anything, which is exactly why it cannot be trusted with a regulated fact: notes are revised, archived, and sometimes redacted out of view for good. So a case note carries operational commentary — what a worker observed, agreed, or intends to do next — revisioned rather than editable, and bound to a case rather than floating free.

The case and customer links are derived

A note is always created against its owning case, and only loan links are selectable. Deriving the other two removes the commonest way commentary goes missing: a note filed under the wrong customer is a note nobody finds again, and a note with no case is a sentence with no matter attached to it.

curl -X POST "$BASE/v1/servicing/cases/1001/notes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LendEasy-Tenant: demo-lender" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Customer will provide the missing filing page through secure upload.",
    "loanRefs": ["7204"],
    "sensitive": true,
    "pinned": true,
    "flagged": false
  }'

{
  "noteId": 7201,
  "revision": 1,
  "status": "ACTIVE",
  "links": [
    { "targetType": "CASE", "targetRef": "1001" },
    { "targetType": "CUSTOMER", "targetRef": "412" },
    { "targetType": "LOAN", "targetRef": "7204" }
  ],
  "resourceId": 7201
}

Revisions, not edits

PUT /v1/servicing/notes/{noteId} appends a new revision and preserves note identity and the immutable revision history:

{
  "body": "Customer supplied the final filing page through secure upload.",
  "sensitive": true,
  "pinned": false,
  "flagged": false,
  "changeReason": "Recorded verified receipt."
}

{
  "resourceId": 7201,
  "changes": { "revision": 2, "fieldKeys": ["body", "pinned"] }
}

The command receipt reports the new revision and exactly which fields changed. GET /v1/servicing/notes/{noteId} returns the current authorized revision with its creator’s display name and actor type — HUMAN or an AI worker — so authorship is never ambiguous in a mixed workforce.

Three scopes, and no keyword search

All three accept the same exact filters — status, sensitive, pinned, flagged, createdFrom, createdTo — plus limit/offset paging. There is deliberately no keyword parameter. Free-text search across a portfolio’s operational commentary is a way to assemble facts about a borrower that no single permission ever granted, so notes are reached through their links and their structured filters instead.

The loan view is deliberately narrower than the customer view. A note reaches a loan only through an explicit link, so a general customer note does not silently attach itself to every loan the customer holds.

Replacing loan links

Loan links are corrected without touching content or revision history:

PUT /v1/servicing/notes/7201/loan-links

{
  "loanRefs": ["7204"],
  "reason": "The note applies only to the selected loan."
}

The replacement is all-or-nothing — the supplied list becomes the complete set of loan links, so a correction never leaves a half-applied state where the note is attached to both the right loan and the wrong one. Sending [] removes them all while the derived case and customer links remain.

Two terminal commands, neither one a delete

Archive and redact are not interchangeable:

• POST /v1/servicing/notes/{noteId}/archive moves the note to ARCHIVED under retention rules. Identity, revisions, and links survive; the note simply stops being current operational content.
• POST /v1/servicing/notes/{noteId}/redact appends a permanent redaction-marker revision. The content is removed from view for good, while audit and link history are retained so the record’s existence and its causal edges remain provable.

Both require a reason, and both are appends. A note that could be deleted outright would take its causal edges with it, and the decision that cited it would then rest on a record the file no longer shows.

Five permissions, and sensitive needs another

Reading a sensitive body requires separate authorization beyond READ_SERVICING_NOTE. On the customer-scope list, an unauthorized caller still sees the note’s metadata with a masked body rather than a silently shortened list — a list that quietly drops rows tells a worker the case has been quiet when in fact it has not, and they act on a history with holes in it.