Fraud Detection & Manual Review

Truv provides two layers of protection when processing verifications: an is_suspicious flag on verification reports and detailed error detection for document uploads. Understanding when and how to act on each is critical for maintaining data integrity without creating unnecessary friction.

Detect document upload fraud

For document processing (pay stubs, W-2s, tax forms), Truv runs every uploaded document through fraud detection trained on 50M+ verified pay stubs. When fraud or data issues are detected, the connection status is set to config_error or no_data.

Detecting fraud in document uploads

When a document upload task completes with a config_error status, fetch the task record to get the specific error message:

curl --request GET \
     --url 'https://prod.truv.com/v1/tasks/?order_id=ORDER_ID' \
     --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
     --header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET'

Check the error_message field on each task in the response. The error_message field on the task record provides the specific reason for the failure.

config_error messages

These indicate issues with the uploaded documents that require action. Some are fraud-related, others are validation failures.

Fraud & tampering

error_message	Description
`Possible tampering detected`	The document appears to have been altered or modified from its original form. This is the strongest fraud signal. Route to your fraud review team.

Identity mismatches

error_message	Description
`The documents contain different full names`	Full names across uploaded documents don’t match each other
`The documents contain different company names`	Employer names across uploaded documents don’t match each other
`The documents contain different SSN's`	SSNs across uploaded documents don’t match each other
`The applicant first name mismatched with one in the documents`	The applicant’s first name from the order doesn’t match the documents
`The applicant last name mismatched with one in the documents`	The applicant’s last name from the order doesn’t match the documents
`SSN mismatch in application and data`	The SSN from the order doesn’t match the SSN in the documents

File issues

These errors only occur for documents uploaded through the Truv Bridge experience. For document collections, the same issues are caught up front by the validation check at upload time (see Monitor validation and classification) and never reach this config_error path.

error_message	Description
`Please upload documents without password protection or encryption.`	The file is password-protected or encrypted. Re-upload an unprotected version.
`File type not supported. Please ensure each uploaded file matches the requested document type.`	Unsupported file format. Accepted formats include PDF and common image types.
`Some documents have mismatched type or subtype: '{filename}' has '{type}' type, expected '{type}'`	A paystub was uploaded when a W-2 was expected, or vice versa

no_data messages

These indicate the documents were processed but didn’t contain enough information to complete the verification.

error_message	Description
`Not enough data to complete the task`	Documents didn’t contain sufficient information
`No employment dates are available`	Employment dates couldn’t be found in the documents
`No saved employments found`	No employment records found in the documents
`The connected account does not have required data`	The account doesn’t contain the needed data
`No paystubs or W-2s found for the most recent employment`	No recent income documents found for the current employer
`Required data not found in the source`	Required verification data couldn’t be located
`No statements found for employment`	No income statements found for the reported employment
`Most recent company does not have address`	Employer address couldn’t be determined
`Empty annual income summary data for {year}`	No annual income summary for the specified year
`Task {task_id}. Profile validation failed: first_name and last_name are required`	Applicant name wasn’t provided. Required for processing.

Manual Review with is_suspicious Flag

Every income and employment verification report includes an is_suspicious boolean field. When true, it signals that something in the returned data warrants a closer look. It does not necessarily indicate fraud.

Two-tier fraud detection

Truv uses a two-tier detection system. The tier determines whether the task completes with data or fails entirely.

Tier	Behavior	`is_suspicious`	Task status	Data returned	When it triggers
Tier 1	Task completes, data flagged	`true`	`completed`	Yes	Data anomalies detected but document is processable (e.g., SSN mismatch, name mismatch, minor inconsistencies)
Tier 2	Task fails, no data returned	N/A	`config_error`	No	Document is too suspicious to process (e.g., confirmed tampering, known fraud template match)

Tier 1 flags require manual review but still return data. Tier 2 blocks the verification entirely because the document cannot be trusted. Check the task error_message for Tier 2 failures.

Common triggers

Scenario	What happened	Tier	Recommended action
Name mismatch	The order was for John Doe, but his spouse Jane Doe connected her payroll account	1	Manual review. Verify the correct person connected.
SSN mismatch	The SSN on the order doesn’t match the SSN returned from the payroll provider	1	Manual review. Confirm identity with the applicant.
Employer mismatch	The applicant’s reported employer doesn’t match the connected payroll account	1	Manual review. The applicant may have changed jobs or connected the wrong account.
Document tampering	Uploaded document metadata or content shows signs of alteration	2	Route to fraud team. No data is returned.
Known fraud template	Document matches a known fraudulent template pattern	2	Route to fraud team. No data is returned.

Detection indicators

Truv’s fraud detection engine, trained on 50M+ verified pay stubs, analyzes documents across multiple dimensions.

Document metadata analysis

Every uploaded document carries metadata that reveals its creation and editing history. Truv inspects PDF producer fields, creation timestamps, and modification history to detect documents that were generated or altered using manipulation tools rather than produced by a legitimate payroll system.

Known fraud template matching

Truv maintains a library of known fraudulent document templates. Uploaded documents are compared against these patterns to catch documents created from widely circulated fraud kits or template generators.

Manipulation tool detection

