Document Processing

Extract income and employment data from pay stubs, W-2s, and tax documents uploaded by clients or caseworkers. Truv validates each document, classifies the type, and returns structured data in the same format as direct payroll connections.

Document upload is built into the standard Bridge widget as a fallback. If you’re using the Customer Portal or Caseworker Portal, clients can already upload documents when they can’t connect to their payroll provider. Use this page only if you need the standalone Document Collections API for caseworker-driven bulk uploads.

Integration pattern: Document Processing | Products: Document extraction | Demo: PSDocuments

Get started

Run the demo

Clone and run the PSDocuments demo to see the full document upload and extraction flow working locally.

git clone https://github.com/truvhq/demo-apps.git
cd demo-apps
npm install && npm start

Open http://localhost:5173, select Public Sector > Document Processing, and process the pre-loaded test pay stubs. You can also upload your own documents.See full setup instructions for ngrok and environment configuration.

Understand the API flow

The demo follows this sequence:

Create a user — Your server calls POST /v1/users/ with an optional external_user_id (case ID) to create a Truv user.
Create a document collection — Your server sends base64-encoded documents and the user_id to POST /v1/documents/collections/. The response includes a collection_id.
Poll for validation — Your server polls GET /v1/documents/collections// until all files reach status: "successful". Truv validates readability and classifies each document type.
Finalize the collection — Your server calls POST /v1/documents/collections//finalize/ to trigger data extraction.
Receive webhooks — Truv sends a task-status-updated webhook with status: "done" when extraction completes. The webhook includes a link_id for retrieving the report.
Retrieve the report — Fetch the income report using the link_id from the webhook. The extracted data follows the same schema as direct payroll connections.

Review the code

Each step maps to a specific file in the demo. Use these as reference when building your integration.

Step	Demo file	API reference
Collection creation	`server/routes/upload-documents.js`	POST /v1/documents/collections/
Validation polling	`server/routes/upload-documents.js`	GET /v1/documents/collections//
Upload UI	`src/demos/PSDocuments.jsx`	Document Collections
Finalization	`server/routes/upload-documents.js`	POST /v1/documents/collections//finalize/
Webhook verification	`server/webhooks.js`	Webhook events
Report retrieval	`server/routes/upload-documents.js`	Income reports

Public Sector-specific configuration

Government document types

Benefits eligibility determinations commonly use these document types:

Document type	Use case	Fields extracted
Pay stubs	SNAP, TANF, Medicaid income verification	Employer, gross/net pay, deductions, pay period
W-2 forms	Annual income verification	Annual wages, federal/state taxes, employer EIN
1099 forms	Self-employed and gig income	Payer, non-employee compensation
SSA-1099	Social Security benefits	Benefit amounts, tax withholdings
Volunteer letters	Community service hour verification	Organization, hours, dates

Case ID tracking

Pass external_user_id when creating the user to link document collections to your agency’s case identifier.

{
  "external_user_id": "case-12345"
}

Consistent data format

Documents processed through the Document Collections API return structured data in the same schema as direct payroll connections. Use a single ingestion pipeline for both data_source: "docs" and data_source: "payroll" in your eligibility system.

Fallback from payroll connection

When a client can’t connect their payroll provider through Customer Portal or Caseworker Portal, fall back to document upload. Enable document upload in the Truv Dashboard to offer it directly within the Bridge widget.

Next steps

Customer Portal

Embed verification in the client-facing portal

Caseworker Portal

Send verification links and ingest data into caseworker screens