> ## 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.

# Income & Employment for Mortgage

> Verify borrower income and employment directly from payroll providers, certified by Fannie Mae and Freddie Mac

Verification of Income and Employment (VOIE) provides instant access to borrower income and employment data directly from payroll providers. Truv connects to 85%+ of US employees through ADP, Paychex, Workday, UKG, and 100+ other providers.

## Benefits

<CardGroup cols={2}>
  <Card title="GSE Certified" icon="certificate">Fannie Mae D1C and Freddie Mac LPA certified reports</Card>
  <Card title="85%+ Coverage" icon="users">Connects to ADP, Paychex, Workday, UKG, and 100+ providers</Card>
  <Card title="Instant Results" icon="bolt">Verified income and employment data in seconds</Card>
  <Card title="Multiple Income Types" icon="layer-group">W-2, 1099, gig, disability benefits, retirement benefits, and military income</Card>
</CardGroup>

<Note>
  **GSE Certified**: Truv's Income & Employment reports are certified by Fannie Mae ([Desktop Underwriter](https://singlefamily.fanniemae.com/applications-technology/desktop-underwriter)) and Freddie Mac (Loan Product Advisor). Reports are generated in GSE-compatible formats automatically.
</Note>

***

## What you get

<CardGroup cols={2}>
  <Card title="Income Data" icon="dollar-sign">
    * Base salary, hourly rate, commission, bonus
    * Pay frequency (weekly, bi-weekly, semi-monthly, monthly)
    * Year-to-date gross and net pay
    * Historical pay statements
    * Tax deductions and withholdings
  </Card>

  <Card title="Employment Data" icon="building">
    * Employer name, address, phone, EIN
    * Employment status (active, terminated, leave)
    * Start and end dates
    * Job title and position
    * Full-time / part-time classification
  </Card>

  <Card title="Documents" icon="file-lines">
    * Pay stubs (PDF)
    * W-2 forms (when available)
    * Employment verification letter
    * GSE-formatted PDF report
  </Card>

  <Card title="Supported Income Types" icon="users">
    * W-2 employees
    * 1099 contractors
    * Benefits providers
    * Military (MyPay)
  </Card>
</CardGroup>

***

## Data coverage

### Employers and Payroll Providers

Truv connects to 85%+ of US employees through major payroll providers:

| Category           | Examples                        |
| ------------------ | ------------------------------- |
| Employers          | Walmart, Costco, Walgreens      |
| Payroll providers  | ADP, Paychex, Workday           |
| Gig                | Uber, Lyft, DoorDash            |
| Benefits providers | Disability, Retirement, Veteran |
| PEOs               | TriNet, Accupay, iSolved        |

Further explore: [Payroll Coverage](/developers/coverage-payroll)

***

## GSE Certification

### Fannie Mae: Day 1 Certainty

* Rep and warrant relief on income and employment
* Reduced documentation requirements
* Validated data meeting DU requirements

### Freddie Mac: Loan Product Advisor

