Case notes

A case note is the servicing plane’s operational commentary — what a worker observed, agreed, or intends to do next. It is revisioned rather than editable, link-aware rather than free-floating, and it is never the authoritative record of a regulated fact.

Create on a case

A note is always created against its owning case. The case and customer links are derived; only loan links are selectable:

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": ["456"],
    "sensitive": true,
    "pinned": true,
    "flagged": false
  }'

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

body is the only required field. Three flags shape handling rather than content:

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 envelope 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.

Discovery by case, customer, and loan

All three accept the same exact filters — status, sensitive, pinned, flagged, createdFrom, createdTo — plus limit/offset paging. There is no keyword parameter: notes are found through structured filters and their links, not full-text search over operational commentary.

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.

Replace loan links

Loan links are corrected without touching content or revision history:

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

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

The replacement is atomic — the supplied list becomes the complete set of loan links. Sending [] removes them all while the derived case and customer links remain.

Archive and redact

Two terminal commands exist and they 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. Neither deletes the note.

Permissions

Reading a sensitive body requires separate authorization in addition to 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.