# Verification of Employment - Payroll
source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voe-payroll/index.md

## Overview {#overview}

The Verification of Employment -- Payroll (VOE-Payroll) product provides
insights into the consumer's employment. The report includes employment
details, including employer name, employment status, and other
employment information as available. Often used as a verification of
employment prior to closing a mortgage loan.

Learn more about Mastercard's [Income \& Employment](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#income--employment) products.

### Key Product Features {#key-product-features}

* **Employment Summary:** Employer name, address, hire date, latest pay date, employment status, etc

#### Additional Product Information {#additional-product-information}

* **Report Generation Time (median):**
  * Direct API payroll accounts: Less than 5 seconds
  * Credentialed payroll accounts: Less than 10 seconds
* **Report Refreshes:** This report can be refreshed with new data as long as the accounts are still connected, and consent is active. Refreshes are provided at no cost within 60 days after the first report is created. A report pulled after this period will incur a new charge.
* **Supported Report Format:** JSON and PDF

Note: This report may ONLY be furnished for a Fair Credit Reporting Act (FCRA) purpose such as credit, insurance, or employment, and only pursuant to a permissible purpose certification by the report user. Provision and use of this report is subject to all applicable obligations of the FCRA.

### Use Cases {#use-cases}

The VOE -- Payroll product is suitable for the following use case:

* [Mortgage Lending](https://developer.mastercard.com/open-finance-us/documentation/usecases/mortgage-lending/index.md)

## How it Works {#how-it-works}

### Prerequisites {#prerequisites}

This product is dependent on the customer linking their bank accounts via Data Connect. Refer to [Generating Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md) for more information.

* [Generate the required credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials)
* [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token)
* [Create a customer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers)
* [Create a consumer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers)
* [Generate a Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) and [link customer accounts](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#the-connect-flow)

### Generate VOE -- Payroll Report {#generate-voe----payroll-report}

To generate or refresh a VOE -- Payroll report, use the following
endpoint:

API Reference: `POST /decisioning/v2/customers/{customerId}/voePayroll`

The response will include the status of the report generation and a
report ID. A notification is sent when report generation is finished
(see [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md)).

#### Implementation Notes {#implementation-notes}

VOE-Payroll reports are often ordered as a pre-closing verification of employment after previously ordering a VOIE-Payroll report for mortgage lending. If the payroll accounts are still connected, the VOE-Payroll report can be ordered without needing to re-engage the consumer. If accounts are not connected, an error will occur when generating the report, and the customer must be sent back into Data Connect to reconnect their accounts.

### Get VOE -- Payroll Report {#get-voe----payroll-report}

Once the report is generated, retrieve the report using one of the [Get Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md) endpoints.

#### Example Report {#example-report}

The Get Report APIs response contains different data depending on the
type of report requested. The following example shows what a successful
JSON response could look like for this report. Examples are meant for
reference only and may lag production changes.

```json
{
  "id": "41h4nzppn47u-voepayroll",
  "portfolioId": "9qud7dtuzbew-1-port",
  "gseEnabled": true,
  "createdDate": 1579819592,
  "requesterName": "Decisioning API",
  "endUser": {
    "name": "ABC Apartments",
    "address": "123 Main St",
    "city": "Murray",
    "state": "UT",
    "zip": "84123",
    "phone": "555-2106",
    "email": "customerservice@example.com",
    "url": "example.com"
  },
  "requestId": "7a7qyps2iy",
  "customerType": "active",
  "customerId": 1275320,
  "consumerId": "3f7ff2cf0ffb3d0cd59875e070c9b1d4",
  "consumerSsn": "6789",
  "disputeStatement": "Invalid data present.",
  "type": "voePayroll",
  "reportStyle": "credentialedPayroll",
  "title": "Mastercard Open Banking Verification of Employment - Payroll",
  "status": "success",
  "constraints": {
    "payrollData": {
      "payrollAccountIds": [
        "018d3f0e-6c1c-fa13-7e50-0003acfcfdae"
      ],
      "payrollAggregatorResponseId": "4baxktu9wdda"
    }
  },
  "employmentHistory": [
    {
      "asOfDate": 1596175200,
      "employmentId": "zgk6wh3urqr0gtxv",
      "employerName": "ACME INC",
      "payrollSource": "argyle",
      "payrollProvider": "Paychex",
      "employee": {
        "name": "John Doe Smith",
        "givenName": "John",
        "middleName": "Doe",
        "familyName": "Smith",
        "address": [
          {
            "address1": "Address 1",
            "city": "City",
            "state": "TX",
            "zip": "99999"
          }
        ]
      },
      "employment": {
        "employerName": "ACME INC",
        "legalEntityId": "752760000",
        "originalHireDate": 1527832800,
        "latestHireDate": 1527832800,
        "latestPayDate": 1596175200,
        "daysSinceLastPay": 10,
        "numberPayCadenceWithoutPay": 1,
        "employmentEndDate": 1527832800,
        "employmentDuration": "P1Y6M0D",
        "employerAddress": [
          {
            "address1": "Address 1",
            "city": "City",
            "state": "TX",
            "zip": "99999"
          }
        ],
        "employmentStatusCode": "A",
        "employmentStatusName": "Active",
        "workLevelCode": "FT",
        "workLevelName": "Full Time-Regular",
        "latestPayPeriodEndDate": 1699747200,
        "derivedEmploymentStatus": false,
        "workLevelStatus": "Full Time",
        "positionTitle": "Shift Supervisor",
        "positionDuration": "P1Y6M0D"
      },
      "income": {
        "payFrequency": "Weekly"
      }
    }
  ]
}
```

A human-readable PDF version of the report is available which is great
for underwriters or any other manual viewing of the report.

How to read a VOE -- Payroll report:
[VOIE_Payroll_HTR.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/VOIE_Payroll_HTR.pdf) (2MB)

## Testing {#testing}

Refer to [Generating Reports -- Testing](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#testing).

Ensure you use a test profile that is indicated as supporting Payroll
such as [Homer Loanseeker](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#payroll-profiles).