> ## 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. # The User Income & Employment Reports object > User-level Verification of Income and Employment (VOIE) reports that aggregate income and employment data across all account links. User Reports aggregate income and employment data across all of a user's account links into a single report. For data from a single account link, see [Link Income and Employment Reports](/api-reference/account-link-income-and-employment-reports/object). **Link-level vs User-level reports:** Link-level reports (`GET /v1/links/{link_id}/income/report/`) contain data from a single payroll connection and include link-exclusive fields like `status`, `is_suspicious`, and `access_token`. User-level reports (`POST /v1/users/{user_id}/reports/`) aggregate across all connections, exposing the top-level `report_id` plus the per-employment `gse_accepted` flag (nested under `links[].employments[]`) for GSE submission. Both report types include `provider`. Use user-level reports for mortgage/GSE workflows. # 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) | ## 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) | ### 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](#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](#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](#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](#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\_updated | 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, null | Supervisor's name | | profile | object | Person's identity information | | company | object | [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. | Attribute | Type | Description | | :-------- | :----- | :-------------------------------- | | name | string | Company name | | address | object | [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: `S` - Salary, `H` - Hourly, `D` - Daily, `W` - Weekly, `M` - Monthly | | 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: `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. | 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 Use the endpoints below to manage user-level reports. * [Create a report](/api-reference/user-income-and-employment-reports/users_reports) * [Retrieve a report](/api-reference/user-income-and-employment-reports/users_get_report) # Example response The sample below is a JSON response for the endpoint. ```json theme={null} { "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": "john.doe@example.com", "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 } ] } ] } ```