Setting up Income Clarity

What Income Clarity does

Income Clarity is MOS's income analysis layer, built in partnership with Candor's decision engine. It takes the classified and extracted documents already in a loan file and produces a verified income figure without any manual calculation. The result includes which documents were used, when the calculation ran, and the full income data output from Candor.

The document types that feed Income Clarity are the same ones the Loan Setup pipeline classifies and extracts: W-2 wage statements, pay stubs, 1099s, tax returns (1040, Schedule C, Schedule E, and K-1), bank statements used for self-employed income analysis, and employer letters. All of these must already exist in the MOS loan file as extracted documents before you can trigger a calculation.

Candor handles every income type, including complex self-employed scenarios. The result flows back into Encompass via the same export pipeline established during Loan Setup. No separate LOS integration is required once the standard mappings are configured at the tenant level.

Prerequisites

Loan Setup must complete before Income Clarity can run. Specifically, the income-relevant documents in the loan file must reach EXTRACTED status in the Loan Setup pipeline. If you trigger Income Clarity before extraction is complete, the /income-eligible-documents endpoint will return an empty list and the trigger call will have nothing to analyze.

The recommended pattern is to monitor the Loan Setup pipeline via GET /loans/{loanId}/documents and trigger Income Clarity only after the relevant documents reach EXTRACTED status. Alternatively, use the MOS webhook subscription for the extraction.completed event as your trigger signal once webhook subscriptions are enabled for your tenant.

Step 1: Check which documents are eligible

Before triggering the calculation, verify that income-eligible documents are present in the loan file:

curl -X GET https://api.mos.true.ai/v1/loans/{loanId}/income-eligible-documents \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-tyk-mos-client-secret: YOUR_CLIENT_SECRET" \
  -H "tenant-id: YOUR_TENANT_ID"

The response lists every document in the loan file that qualifies for income analysis, with each document's documentId, documentType, and current processingStatus. This call is a preflight check that confirms prerequisites without committing to a calculation run. If the list is empty, Loan Setup has not yet produced extracted documents of the right types.

Use this endpoint in your integration logic before every trigger call, not just the first. When new income documents arrive mid-process — such as a corrected W-2 or an additional pay stub — this endpoint reflects the updated document set immediately.

Step 2: Trigger the calculation

Once eligible documents are confirmed, trigger the Income Clarity calculation:

curl -X POST https://api.mos.true.ai/v1/loans/{loanId}/income-clarity/trigger \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-tyk-mos-client-secret: YOUR_CLIENT_SECRET" \
  -H "tenant-id: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "requestedBy": "system-integration",
    "forceRecalculation": false
  }'

The two body parameters:

• requestedBy — a string identifying who or what triggered the calculation. This value appears in the income clarity history record. Use a system identifier for automated triggers and a user identifier for manual retriggers from your UI.
• forceRecalculation — set to true to re-run the calculation even if a result already exists for this loan. Set to false (or omit it) for initial trigger calls. See Re-running after new documents arrive below.

The endpoint returns immediately with a taskId and status: "active". The Candor analysis runs asynchronously; the response does not block on the result.

Step 3: Poll for results

Poll GET /loans/{loanId}/income-clarity until the calculatedAt field is populated:

curl -X GET https://api.mos.true.ai/v1/loans/{loanId}/income-clarity \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-tyk-mos-client-secret: YOUR_CLIENT_SECRET" \
  -H "tenant-id: YOUR_TENANT_ID"

While the calculation is in progress, calculatedAt is null. Once Candor completes the analysis, the full response includes:

The files[] array is the audit trail. It records which documents Candor evaluated to produce the incomeData result. For investor delivery or compliance review, this array answers "which documents were used?" without any manual reconstruction.

Poll at a fifteen-second interval. Income Clarity completes in under three minutes from trigger to result under normal load.

Webhook alternative to polling

MOS supports outbound webhook subscriptions as an event-driven alternative to polling. Once enabled for your tenant, the extraction.completed event fires for each document as soon as the EXTRACTOR stage finishes. You can use this as both the signal to trigger the Income Clarity calculation and, after triggering, as the signal that new income documents are ready for a recalculation.

A typical webhook-driven Income Clarity flow:

1. Subscribe to extraction.completed for the loan.
2. When the event fires for an income-eligible document type (W-2, pay stub, 1040, etc.), call /income-eligible-documents to confirm the full eligible set is ready.
3. Trigger the Income Clarity calculation.
4. If a second extraction.completed fires for a new income document after the first calculation, retrigger with forceRecalculation: true.

Each delivery is signed with x-mos-webhook-* headers so your endpoint can verify the payload came from MOS. Contact your MOS integration team to enable webhook subscriptions for your tenant.

Re-running after new documents arrive

If new income-eligible documents are added to the loan file after the first calculation — for example, when the borrower submits an updated W-2 or an additional pay stub arrives — re-trigger with forceRecalculation: true:

curl -X POST https://api.mos.true.ai/v1/loans/{loanId}/income-clarity/trigger \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-tyk-mos-client-secret: YOUR_CLIENT_SECRET" \
  -H "tenant-id: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "requestedBy": "new-document-handler",
    "forceRecalculation": true
  }'

Without forceRecalculation: true, the trigger call returns the existing result rather than initiating a new run. With it set to true, MOS evaluates the current income-eligible document set — now including the new documents — and produces a fresh incomeData result. The prior run is not overwritten; it is preserved in the history endpoint.

Viewing calculation history

Every Income Clarity run for a loan is recorded. To retrieve the full history:

curl -X GET https://api.mos.true.ai/v1/loans/{loanId}/income-clarity/history \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-tyk-mos-client-secret: YOUR_CLIENT_SECRET" \
  -H "tenant-id: YOUR_TENANT_ID"

The response returns an array of prior runs, each with a runId, status, createdAt timestamp, and the requestedBy value from the trigger call. This gives you a complete audit trail of every time an income calculation was run on the loan, in chronological order.

Use the history endpoint when building a loan-level UI that shows calculation provenance, when investigating discrepancies between calculations, or when preparing investor-grade documentation for a closed loan.

Key numbers