The problem
Income analysis is the largest manual time sink in underwriting. A processor must identify which documents are income-relevant, perform or commission calculations — especially for self-employed borrowers — then reconcile numbers across documents and AUS findings. This takes 20–60 minutes per file and produces inconsistent results depending on who reviews the loan.
The deeper problem: there is no audit trail. When an underwriter's income calculation differs from the processor's, there is no record of which documents were used, which fields were considered, or why the number changed. Compliance teams and investors cannot verify the calculation without repeating it.
| 20–60 min of manual income analysis per file Identifying income documents, running calculations, reconciling against AUS findings — all done by hand, per file, before the underwriter can issue a decision. |
Inconsistent results across teams Different processors apply different methodologies to the same borrower profile. The income figure that reaches decisioning depends on who touched the file — not on the underlying documents. |
No audit trail for income calculation Manual calculations leave no machine-readable record of which documents were used, which fields drove the result, or when the number was produced. Investor delivery requires reconstructing the logic after the fact. |
How it works
The Underwriting workflow uses the structured document file built during Loan Setup as its input. It checks which documents are income-eligible, triggers the Candor decision engine via API, and returns a verified income figure — with a full record of which files were used — directly to your LOS.
| Step 1 — Check income-eligible documents Call GET /loans/{id}/income-eligible-documents to see which classified documents in the loan file qualify for income analysis. This confirms prerequisites are met before triggering the calculation. |
Step 2 — Trigger income clarity calculation POST to /loans/{id}/income-clarity/trigger. Pass forceRecalculation: true to re-run after new documents arrive. The endpoint returns immediately with a taskId and status: "active" while Candor runs the analysis asynchronously. |
Step 3 — Poll for the income clarity result Poll GET /loans/{loanId}/income-clarity until calculatedAt is populated. The response includes the incomeData object, the files[] array showing which documents were used, and the full calculation timestamp. |
What you get
| Under 3 minutes to income analysis From trigger to verified income figure in the LOS — compared to 20–60 minutes of manual work. Candor handles W-2, pay stub, 1099, tax return, and self-employed income types without human intervention. |
87.5% avg W-2 extraction confidence Field-level confidence scores on every extracted income value. High-confidence fields process straight through; values below threshold are flagged for review rather than silently passed to the decision engine. |
Full audit trail of documents used Every income clarity result includes a files[] array — the exact documents used in the calculation, with file IDs, names, and types. History endpoint records every prior run. Investor-ready without manual reconstruction. |
Common questions
What income types does MOS support?
MOS identifies income-eligible documents via the /income-eligible-documents endpoint, which covers: pay stubs, W-2s, 1099s, tax returns (1040, Schedule C, Schedule E, K-1), bank statements for self-employed analysis, and employer letters. Candor's decision engine handles the income calculation for all of these types, including complex self-employed scenarios. The incomeData object in the response contains the calculated figures for each income stream identified.
Do I need to wait for Loan Setup to complete first?
Yes. The income clarity workflow requires classified and extracted documents to already exist in the MOS loan file. The /income-eligible-documents endpoint will return an empty list if no qualifying documents have reached EXTRACTED status yet. The recommended pattern is to trigger income clarity automatically after the Loan Setup extraction stage completes — you can detect this by filtering the analytics event stream for EXTRACTION_RESULT events from the relevant loan.
What if new pay stubs arrive after the first calculation?
Re-trigger the calculation by posting to /loans/{id}/income-clarity/trigger with forceRecalculation: true. MOS will re-evaluate the income-eligible document set, which now includes the new pay stubs, and produce a fresh incomeData result. The prior run is preserved in the history endpoint (GET /loans/{id}/income-clarity/history), so you retain a complete record of every calculation performed on the loan.
How do I get income data into Encompass?
Income clarity results flow back into Encompass via the same export pipeline established during Loan Setup. The incomeData fields are mapped to Encompass External Field Mapping configurations at the tenant level — no per-loan integration work is required once the mappings are set up. You can confirm delivery by checking the processing report at GET /reports/loan-processing for a populated docPushDateTime.
Key endpoints
Check which documents are income-eligible, trigger calculation, and retrieve decision-ready income data — in minutes.
/loans/{id}/income-eligible-documents
List documents eligible for income analysis
/loans/{id}/income-clarity/trigger
Trigger income clarity calculation
/loans/{loanId}/income-clarity
Retrieve completed income analysis results
/loans/{id}/income-clarity/history
All prior income clarity runs for the loan
Loan Setup & Data Quality
Turn uploads into clean, decision-ready files automatically.
Underwriting Automation
Decision-ready income and asset data without manual calculations.
Processing, Closing & Post-Close
Automate condition matching, closing review, and post-close validation.