VOIE Reports

View reference information from Verification of Income and Employment (VOIE) reports.

Verification of Income and Employment (VOIE) reports contain information from the user’s accounts. Learn more below about the data provided from reports.

Attributes

The tables below have the values, format, and descriptions for the responses.

AttributeTypeDescription
report_idstringUnique identifier of the report
created_atdate-timeTimestamp when the report was created
completed_atdate-timeTimestamp when the report was completed
linksarray of objectsList of employment links, see Links object

Links object

The information in this table is for values in the Links object.

AttributeTypeDescription
link_idstringUnique identifier of the link
tracking_infostringAdditional optional identifier passed by user
providerstringData provider ID
provider_namestringData provider name
employmentsarray of objectsList of employee data, see Employments object

Employments object

The Employments object contains the values and descriptions below.

Attribute

Type

Description

income

string

Income amount not including commission or bonuses, only for income product
Null for employment product

income_unit

string

Pay interval for income field, only for income product
YEARLY - Annual income
MONTHLY - Monthly income
WEEKLY - Weekly income
DAILY - Daily income
HOURLY - Hourly income
Null for employment product

pay_rate

string

Payment rate per pay cycle, only for income product
Null for employment product

pay_frequency

string

Pay frequency, only for income product
M - Monthly
SM - Semi-Monthly
W - Weekly
BW - Bi-Weekly
A - Annually
SA - Semiannually
C - Commission
Null for employment product

statements

array of objects

List of paystubs received from a payroll provider, only for income product, see Statements object
Null for employment product

annual_income_summary

array of objects

Annual income summary by years, only for income product, see Annual income summary object
Null for employment product

bank_accounts

array of objects

List of bank accounts linked to employment, only for income product, see Bank accounts object
Null for employment product

w2s

array of objects

List of W-2 forms linked to employment, only for income product, see W2s object
Null for employment product

id

string

Unique ID

is_active

Boolean

Status of active employment

job_title

string

Employee's job title

job_type

string

Employee's job type
F - Full Time
P - Part Time
S - Seasonal
D - Daily (per diem)
C - Contract

start_date

date

Employee's hire date

original_hire_date

date

Original hire date

end_date

date

Employee's end date

external_last_update

date

Indicates date of last updated employment data from Payroll Provider

derived_fields

array of strings

Array of derived fields

missing_data_fields

array of strings

List of missing data fields from payroll response

manager_name

string

Supervisor's name

profile

object

Person's identity information

company

object

Company object

gse_accepted

Boolean

Status of provider eligibility from Fannie Mae Desktop Underwriter

Company object

This table covers values within the company object.

AttributeTypeDescription
namestringCompany name
addressobjectAddress object
phonestringCompany phone number
einstringEmployer Identification Number
Address object

The values in this table are for the address object of the company.

AttributeTypeDescription
streetstringStreet
citystringCity
statestringState
zipstringZip
countrystringCountry

Statements object

View the table below for information from the Statements object.

Attribute

Type

Description

id

string

Unique ID

check_number

string

External ID of pay stub from payroll provider

pay_date

date

Pay date

net_pay

string

Net pay

net_pay_ytd

string

Net pay year to date

gross_pay

string

Gross pay

gross_pay_ytd

string

Gross pay year to date

bonus

string

Bonus

commission

string

Commission

hours

string

Work hours during pay period

basis_of_pay

string

Basis of pay
S - Salary
H - Hourly
D - Daily
W - Weekly

period_start

date

Period start

period_end

date

Period end

regular

string

Regular pay

regular_ytd

string

Regular salary year to date

other_pay_ytd

string

All other payment year to date

bonus_ytd

string

Bonus year to date

commission_ytd

string

Commission year to date

overtime

string

Overtime pay

overtime_ytd

string

Overtime pay year to date

other_pay

string

All other payment

earnings

array of objects

Earnings for this pay cycle by type

earnings_ytd

array of objects

Earnings year to date by type

deductions

array of objects

Deductions for pay cycle by type

deductions_ytd

array of objects

Deductions year to date by type

md5sum

string

MD5 hash value computed based on file content

file

uri

Link to pay stub file, format is specified in the content-type

derived_fields

array of strings

Array of derived fields

missing_data_fields

array of strings

List of missing data fields from payroll response

Annual income summary object

Find information for the attributes and values of the annual income summary object.

AttributeTypeDescription
idstringUnique ID
yearintegerIncome report year
regularstringRegular salary
bonusstringBonus
commissionstringCommission
overtimestringOvertime pay
other_paystringAll other payment forms
net_paystringNet pay
gross_paystringGross pay

Bank accounts object

The table below covers the attributes within the bank accounts object.

Attribute

Type

Description

account_number

string

Account number

routing_number

string

Routing number

account_name

string

User friendly account name

account_type

string

Account type
C - Checking account
S - Savings account

deposit_type

string

Deposit type
E - Entire paycheck
P - Percentage of the paycheck
A - Fixed amount from the paycheck

deposit_value

string

Deposit value

bank_name

string

Bank name

W2s object

The values in this table are for the W-2s object field.

AttributeTypeDescription
fileuriLink to W2 report file, format is specified in the content-type
md5sumstringMD5 hash value computed based on file content
yearintegerYear
wagesstringWages, tips, other compensation (Section 1)
federal_taxstringFederal income tax withheld (Section 2)
social_security_wagesstringSocial security wages (Section 3)
social_security_taxstringSocial security tax withheld (Section 4)
medicare_wagesstringMedicare wages (Section 5)
medicare_taxstringMedicare tax withheld (Section 6)
gross_paystringGross pay

Endpoints

The VOIE Reports have the endpoints below.

Example response

The sample below is a JSON response for the endpoint.

{
  "report_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2022-05-04T11:30:00Z",
  "completed_at": "2022-05-04T12:00:00Z",
  "links": [
    {
      "link_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "tracking_info": "string",
      "provider": "string",
      "employments": [
        {
          "income": "70000.00",
          "income_unit": "YEARLY",
          "pay_rate": "6500.00",
          "pay_frequency": "M",
          "statements": [
            {
              "id": "24d7e80942ce4ad58a93f70ce4115f5c",
              "check_number": "29205182",
              "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": [
            {
              "account_number": "1234567890",
              "routing_number": "123456789",
              "account_name": "My Bank",
              "account_type": "C",
              "deposit_type": "A",
              "deposit_value": "200.00",
              "bank_name": "TD Bank"
            }
          ],
          "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",
              "gross_pay": "18211.48"
            }
          ],
          "id": "24d7e80942ce4ad58a93f70ce4115f5c",
          "is_active": false,
          "job_title": "PR associate",
          "job_type": "F",
          "start_date": "2018-01-01",
          "original_hire_date": "2017-06-21",
          "end_date": "2023-04-29",
          "external_last_updated": "2023-04-29",
          "derived_fields": [
            "is_active"
          ],
          "missing_data_fields": [
            "w2s"
          ],
          "manager_name": "Jenny McDouglas",
          "profile": {
            "id": "48427a36d43c4d5aa6324bc06c692456",
            "created_at": "2022-06-07T15:00:00Z",
            "updated_at": "2022-06-31T15:00:00Z",
            "first_name": "John",
            "last_name": "Doe",
            "full_name": "John Doe",
            "middle_initials": "K",
            "email": "[email protected]",
            "ssn": "123456789",
            "date_of_birth": "1992-03-03",
            "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": "6503087300",
            "ein": "12-345678"
          },
          "gse_accepted": true
        }
      ]
    }
  ]
}