Skip to main content
Verify borrower income and employment by uploading documents directly to Truv. Send pay stubs, W-2s, 1099s, and tax returns through the Document Collections API. Truv validates, classifies, and extracts structured data — no Bridge widget required.
Integration pattern: Document Processing | Products: Document extraction (pay stubs, W-2s, 1099s, tax returns) | Demo: Document Processing

​
Get started

1

Run the demo

Clone and run the Document Processing demo to upload documents, validate them, and extract structured data locally.
git clone https://github.com/truvhq/demo-apps.git
cd demo-apps
npm install && npm start
Open http://localhost:5173, select Mortgage > Document Processing, and process the pre-loaded test pay stubs. You can also upload your own PDF, JPEG, or PNG files.See full setup instructions for ngrok and environment configuration.
2

Understand the API flow

The demo follows this sequence:
  1. Create a user — Your server calls POST /v1/users/ to create a Truv user for the borrower.
  2. Create a document collection — Your server sends Base64-encoded files to POST /v1/documents/collections/ with the user_id. Truv validates each file (size, type, readability, uniqueness) and classifies it by document type.
  3. Poll for validation — Your server polls GET /v1/documents/collections// until all files reach successful status.
  4. Finalize the collection — Your server calls POST /v1/documents/collections//finalize/ to trigger data extraction.
  5. Receive webhooks — Truv sends a task-status-updated webhook with status: done when extraction completes. The payload includes a link_id.
  6. Retrieve extracted data — Fetch the income report using the link_id from the webhook via GET /v1/links//income/report/.
3

Review the code

Each step maps to a specific file in the demo. Use these as reference when building your integration.
StepDemo fileAPI reference
Collection creationserver/routes/upload-documents.jsPOST /v1/documents/collections/
Validation pollingsrc/demos/UploadDocuments.jsxGET /v1/documents/collections//
Finalizationserver/routes/upload-documents.jsPOST /v1/documents/collections//finalize/
Webhook verificationserver/webhooks.jsWebhook events
Report retrievalserver/routes/upload-documents.jsLink income report

​
Mortgage-specific configuration

​
Supported document types

DocumentUse caseFields extracted
Pay stubsIncome verificationEmployer, gross/net pay, deductions, pay period
W-2 formsAnnual incomeWages, federal/state taxes, employer EIN
1099 forms (NEC, MISC, DIV)Self-employed incomeNon-employee compensation, payer info
Tax returns (1040)Filed incomeAGI, tax liability, filing status

​
Common document combinations

Purchase / Refinance (employed borrower):
  • 2 most recent pay stubs
  • Most recent W-2
  • Prior year W-2 (if available)
Self-employed borrower:
  • 1099 forms
  • 1040 tax return
  • Bank statements (for asset verification)

​
GSE compliance

Document-extracted data supports Fannie Mae D1C and Freddie Mac AIM. Every document is checked against 50M+ verified pay stubs for fraud detection. The output report uses the same schema as direct payroll connections — no changes to your LOS integration or underwriting workflow.

​
Document upload via Bridge

When document upload is enabled in the Truv Dashboard, borrowers who can’t connect their payroll provider can upload documents directly within the Truv Bridge widget. Documents uploaded through Bridge are identified by data_source: "docs" in the response.

​
Next steps

Implementation Guide

Complete API walkthrough for Document Collections

Document Collections API

Full API reference for upload, validate, finalize, and retrieve

Fraud & Manual Review

Handle fraud detection and document errors

GSE Testing

Test with Fannie Mae and Freddie Mac report IDs