Overview

VOIE from Truv provides additional options for your users' data. The integrations below bring important financial information through your workflow. View more details about the integrations and use cases in the table below.

Integration	Description	Possible use cases
Document processing	Collect user documents to process and analyze data	- Processing user documents and parse into structured data schema - Back up plan for unsuccessful payroll connection attempts or unprocessed user data, NOTE: View the Designing the Income and Employment UX guide for more on uploading documents as a fallback solution.
Tax return collection	Connect tax preparation providers to income and employment verification	- Alternative requests and confirmations of tax transcripts from the IRS - Collecting and managing digital tax documents
Financial accounts	Use digital records from financial institutions for user income stream insights	- Lenders assessing loan eligibility - Landlords evaluating tenant applications - Employers confirming a potential hire's employment history - Social service agencies determining benefits or assistance eligibility
VOIE for Fannie Mae and Freddie Mac	Use verification of income and employment and share reports with government sponsored enterprises	- Streamline provider information to Fannie Mae and Freddie Mac for users for additional convenience

Process for integrations

The points below cover getting started with the VOIE integration methods. The items below cover the general process. Follow the relevant sections to continue with your use case needs.

Configuring your integration - Planning your use case contexts and needs for configuration
Bridge Token specifications- Setting up Truv Bridge and the required tokens
Testing integrations- Testing your integration with sample credentials and values

Configuring your integration

Each of the integrations for these verification methods has the sections below help to get started. View the configurations in the sections below, then proceed to setting up Truv Bridge. When creating a bridge_token, the integrations have separate values to include for your configuration.

The sections below cover the specifications for each of the integrations when planning out the use case workflow. View the samples in the Bridge Token specifications section for more.

Document processing

Truv's document processing solution helps you collect user documents. These files are then processed to extract structured data and analysed for fraud. The points below cover user information to collect when integrating your document processing solution.

Document type required, such as paystubs, W2, and 1099

📘
Note
For 1099 tax documents, Truv supports parsing for formatting from any year after 2021. This includes the following 1099 forms.

1099-DIV, 1099-G, 1099-INT, 1099-MISC, 1099-NEC, 1099-R

Number of documents required for each type
Applicant first_name and last_name

In addition, you can add a specific message for your users displayed in Truv Bridge. Use Customization Templates to start with configurations for your users.

Tax return collection

Truv simplifies connecting your users to their tax preparation software providers. Configure your introduction page to your users on top of Truv’s widget templates.

Users can then verify income and connect to their tax preparation software from the start. Verification can be instant compared to the wait time for IRS tax returns and documents such as 4506-C. Users can select their tax preparation provider from the list in Truv Bridge.

Financial accounts and income reports

Truv income reports share a comprehensive view of the user’s financial account. This information is an overview and includes historical information. This gives decision makers as much information as possible about a user’s financial account.

Truv simplifies connecting your users to their financial institution. Users can select their bank or credit union in Truv Bridge from the list of most popular financial institutions. They can also look for their financial institution in the search field at the top of the screen.

Report endpoints

These endpoints provide a comprehensive collection of financial account information from a user. View detailed information on the attributes and responses using the Income Report API reference page. The financial account response information is in the Example responses section below.

VOIE for Fannie Mae and Freddie Mac

Truv Verification of Income and Employment (VOIE) provides government sponsored enterprise (GSE) connectivity. With the appropriate configuration, generate and send user VOIE Reports directly to Fannie Mae and Freddie Mac. Simplify your users’ experience with a straightforward way of connecting their financial provider information.

Connecting multiple accounts

For users with more than one account, VOIE has the option to connect multiple accounts. During the connection process for users, users may have multiple tokens to exchange. Once the token exchanges are complete, use the Link information to retrieve or modify data in the user’s account.

User reports

During the verification process, generate user reports with the VOIE Reports endpoints in addition to retrieving information from the provider. These reports are available to send as needed.

Government sponsored enterprise (GSE) compatibility

VOIE report responses contain the gse_accepted field. With this Boolean value enabled, GSEs such as Fannie Mae and Freddie Mac accept the report as is. These two respond differently depending on the resulting reports available.

