Skip to main content
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.
error_messageDescription
Possible tampering detectedThe document appears to have been altered or modified from its original form. This is the strongest fraud signal. Route to your fraud review team.
error_messageDescription
The documents contain different full namesFull names across uploaded documents don’t match each other
The documents contain different company namesEmployer names across uploaded documents don’t match each other
The documents contain different SSN'sSSNs across uploaded documents don’t match each other
The applicant first name mismatched with one in the documentsThe applicant’s first name from the order doesn’t match the documents
The applicant last name mismatched with one in the documentsThe applicant’s last name from the order doesn’t match the documents
SSN mismatch in application and dataThe SSN from the order doesn’t match the SSN in the documents
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 processing status) and never reach this config_error path.
error_messageDescription
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_messageDescription
Not enough data to complete the taskDocuments didn’t contain sufficient information
No employment dates are availableEmployment dates couldn’t be found in the documents
No saved employments foundNo employment records found in the documents
The connected account does not have required dataThe account doesn’t contain the needed data
No paystubs or W-2s found for the most recent employmentNo recent income documents found for the current employer
Required data not found in the sourceRequired verification data couldn’t be located
No statements found for employmentNo income statements found for the reported employment
Most recent company does not have addressEmployer 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 requiredApplicant 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.
TierBehavioris_suspiciousTask statusData returnedWhen it triggers
Tier 1Task completes, data flaggedtruecompletedYesData anomalies detected but document is processable (e.g., SSN mismatch, name mismatch, minor inconsistencies)
Tier 2Task fails, no data returnedN/Aconfig_errorNoDocument 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

ScenarioWhat happenedTierRecommended action
Name mismatchThe order was for John Doe, but his spouse Jane Doe connected her payroll account1Manual review. Verify the correct person connected.
SSN mismatchThe SSN on the order doesn’t match the SSN returned from the payroll provider1Manual review. Confirm identity with the applicant.
Employer mismatchThe applicant’s reported employer doesn’t match the connected payroll account1Manual review. The applicant may have changed jobs or connected the wrong account.
Document tamperingUploaded document metadata or content shows signs of alteration2Route to fraud team. No data is returned.
Known fraud templateDocument matches a known fraudulent template pattern2Route 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.
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.
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.
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.
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.
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.
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:
CheckFlag
Different SSNs across documentsThe documents contain different SSN's
Different company names across documentsThe documents contain different company names
Different applicant names across documentsThe documents contain different full names
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:
  1. Do not auto-reject. The flag is a signal for manual review, not an automatic denial.
  2. Compare the order details against the returned data. Check names, SSN, and employer information.
  3. 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.
ScenarioSource of truthComparison targetResult
Payroll connectionSSN on the orderSSN from the payroll provider’s recordsis_suspicious: true if mismatch
Document upload (single doc)SSN on the orderSSN extracted from the uploaded documentSSN mismatch in application and data error
Document upload (multiple docs)Each documentOther uploaded documentsThe 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.

​
Priority levels

SignalPriorityAction
Possible tampering detectedHigh: FraudEscalate to fraud review team immediately
Identity mismatches (names, SSN across docs)Medium: ReviewManual review to determine if intentional or error
is_suspicious: true on payroll connectionMedium: ReviewCompare order details against returned data
File issues (encrypted, wrong type)Low: ResubmitAsk applicant to re-upload correct documents
no_data errorsLow: ResubmitRequest 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

Bridge Events

Client-side event reference for error handling and fallback routing