Review a loan's documents for a prepayment penalty

Whether a loan carries a prepayment penalty (PPP) can be stated in any of half a dozen documents: the note, a note addendum, a rider to the deed of trust, a separate disclosure, the Closing Disclosure. Processors check them one by one. In this walkthrough you have QBO pick the right documents for each loan, send them to AI with the same checklist your processors use, and save the findings as a memo on the loan for a processor to confirm.

The pattern is general: choose the right documents, give AI your checklist, save the answer on the record. Swap the checklist and the document list to review appraisals, closing packages, title commitments, or claim files the same way.

Who it’s for

Power users in mortgage servicing or lending operations who configure templates and workflows. Step 4 adds a SQL filter, which needs someone comfortable with SQL.

Prerequisites

• An AI agent that can read PDFs, configured for your installation. This walkthrough calls it DocumentReview. See AI agents.
• Loan documents already classified into document templates, and ideally scored. See Classify a document and extract its data with AI.
• Permission to edit message templates, labels, workflow templates, and the Loan module’s configuration.

Building blocks used

• AI: the AI review method
• Messaging: a message template holds the instructions; the review is saved as a message
• Document Management and Scoring: document templates and confidence pick the right documents
• Contacts & Organizations: a label marks the relevant document templates
• Workflow and Worklists: run reviews at scale and queue them for confirmation

How it works

The AI review method works on any record. Called on a loan, it:

1. Loads a message template; the template’s body becomes the model’s instructions.
2. Sends a summary of the loan, plus each document you list in AttachmentIDs. Documents go to the model as original files, so layout and tables are preserved.
3. Asks for a structured answer: a subject, a Markdown memo, and optionally a priority, a status, and a message type.
4. Saves that answer as a message on the loan.

Documents are fetched under the calling user’s security, so the review can only read documents that user can reach.

Steps

1. Write the review instructions as a message template

Create a message template named PPP Review. Its body is the instructions. Start with the role and goal, then give the checklist your processors already follow:

You are a residential mortgage analyst. Review the documents provided for this loan and determine whether the loan has a prepayment penalty. Work through the documents in this order:

1. Note: review the prepayment section for whether a penalty is allowed and its terms.
2. Note addenda: look for a prepayment addendum and, if present, its terms.
3. Deed of trust: check the riders section for a prepayment rider; if one is listed, find the rider and its terms.
4. Prepayment penalty disclosure separate from the note and deed of trust: if present, its terms.
5. Closing Disclosure: the prepayment penalty box on page 1 gives the penalty period and maximum amount. Convert a dollar maximum to a percentage of the loan amount.
6. To confirm, check the first payment letter (prepayment yes/no box), the data entry sheet (prepayment yes/no, months, and percentage), and, if there’s no Closing Disclosure or Loan Estimate, the final TILA disclosure or HUD-1.

Report the penalty period in months, the penalty terms, and which document each finding came from. Set Status to exactly one of: PPP Found, No PPP, Inconclusive. Return null for MessageType.

Two lines at the end matter:

• Status comes back as a field on the saved message, so a worklist can sort loans by the outcome without anyone reading the memo first.
• MessageType: if the model returns a message type, QBO uses it instead of the one you pass. Asking for null keeps your MessageType parameter (step 5) in charge.

2. Label the document templates that matter

Not every document on a loan says anything about prepayment. Sending them all costs tokens and gives the model more to get wrong.

Create a label named PPP Eligible whose members are document templates, and add the templates the checklist names: Note, Note Addendum, Deed of Trust, Prepayment Rider, Prepayment Penalty Disclosure, Closing Disclosure, First Payment Letter, Data Entry Sheet, TILA Disclosure, HUD-1. Adjust the list to the templates your installation actually uses.

3. Pick the best copy of each document

A loan may have several copies of the same document: a draft and a signed version, or the same note uploaded twice. QBO’s document integration includes a shared statement, DocumentListRanked, that solves this. For each record, it:

1. Keeps only documents whose template is a member of the label you name in Collection.
2. Ranks copies of each template by score confidence, then by most recently updated.
3. Returns the top Versions copies of each template (default 1) as a comma-separated AttachmentIDs column, one row per record.

Try it on the loans you can see:

GET /api/loan/documentlistranked?Collection=PPP Eligible&Versions=1

Loans with no eligible documents return no row, so they’re never sent to AI. Running the statement requires the DocumentListRanked permission.

Note

Scoring documents before the review pays off twice: confidence picks the cleanest copy here, and the model reads fewer, better documents.

4. Decide which loans to review

Add a filter named IsPPPEligible to the Loan module’s configuration, with IsPPPEligible as its parameter so passing IsPPPEligible=true adds it to the statement’s {Where.Basic} clause. For example:

NOT EXISTS (
    SELECT 1 FROM Message
    WHERE Message.Object = 'Loan'
      AND Message.ObjectID = Loan.LoanID
      AND Message.MessageType = 'PPP Review'
)
AND Loan.Status IN ('Default', 'Foreclosure')

The first condition skips loans that already have a review, so rerunning the step never pays for the same review twice. Replace the status condition with your own business rules.

5. Run the review from a workflow

Try one loan first:

GET /api/loan/aireview?ID=1001&AgentName=DocumentReview&Template=PPP Review&MessageType=PPP Review&AttachmentIDs=2207,2210,2214

Then, in a workflow template, choose New > Add an Advanced Step. An advanced step calls its action once for each row its data source returns:

Step setting	Value
Data Source	Operation: module Loan, operation DocumentListRanked, parameters Collection=PPP Eligible&Versions=1&IsPPPEligible=true
Action	Module Loan, operation AiReview, parameters ID={LoanID}&AgentName=DocumentReview&Template=PPP Review&MessageType=PPP Review&AttachmentIDs={AttachmentIDs}
Queue	A dedicated queue, so slow AI calls don’t hold up other workflow steps

Each row supplies its own LoanID and AttachmentIDs, so every eligible loan is reviewed with its own best documents.

Tip

To see what the reviews cost, add Chat_LedgerID with a ledger’s ID and QBO posts the tokens each call uses to that ledger. See token cost tracking. For a large backlog, the queued form /api/loan/queue/aireview and provider batch jobs spread the work out.

6. Confirm the findings

Build a worklist of loans with a PPP Review message, grouped by its status. Processors open each loan, read the memo, check the cited documents, and set up the penalty terms or record that there’s none. Start with Inconclusive loans: those are where a person adds the most.

The result

Every eligible loan gets a PPP Review message on its record. An example (illustrative, not real data):

Subject: Prepayment penalty found: 36 months

Status: PPP Found

The loan is a business-purpose loan for an investment property, per the signed business purpose affidavit. A Prepayment Rider is attached to the deed of trust and sets a 36-month penalty period. The final TILA disclosure confirms a prepayment penalty applies. No separate prepayment disclosure or Closing Disclosure was provided.

Processors confirm a structured finding that cites its sources, instead of searching every document on every loan, and each loan is reviewed once.

Next steps

• Reuse the pattern for appraisal reviews, closing package checks, or title review by changing the message template and the label.
• Capture the penalty terms as typed values with an AI score template on the rider or note, so they feed reports and rules directly.
• Set loan fields from the review with the AI update operation once you trust the results.