Fannie Mae - Fully compatible reports are marked as GSE compatible
Freddie Mac - GSE flagged reports may include incomplete or incompatible information

Bridge Token specifications

Each integrations requires additional values in the request when creating a Bridge Token for the User. These values are part of the process for the Implementing Income and Employment Steps guide.

All integrations use the income value for the product_type field. The integrations have separate data_sources field values as well. View more in the configurations section below.

Document upload and Tax return collection - product_type = income, data_sources = ["docs"]
Financial accounts - product_type = income, data_sources = ["financial_accounts"]

Sample cURL configurations

The code sample below contains tabs for each of the integrations.

curl --request POST \
     --url https://prod.truv.com/v1/users/{user_id}/tokens/ \
     --header 'X-Access-Client-Id: {{client_id}}' \
     --header 'X-Access-Secret: {{access_key}}	' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "product_type": "income",
     "data_sources": ["docs"],
     "tracking_info": "any data for tracking current transaction"
}
'

curl --request POST \
     --url https://prod.truv.com/v1/users/{user_id}/tokens/ \
     --header 'X-Access-Client-Id: {{client_id}}' \
     --header 'X-Access-Secret: {{access_key}}	' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "product_type": "income",
     "data_sources": ["tax"],
     "tracking_info": "any data for tracking current transaction"
}
'

curl --request POST \
     --url https://prod.truv.com/v1/users/{user_id}/tokens/ \
     --header 'X-Access-Client-Id: {{client_id}}' \
     --header 'X-Access-Secret: {{access_key}}	' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "product_type": "income",
     "data_source": ["financial_accounts"],
     "tracking_info": "any data for tracking current transaction"
}
'

Testing integrations

The sections below provide details for testing integrations. They include sample documents, credentials, and other test data.

Document processing and upload

When implementing VOIE in your workflow for document uploads, use the Testing guide to try different scenarios within the sandbox. The sections below and the Document processing testing page provide PDFs to upload and test various scenarios.

Document processing testing

When testing for Integrating Document Processing, the PDF downloads in the list below cover different scenarios for sandbox use.

Upload the documents for testing different sandbox response results. Pay statements and tax documents return data when successful. Unsuccessful uploads respond with status updates.

Successful documents - Most recent paystub, Next recent paystub, First paystub, W2
1099 tax forms - 1099-DIV, 1099-G, 1099-INT, 1099-MISC, 1099-NEC, 1099-R, SSA-1099

Suspicious document detection

Documents from uploads may have fraudulent, consistent, or unacceptable data. When encountering these issues, mark specific instances for review. Prevent malicious activity with additional analysis and attention.

View the table below for various scenarios and PDF examples.

Scenario	Description	Downloads
Tampered documents	Information is falsified or manipulated	Tampered 1, Tampered 2, Tampered 3
Different Social Security Numbers	Personal information is inconsistent	SSN 1, SSN 2, SSN 3
Different company names	Company information is inconsistent	Company 1, Company 2, Company 3
Different applicant names	Personal information is inconsistent	Applicant 1, Applicant 2, Applicant 3
Documents without data, or with invalid data	Information is missing or unable to be parsed	No data 1, No data 2, No data 3

📘
Note
Test scenarios use the file name to return results. Testing ignores the file contents when in the sandbox.

Tax return credentials

When implementing VOIE in your workflow for Tax Returns, use the credentials below to try different scenarios within the sandbox.

Username	Password	SSN	Scenario
`goodlogin.tax`	`goodpassword`	`991-91-9991`	Successful login with complete data returned

The table below covers the credentials available for testing error scenarios.

Username	Password	Scenario
`error.user`	`login_error`	Incorrect login and password
`error.user`	`mfa_error`	Issue with multi-factor authentication
`error.user`	`account_locked`	Locked account, requires provider unlock
`error.user`	`no_data`	No data found in provider account
`error.user`	`unavailable`	Provider is not available, maintenance issue
`error.user`	`error`	Generic login error

Example responses

The JSON data below contains sample report payloads for the integrations.