Documents edited with PDF manipulation software leave distinct artifacts. Truv detects these fingerprints, including font substitution, layer inconsistencies, and editing tool signatures that differ from legitimate payroll-generated documents.

Browser-generated PDF detection

Pay stubs “printed to PDF” from a browser rather than exported from a payroll system have different structural characteristics. While not always fraudulent, browser-generated PDFs bypass the payroll system’s native export and are flagged for review.

Date and pay period consistency

Truv validates that pay dates, pay period start and end dates, and year-to-date totals are internally consistent. Mismatched dates, impossible pay periods, or YTD totals that don’t align with pay frequency are flagged.

Cross-document consistency

When multiple documents are uploaded (e.g., several pay stubs or a pay stub plus a W-2), Truv cross-references them for consistency. Inconsistencies trigger Tier 1 flags or Tier 2 failures depending on severity:

Check	Flag
Different SSNs across documents	`The documents contain different SSN's`
Different company names across documents	`The documents contain different company names`
Different applicant names across documents	`The documents contain different full names`

Cross-field validation

Individual fields within a document are validated against each other. Truv checks that gross pay, deductions, and net pay are arithmetically consistent, that tax withholdings are within plausible ranges for the stated income, and that employer identification numbers (EINs) match known formats.

How to handle each tier

Tier 1: `is_suspicious = true`

The is_suspicious flag appears in the response body when you fetch a verification report:

{
  "id": "24d7e80942ce4ad58a93f70ce4115f5c",
  "status": "completed",
  "is_suspicious": true,
  "employers": [...]
}

When is_suspicious is true:

Do not auto-reject. The flag is a signal for manual review, not an automatic denial.
Compare the order details against the returned data. Check names, SSN, and employer information.
Contact the applicant if needed. In many cases, the mismatch has a simple explanation (e.g., a spouse connected instead of the applicant).

Treating is_suspicious: true as an automatic rejection will create false positives. Always route these to manual review rather than declining outright.

Tier 2: Task fails with `config_error`

When a document is too suspicious to process, the task fails with status config_error and no verification data is returned. Fetch the task record to get the specific error_message. See Detect document upload fraud for all error messages and recommended actions.

SSN mismatch detection

When you create an order with the applicant’s SSN, Truv automatically compares it against the SSN returned from the payroll provider or extracted from uploaded documents. This is a backend validation — there is no front-end control or configuration.

Scenario	Source of truth	Comparison target	Result
Payroll connection	SSN on the order	SSN from the payroll provider’s records	`is_suspicious: true` if mismatch
Document upload (single doc)	SSN on the order	SSN extracted from the uploaded document	`SSN mismatch in application and data` error
Document upload (multiple docs)	Each document	Other uploaded documents	`The documents contain different SSN's` error

SSN matching runs automatically on every verification where an SSN is provided on the order. You cannot disable or configure this behavior. If no SSN is provided on the order, cross-matching against the payroll provider is skipped, but cross-document SSN consistency checks still run for document uploads.

For payroll connections, an SSN mismatch sets is_suspicious: true on the report (Tier 1). The verification still completes with data, but you should route the result to manual review before accepting it. For document uploads, SSN mismatches produce config_error task failures with specific error messages listed in the Identity mismatches section below.

Recommended review workflow

Priority levels

Signal	Priority	Action
`Possible tampering detected`	High: Fraud	Escalate to fraud review team immediately
Identity mismatches (names, SSN across docs)	Medium: Review	Manual review to determine if intentional or error
`is_suspicious: true` on payroll connection	Medium: Review	Compare order details against returned data
File issues (encrypted, wrong type)	Low: Resubmit	Ask applicant to re-upload correct documents
`no_data` errors	Low: Resubmit	Request additional or different documents

Test fraud scenarios

Truv provides test documents in sandbox mode to simulate fraud detection. See Test Documents for downloadable files including:

Tampered documents: triggers Possible tampering detected
Different SSNs: triggers SSN mismatch errors
Different applicant names: triggers name mismatch errors
No data / invalid data: triggers no_data scenarios

Next steps

Document Processing

Implementation guide for document uploads

Test Documents

Test fraud detection with sample documents

Connection Lifecycle

All connection statuses and error states

Errors & Handling

Complete error code reference

Bridge Events

Client-side event reference for error handling and fallback routing

​Detect document upload fraud

​Detecting fraud in document uploads

​config_error messages

​no_data messages

​Manual Review with is_suspicious Flag

​Two-tier fraud detection

​Common triggers

​Detection indicators

​How to handle each tier

​Tier 1: is_suspicious = true

​Tier 2: Task fails with config_error

​SSN mismatch detection

​Recommended review workflow

​Priority levels

​Test fraud scenarios

​Next steps

Document Processing

Test Documents

Connection Lifecycle

Errors & Handling

Bridge Events

Detect document upload fraud

Detecting fraud in document uploads

config_error messages

no_data messages

Manual Review with is_suspicious Flag

Two-tier fraud detection

Common triggers

Detection indicators

How to handle each tier

Tier 1: `is_suspicious = true`

Tier 2: Task fails with `config_error`

SSN mismatch detection

Recommended review workflow

Priority levels

Test fraud scenarios

Next steps