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.
Attribute | Type | Description |
---|---|---|
report_id | string | Unique identifier of the report |
created_at | date-time | Timestamp when the report was created |
completed_at | date-time | Timestamp when the report was completed |
links | array of objects | List of employment links, see Links object |
Links object
The information in this table is for values in the Links object.
Attribute | Type | Description |
---|---|---|
link_id | string | Unique identifier of the link |
tracking_info | string | Additional optional identifier passed by user |
provider | string | Data provider ID |
provider_name | string | Data provider name |
employments | array of objects | List 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 |
income_unit | string | Pay interval for income field, only for income product |
pay_rate | string | Payment rate per pay cycle, only for income product |
pay_frequency | string | Pay frequency, only for income product |
statements | array of objects | List of paystubs received from a payroll provider, only for income product, see Statements object |
annual_income_summary | array of objects | Annual income summary by years, only for income product, see Annual income summary object |
bank_accounts | array of objects | List of bank accounts linked to employment, only for income product, see Bank accounts object |
w2s | array of objects | List of W-2 forms linked to employment, only for income product, see W2s object |
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 |
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 | |
gse_accepted | Boolean | Status of provider eligibility from Fannie Mae Desktop Underwriter |
Company object
This table covers values within the company object.
Attribute | Type | Description |
---|---|---|
name | string | Company name |
address | object | Address object |
phone | string | Company phone number |
ein | string | Employer Identification Number |
Address object
The values in this table are for the address object of the company.
Attribute | Type | Description |
---|---|---|
street | string | Street |
city | string | City |
state | string | State |
zip | string | Zip |
country | string | Country |
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 |
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.
Attribute | Type | Description |
---|---|---|
id | string | Unique ID |
year | integer | Income report year |
regular | string | Regular salary |
bonus | string | Bonus |
commission | string | Commission |
overtime | string | Overtime pay |
other_pay | string | All other payment forms |
net_pay | string | Net pay |
gross_pay | string | Gross 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 |
deposit_type | string | Deposit type |
deposit_value | string | Deposit value |
bank_name | string | Bank name |
W2s object
The values in this table are for the W-2s object field.
Attribute | Type | Description |
---|---|---|
file | uri | Link to W2 report file, format is specified in the content-type |
md5sum | string | MD5 hash value computed based on file content |
year | integer | Year |
wages | string | Wages, tips, other compensation (Section 1) |
federal_tax | string | Federal income tax withheld (Section 2) |
social_security_wages | string | Social security wages (Section 3) |
social_security_tax | string | Social security tax withheld (Section 4) |
medicare_wages | string | Medicare wages (Section 5) |
medicare_tax | string | Medicare tax withheld (Section 6) |
gross_pay | string | Gross 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
}
]
}
]
}