{
  "id": "24d7e80942ce4ad58a93f70ce4115f5c",
  "status": "new",
  "finished_at": "2021-04-06T11:30:00Z",
  "completed_at": "2021-04-06 11:30:00+00:00",
  "access_token": "48427a36d43c4d5aa6324bc06c692456",
  "tracking_info": "user123456",
  "refresh_status": null,
  "employments": [
    {
      "income": null,
      "income_unit": null,
      "pay_frequency": null,
      "statements": [
        {
          "id": "24d7e80942ce4ad58a93f70ce4115f5c",
          "check_number": null,
          "pay_date": "2018-05-15",
          "net_pay": "11500.32",
          "net_pay_ytd": "31980.64",
          "gross_pay": "13900.11",
          "gross_pay_ytd": "49200.00",
          "bonus": "100.00",
          "commission": "12000.00",
          "hours": "40.00",
          "basis_of_pay": "S",
          "period_start": "2018-05-01",
          "period_end": "2018-05-15",
          "regular": "1695.11",
          "regular_ytd": "23000.00",
          "other_pay_ytd": "700.00",
          "bonus_ytd": "1000.00",
          "commission_ytd": "24000.00",
          "overtime": "45.00",
          "overtime_ytd": "500.00",
          "other_pay": "60.00",
          "earnings": [
            {
              "name": "Regular",
              "amount": "1935.77",
              "category": "regular",
              "rate": null,
              "units": null
            },
            {
              "name": "Overtime",
              "amount": "60.58",
              "category": "overtime",
              "rate": "30.29",
              "units": "2"
            }
          ],
          "earnings_ytd": [
            {
              "name": "Regular",
              "amount": "1935.77",
              "category": "regular",
              "rate": null,
              "units": null
            },
            {
              "name": "Overtime",
              "amount": "60.58",
              "category": "overtime",
              "rate": "30.29",
              "units": "2"
            }
          ],
          "deductions": [
            {
              "amount": "127.01",
              "category": "socialsec",
              "name": "Social Security Tax"
            },
            {
              "amount": "46.23",
              "category": "state",
              "name": "VA State Income Tax"
            },
            {
              "amount": "29.7",
              "category": "medicare",
              "name": "Medicare Tax"
            }
          ],
          "deductions_ytd": [
            {
              "amount": "127.01",
              "category": "socialsec",
              "name": "Social Security Tax"
            },
            {
              "amount": "46.23",
              "category": "state",
              "name": "VA State Income Tax"
            },
            {
              "amount": "29.7",
              "category": "medicare",
              "name": "Medicare Tax"
            }
          ],
          "md5sum": "03639d6a6624f69a54a88ea90bd25e9d",
          "file": "https://citadelid-resources.s3-us-west-2.amazonaws.com/paystub_sample.pdf",
          "derived_fields": [
            "basis_of_pay"
          ],
          "missing_data_fields": [
            "earnings_ytd"
          ]
        }
      ],
      "annual_income_summary": [
        {
          "id": "24d7e80942ce4ad58a93f70ce4115f5c",
          "year": 2018,
          "regular": "23000.00",
          "bonus": "1000.00",
          "commission": "24000.00",
          "overtime": "500.00",
          "other_pay": "700.00",
          "net_pay": "31980.64",
          "gross_pay": "49200.00"
        }
      ],
      "bank_accounts": [
      ],
      "w2s": [
        {
          "file": "https://citadelid-resources.s3-us-west-2.amazonaws.com/W2_sample.pdf",
          "md5sum": "f65e30c39124ad707ac4b3aeaee923a7",
          "year": 2020,
          "wages": "900.50",
          "federal_tax": "75.01",
          "social_security_wages": "900.50",
          "social_security_tax": "56.30",
          "medicare_wages": "900.50",
          "medicare_tax": "13.15"
        }
      ],
      "id": "24d7e80942ce4ad58a93f70ce4115f5c",
      "is_active": false,
      "job_title": null,
      "job_type": null,
      "start_date": "2018-01-01",
      "original_hire_date": null,
      "end_date": "2022-06-16",
      "external_last_updated": "2022-06-16",
      "dates_from_statements": true,
      "derived_fields": [
        "is_active"
      ],
      "missing_data_fields": [
      ],
      "manager_name": "Jenny McDouglas",
      "profile": {
        "first_name": "John",
        "last_name": "Doe",
        "middle_initials": "K",
        "email": null,
        "ssn": "6789",
        "date_of_birth": null,
        "home_address": {
          "street": "1 Morgan Ave",
          "city": "Los Angeles",
          "state": "CA",
          "zip": "90210",
          "country": "US"
        }
      },
      "company": {
        "name": "Facebook Demo",
        "address": {
          "street": "1 Morgan Ave",
          "city": "Los Angeles",
          "state": "CA",
          "zip": "90210",
          "country": "US"
        },
        "phone": null
      }
    }
  ],
  "pdf_report": "https://citadelid-resources.s3-us-west-2.amazonaws.com/report.pdf",
  "provider": "doc_upload",
  "data_source": "docs"
}