* [Asset and Income Modeler (AIM)](https://sf.freddiemac.com/tools-learning/technology-tools/our-solutions/aim-asset-income-modeler)
* Automated income assessment
* LPA integration

For document-based income when a borrower cannot complete a payroll connection, use [AIM Check](/mortgage/products/aim-check).

[Learn more about GSE testing →](/developers/testing/gse-testing)

***

## How to implement

Choose your integration path based on your tech stack:

| Path                                                      | Code Required | Best For                                  |
| --------------------------------------------------------- | ------------- | ----------------------------------------- |
| [LOS/POS Integration](/mortgage/integration/los-overview) | None          | Encompass, nCino, Floify, BeSmartee users |
| [Truv Dashboard](/developers/dashboard)                   | None          | Manual orders, pilot testing              |
| [Custom Integration](/mortgage/integration/custom-pos)    | Custom        | Full API control, custom borrower portal  |

For custom integrations, see the [POS Application guide](/mortgage/integration/custom-pos) for the borrower-facing flow or the [LOS guide](/mortgage/integration/custom-los) for loan-officer-initiated verification.

***

## Report structure

When you retrieve VOIE data via the API, the response follows the [Income Report](/api-reference/account-link-income-and-employment-reports/link_detail_reports_income) schema. Each report contains an `employments` array with income and employment details per employer. The income product automatically includes employment data.

| Field          | Path                               | Example                |
| -------------- | ---------------------------------- | ---------------------- |
| Annual income  | `employments[].income`             | `"70000.00"`           |
| Income period  | `employments[].income_unit`        | `YEARLY`               |
| Pay per period | `employments[].pay_rate`           | `"6500.00"`            |
| Pay frequency  | `employments[].pay_frequency`      | `SM` (Semi-Monthly)    |
| Employer name  | `employments[].company.name`       | `"Acme Corporation"`   |
| Employee name  | `employments[].profile.first_name` | `"John"`               |
| Pay statements | `employments[].statements[]`       | Array of pay stubs     |
| W-2 forms      | `employments[].w2s[]`              | Array of W-2 documents |

<Accordion title="View full response example" icon="code">
  ```json theme={null}
  {
    "id": "24d7e80942ce4ad58a93f70ce4115f5c",
    "status": "done",
    "provider": "adp",
    "data_source": "payroll",
    "employments": [
      {
        "income": "70000.00",
        "income_unit": "YEARLY",
        "pay_rate": "6500.00",
        "pay_frequency": "SM",
        "company": {
          "name": "Acme Corporation",
          "address": {
            "street": "123 Main St",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94102"
          },
          "phone": "4155550100",
          "ein": "123456789"
        },
        "profile": {
          "first_name": "John",
          "last_name": "Doe",
          "ssn": "222233333"
        },
        "statements": [
          {
            "pay_date": "2024-01-15",
            "net_pay": "2900.00",
            "gross_pay": "4250.00",
            "period_start": "2024-01-01",
            "period_end": "2024-01-15"
          }
        ],
        "w2s": [],
        "annual_income_summary": []
      }
    ]
  }
  ```
</Accordion>

<Info>
  **Pay frequency codes:** `M` (Monthly), `SM` (Semi-Monthly), `W` (Weekly), `BW` (Bi-Weekly), `A` (Annually), `SA` (Semiannually), `C` (Commission)
</Info>

***

## API reference

<CardGroup cols={2}>
  <Card title="Orders" icon="file-circle-plus" href="/api-reference/orders/object">Create and manage verification orders</Card>
  <Card title="Income Report" icon="file-lines" href="/api-reference/account-link-income-and-employment-reports/link_detail_reports_income">Retrieve income verification data</Card>
  <Card title="Employment Report" icon="building" href="/api-reference/account-link-income-and-employment-reports/link_detail_reports_employment">Retrieve employment verification data</Card>
  <Card title="Bridge Token" icon="key" href="/api-reference/bridge-token/object">Create tokens for Truv Bridge</Card>
</CardGroup>

***

## Best practices

<AccordionGroup>
  <Accordion title="Use deeplinking when you know the employer" icon="link">
    If you know the borrower's employer upfront, pass a `company_mapping_id` when creating the order. This skips the employer search screen and drops the borrower directly into the login flow, improving completion rates.
    [Learn more →](/developers/integration/embedded-orders/deeplinking)
  </Accordion>

  <Accordion title="Handle multiple employers" icon="building">
    Borrowers with multiple income sources (e.g., W-2 + 1099, or two W-2 employers) will create multiple connections. Process each connection as it completes via webhooks rather than waiting for all to finish.
  </Accordion>

  <Accordion title="Plan for edge cases" icon="triangle-exclamation">
    * **Self-employed borrowers** may not have payroll data. Pair `income` with `assets` to capture bank transaction data.
    * **Recently changed employers**: the borrower may need to connect both current and previous payroll providers
    * **MFA-enabled accounts**: ensure your UX accounts for MFA prompts during the Bridge flow
  </Accordion>
</AccordionGroup>

***

## Next steps

<CardGroup cols={2}>
  <Card title="POS Application" icon="code" href="/mortgage/integration/custom-pos">
    Embed verification in a borrower-facing portal
  </Card>

  <Card title="LOS Integration" icon="list-check" href="/mortgage/integration/custom-los">
    Send verification links from your loan origination system
  </Card>

  <Card title="GSE Testing" icon="certificate" href="/developers/testing/gse-testing">
    Validate Fannie Mae and Freddie Mac compliance
  </Card>

  <Card title="Sample Reports" icon="file-contract" href="/mortgage/testing/sample-reports">
    View example VOIE report output
  </Card>
</CardGroup>