Notes

A note is human context that does not fit a typed field: what an operator observed, why a manual choice was made, or what the next worker should know. It is not a fact source for calculations and it never contacts the customer.

Create deliberately

curl -X POST "$BASE/v1/loans/7204/notes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LendEasy-Tenant: demo-lender" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: note-harbor-payoff-delivery" \
  -d '{
    "body": "Maya requested email delivery for the payoff figure.",
    "sensitive": false,
    "pinned": false
  }'

{ "resourceId": 802 }

Requires CREATE_LMS_NOTE; the same route family exists at POST /v1/customers/{customerId}/notes. The actor and time come from authenticated execution context, not caller-supplied prose. A body can hold up to 20,000 characters, and marking a note sensitive requires the sensitive read permission—decide before submission, because restricted legal, medical, dispute, or vulnerability context must not spend even a short interval as ordinary text.

Markers first, bodies one at a time

GET /v1/customers/{customerId}/notes and GET /v1/loans/{loanId}/notes return markers only—pinned first, newest first:

{
  "items": [{
    "noteId": 802,
    "noteRef": "note_9c1d3e5f7a9b1c3d5e7f",
    "status": "ACTIVE",
    "sensitive": false,
    "pinned": false,
    "flagged": false,
    "redactionState": "NONE"
  }]
}

Bodies are read one note at a time via GET /v1/notes/{noteId} (READ_LMS_NOTE). A sensitive body additionally requires the sensitive read permission, so a marker list never leaks restricted text to a caller who can only see that a note exists.

There is no category field; use links and flags, not taxonomy, to organize notes.

Revise; never rewrite

If Maya actually requested secure message rather than email, revise the note. PUT /v1/notes/{noteId} (UPDATE_LMS_NOTE) appends a new immutable revision with an optional changeReason; the original revision is never edited or deleted.

curl -X PUT "$BASE/v1/notes/802" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LendEasy-Tenant: demo-lender" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: revise-note-802-channel" \
  -d '{
    "body": "Maya requested secure-message delivery for the payoff figure.",
    "changeReason": "Channel corrected."
  }'

GET /v1/notes/{noteId} always returns the current revision’s body; GET /v1/notes/{noteId}/history returns revision metadata newest first—revision number, type, and reasons—never the bodies themselves. This preserves what a worker could see at any historical point.

Links, archive, and redaction

• POST /v1/notes/{noteId}/links attaches the note to another customer or loan ({ "targetType": "CUSTOMER", "targetRef": "412" }); POST /v1/notes/{noteId}/links/{linkId}/remove deactivates one link while retaining the row and its removal.
• POST /v1/notes/{noteId}/archive (ARCHIVE_LMS_NOTE) takes no body, is idempotent, and retains all revisions.
• POST /v1/notes/{noteId}/redact (REDACT_LMS_NOTE) takes a required redactionReason, appends a redaction revision, and permanently replaces the content: every read thereafter returns a placeholder, redacted notes cannot be revised, and redaction cannot be undone.

What notes cannot do

• A note cannot grant consent, verify identity, change a balance, or apply a restriction.
• A note saying “payment received” is not a payment fact.
• A note saying “do not call” should trigger the cease-contact workflow; it is not the enforcement control.
• A note saying “approved” cannot replace a structured approval record.
• A note body is never returned in a list; sensitive bodies require the additional sensitive read permission.

Use Forms for schema-validated intake, Interactions for customer communications, and Restrictions for enforceable stops.