Richy Koshy

Encompass
loan automationUnattended loan updates that never overwrite in-progress work.

PRMI’s loan updates ran through an RPA-driven batch tool, checked by hand on a status page that didn’t load reliably. I replaced it with direct Encompass REST API writes behind resource locks, so the job runs unattended and never overwrites in-progress work.

Role
Designed and built the automation and the custom SDK under it
Team
Sole engineer, from discovery and the BRD to UAT and release
Impact
Around 90% less manual effort; loan updates run unattended
Stack
  • Python
  • requests
  • ThreadPoolExecutor
  • OAuth2
  • Encompass REST API
Problem
Loan attribute updates went through a vendor’s Excel-driven batch tool, pushed by RPA, and a person checked every batch on a status page that didn’t load reliably. Nothing checked Encompass itself, so the job could never run unattended.
Approach

Write straight to Encompass through its REST API, loan by loan: take a resource lock, write the fields, read them back, release the lock.

If someone has the loan open, the lock is refused and the loan is retried in a later batch.

Each run records its input and every field’s value before and after the write.

Outcome
Around 90% less manual effort. Every loan ends with a status from Encompass itself, so the check after each batch is gone and the job runs unattended.
Before: RPA and a batch tool, checked by hand on its status page After: direct API writes, unattended updates Vendor status page, loads unreliably RPA pushes the updates Vendor batch tool Excel-driven Encompass loan origination system Manual verification a person, every batch free status: updated, with the values read back refused: the loan is in use later batch Update job Python, custom SDK Exclusive lock a resource lock on the loan Write, read back, release Field Writer, then Field Reader release in a finally block Encompass REST API Skip the loan status: locked, kept for retry Before: checked by hand on a status page updates Vendor status page, loads unreliably RPA pushes the updates Vendor batch tool Excel-driven Encompass loan origination system Manual verification a person, every batch After: unattended later batch free status: updated, with the values read back Update job Python, custom SDK Exclusive lock a resource lock on the loan Skip the loan if it’s in use: status locked Write and read back Field Writer, Field Reader then release the lock Encompass REST API

Before, a person checked every batch on the vendor’s status page, which didn’t load reliably, and nothing checked Encompass itself.

After, every loan gets its own status from Encompass: updated, with the values read back, or locked and retried in a later batch.

Before: a pipeline that couldn’t run unattended

Loan attribute updates ran through a vendor’s Excel-driven batch tool, pushed by RPA.

To confirm a batch, the team relied on the vendor’s status page. Nothing checked Encompass itself, and the status page didn’t load reliably.

The problem wasn’t the effort of that check. It was reliability: there was no dependable answer to whether each loan had updated, and a pipeline that needs a person after every run can’t run unattended.

Fixing that needed programmatic access to Encompass itself.

After: Encompass’s own answer replaces the manual check

The job now writes through the Encompass REST API directly, loan by loan, with the V3 Field Writer: POST /encompass/v3/loans/{loanId}/fieldWriter.

It updates fields by field ID, under the same business rules as the Update Loan API.

Then it reads the same fields back with the V3 Field Reader, for the record.

Each run also writes its input and every field’s value before and after the write to SQL Server, so any discrepancy traces back to a specific run.

Each loan ends with a status that comes from Encompass itself: updated, with the values read back, or locked, with the loan’s details kept so a later batch can retry it.

With that status for every loan, the manual check after every batch is gone, and the job runs unattended.

A lock protocol that never writes to a loan in use

An automated write must never land on a loan that someone is working in.

So every write in the SDK follows one pattern, lock → write → read-back → unlock, even one that takes under a second. It prevents lost updates on loans that several users work on:

  1. Take an exclusive resource lock on the loan. If someone has the loan open, the lock is refused: the loan is skipped and its status shows as locked, so nobody loses in-progress work.
  2. Write the fields with the Field Writer.
  3. Read them back with the Field Reader, for record keeping.
  4. Release the lock. The release sits in a finally block, so it runs even when the write fails.
  5. Retry the locked loans in a later batch.

While the lock is held, a user who opens the loan in Encompass desktop is told it is locked and can open it only read-only, so nobody else can change the loan mid-update.

The protocol was built when opening a loan in Encompass desktop always placed an exclusive lock on it.

Encompass release 26.1 later added an optional Shared Loan Lock, which lets an API integration update a loan while it is open in Encompass desktop.

The SDK underneath

The lock handling lives in a custom Python SDK wrapping the Encompass Cloud APIs. Encompass is the loan origination system at the heart of PRMI’s operations. I designed and built the SDK, and every one of my production automations runs on it.

  • OAuth2 auth with token caching.
  • Pipeline queries with pagination: pages fetched in parallel on a ThreadPoolExecutor, then a check that every record arrived.
  • Safe loan updates: the lock → write → read-back → unlock method above, so automations never overwrite in-progress work.
  • eFolder document and attachment CRUD, disclosure tracking, and borrower pair retrieval.
  • API rate limits: 429 retry with backoff.