> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truv.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Fraud Detection & Manual Review
> How to interpret the is_suspicious flag, detect document fraud, and handle manual review scenarios
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:
```bash theme={null}
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\_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. |
| 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 |
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](/developers/integration/document-processing#step-4-monitor-validation-and-classification-server-side)) 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.
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:
| 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` |
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:
```json theme={null}
{
"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](#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](#detect-document-upload-fraud) section below.
***
## Recommended review workflow
```mermaid theme={null}
flowchart TD
A[Verification completes] --> B{Check status}
B -->|completed| C{is_suspicious?}
B -->|config_error| D[Fetch task details]
B -->|no_data| E[Fetch task details]
C -->|false| F[Auto-approve or proceed]
C -->|true| G[Route to manual review]
D --> H{error_message?}
H -->|Possible tampering detected| I[Route to fraud team]
H -->|Identity mismatch| G
H -->|File issue| J[Request re-upload]
E --> K[Request additional documents]
```
### 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](/developers/testing/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
Implementation guide for document uploads
Test fraud detection with sample documents
All connection statuses and error states
Complete error code reference
Client-side event reference for error handling and fallback routing