[
  {
    "id": "24d7e80942ce4ad58a93f70ce4115f5c",
    "document_type": "F1040",
    "document_subtype": "",
    "file": "https://citadelid-resources.s3-us-west-2.amazonaws.com/tax_sample.pdf",
    "md5sum": "24d7e80942ce4ad58a93f70ce4115f5c",
    "year": 2019
  }
]

{
  "status": "success",
  "completed_at": "2022-05-04T11:30:00Z",
  "days_requested": 61,
  "tracking_info": "any string",
  "provider": "bank_of_america",
  "access_token": "99dd17074ac94aa9ace2621d657c7610",
  "companies": [
    "my employer"
  ],
  "accounts": [
    {
      "id": "24d7e80942ce4ad58a93f70ce4115f5c",
      "created_at": "2022-05-04T11:30:00Z",
      "updated_at": "2022-05-04T12:00:00Z",
      "type": "CHECKING",
      "subtype": "MONEY_MARKET",
      "mask": "string",
      "nickname": "My account"
    }
  ],
  "income": [
    {
      "start_date": "2022-05-04",
      "end_date": "2022-05-04",
      "account_id": "24d7e80942ce4ad58a93f70ce4115f5c",
      "income_description": "Paycheck",
      "income_category": "Income: Paycheck",
      "pay_rate": 0,
      "pay_frequency": "SM",
      "total_amounts": [
        {
          "amount": "200.31",
          "iso_currency_code": "USD"
        }
      ],
      "transaction_count": 7,
      "historical_summary": [
        {
          "start_date": "2022-05-04",
          "end_date": "2022-05-04",
          "total_amounts": [
            {
              "amount": "200.31",
              "iso_currency_code": "USD"
            }
          ],
          "transactions": [
            {
              "amount": "200.31",
              "iso_currency_code": "USD",
              "date": "2022-05-04",
              "check_number": "string",
              "description": "string",
              "pending": true,
              "transaction_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
            }
          ]
        }
      ]
    }
  ],
  "summary": {
    "start_date": "2022-05-04",
    "end_date": "2022-05-04",
    "income_sources_count": 2,
    "income_categories_count": 1,
    "income_transactions_count": 17,
    "total_amounts": [
      {
        "amount": "200.31",
        "iso_currency_code": "USD"
      }
    ]
  },
  "is_suspicious": false
}

Integrations for Verifying Income and Employment

Overview

Process for integrations

Configuring your integration

Document processing

📘
Note

Tax return collection

Financial accounts and income reports

Report endpoints

VOIE for Fannie Mae and Freddie Mac

Connecting multiple accounts

User reports

Government sponsored enterprise (GSE) compatibility

Bridge Token specifications

Sample cURL configurations

Testing integrations

Document processing and upload

Document processing testing

Suspicious document detection

📘
Note

Tax return credentials

Example responses

Overview

Process for integrations

Configuring your integration

Document processing

📘Note

Tax return collection

Financial accounts and income reports

Report endpoints

VOIE for Fannie Mae and Freddie Mac

Connecting multiple accounts

User reports

Government sponsored enterprise (GSE) compatibility

Bridge Token specifications

Sample cURL configurations

Testing integrations

Document processing and upload

Document processing testing

Suspicious document detection

📘Note

Tax return credentials

Example responses

📘
Note

📘
Note