Data Reference for Income and Employment

View the reference data for verification, employment, employer, income, and employee identity information in an income and employment report.

Overview

The sections below cover each of the data values and configurations for income and employment reports. Use the Retrieve an income and employment report endpoint to collect the data.

Data Structure

Field Customization

In your Dashboard, select specific data fields for your API response. Mandatory fields are grayed out and can't be disabled. View the example below.

Example report

The JSON sample below contains a comprehensive response.

{
  "id": "24d7e80942ce4ad58a93f70ce4115f5c",
  "status": "new",
  "completed_at": "2021-04-06 11:30:00+00:00",
  "access_token": "48427a36d43c4d5aa6324bc06c692456",
  "tracking_info": "user123456",
  "refresh_status": "new",
  "employments": [
    {
      "id": "24d7e80942ce4ad58a93f70ce4115f5c",
      "job_title": "PR associate",
      "job_type": "F",
      "start_date": "2018-01-01",
      "end_date": "2019-08-24",
      "external_last_updated": "2019-08-24",
      "original_hire_date": "2017-06-21",
      "is_active": false,
      "dates_from_statements": false,
      "derived_fields": [
        "is_active"
      ],
      "missing_data_fields": [
        "w2s"
      ],
      "profile": {
        "first_name": "John",
        "last_name": "Doe",
        "middle_initials": "K",
        "ssn": "123456789",
        "email": "[email protected]",
        "date_of_birth": "1992-03-03",
        "home_address": {
          "street": "1 Morgan Ave",
          "city": "Los Angeles",
          "state": "CA",
          "zip": "90210"
        }
      },
      "company": {
        "name": "Facebook Demo",
        "address": {
          "street": "1 Hacker Way",
          "city": "Menlo Park",
          "state": "CA",
          "zip": "94025"
        },
        "phone": "6503087300"
      },
      "income": "70000.00",
      "income_unit": "YEARLY",
      "pay_rate": "2153.60",
      "pay_frequency": "M",
      "manager_name": "Jenny McDouglas",
      "statements": [
        {
          "id": "24d7e80942ce4ad58a93f70ce4115f5c",
          "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",
          "bonus_ytd": "1000.00",
          "commission_ytd": "24000.00",
          "overtime": "45.00",
          "overtime_ytd": "500.00",
          "other_pay": "60.00",
          "other_pay_ytd": "700.00",
          "earnings": [
            {}
          ],
          "earnings_ytd": [
            {}
          ],
          "deductions": [
            {}
          ],
          "deductions_ytd": [
            {}
          ],
          "md5sum": "03639d6a6624f69a54a88ea90bd25e9d",
          "file": "https://citadelid-resources.s3-us-west-2.amazonaws.com/paystub_sample.pdf"
        }
      ],
      "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"
        }
      ],
      "annual_salary": "70000.00",
      "hourly_salary": "36.40",
      "w2s": [
        {
          "file": "https://citadelid-resources.s3-us-west-2.amazonaws.com/W2_sample.pdf",
          "md5sum": "f65e30c39124ad707ac4b3aeaee923a7",
          "year": 2020
        }
      ]
    }
  ],
  "provider": "adp"
}

Verification data

The data below relates to income and employment verification. Truv has two endpoints for the retrieval of the VOIE report.

AttributeTypeDescription
idstringUnique ID of the report
statusstringTask status from Connection Lifecycle
completed_atstringTimestamp of completed report
finished_atstringTime when report was finished
access_tokenstringaccess_token for a Link to payroll provider
tracking_infostringProvided string value when bridge_token was created
is_suspiciousbooleanFlag to indicate if the data from the source is suspicious. For example: Fraud detected in uploaded documents or SSN of the user does not match with the data
providerstringUser connected payroll provider
data_sourcestringSource of data
payroll - Payroll provider parsing
docs - User-uploaded documents
pdf_reporturiEmployer verification report in PDF format
refresh_statusstringStatus of most recent refresh task
employmentsarray of objectsList of employer data, see Employments

AttributeTypeDescription
report_idstringUnique ID of the report
created_atstringTimestamp when the report was created
completed_atstringTimestamp of completed report
linksarray of objectsList of employment links, see Links
tracking_infostringProvided string value when bridge_token was created
providerstringUser connected payroll provider
refresh_statusstringStatus of most recent refresh task
employmentsarray of objectsList of payroll provider employments received

Links

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

AttributeTypeDescription
idstringUnique identifier of the most recent data pull
link_idstringUnique identifier of the link
tracking_infostringAdditional optional identifier passed by user
providerstringData provider ID
employmentsarray of objectsList of employee data, see Employments

Employment and income data

Employments

The Employments object contains the values and descriptions below.

AttributeTypeDescription
idstringUnique ID for an employment
job_titlestring
(nullable)
Employee's job title
job_typestring
(nullable)
Type of employment recorded in payroll provider:
F - Full Time
P - Part Time
S - Seasonal
D - Daily (per diem)
C - Contract
start_datestring(date)Date when employment started
end_datestring(date)
(nullable)
Date when employment ended
external_last_updatedstring(date)
(nullable)
Date of last update from payroll provider for employment data
original_hire_datestring(date)
(nullable)
Date when employee was originally hired
is_activeboolean
(nullable)
Status of active employment
dates_from_statementsboolean
(nullable)
Status of employee's hire and termination dates from first and last pay statements (Deprecated)
derived_fieldsobject
(nullable)
Array of derived fields
missing_data_fieldsobject
(nullable)
List of missing data fields in the payroll API response
incomestring(decimal)
(nullable)
Income amount not including commission or bonuses
income_unitstring
(nullable)
Pay interval for income:
YEARLY - Annual
MONTHLY - Monthly
WEEKLY - Weekly
DAILY - Daily
HOURLY - Hourly
pay_frequencystring
(nullable)
Pay frequency:
M - Monthly
SM - Semi-Monthly
BW - Bi-Weekly
W - Weekly
pay_ratestring(decimal)
(nullable)
Yearly income amount employee earns per pay period
manager_namestring
(nullable)
Direct supervisor's name
companyobject
(nullable)
Employer information
profileobject
(nullable)
Identity information
annual_income_summaryobject
(nullable)
Annual income summary from last pay stub of the year
statementsobject
(nullable)
List of paystubs found in the payroll account
w2sobject
(nullable)
List of W-2 forms found in the payroll account
bank_accountsobject
(nullable)
List of bank accounts linked to the payroll account and allocations for direct deposit
gse_acceptedBooleanStatus of provider eligibility from Fannie Mae Desktop Underwriter (only applies to VOIE Report for a User)

Company

This table covers information about employers within our payroll provider records.

AttributeTypeDescription
namestringEmployer name
address objectEmployer address.
phonestring
(nullable)
Employer phone number
einstring
(nullable)
Employer Identification Number

Truv will try to normalize address to a standard form, but in some rare cases (less than 0.1%), components could be returned as-is from the data provider. E.g. state might be returned as 'California' instead of 'CA'.

Profile

The table below is a summary of personal employee information from the payroll provider.

AttributeTypeDescription
idstringID of the object
created_atstringPerson's identity info was retrieved first time (ISO 8601)
updated_atstringPerson's identity info was retrieved last time (ISO 8601)
first_namestringFirst name
last_namestringLast name
full_namestringFull name
middle_initialsstring
(nullable)
Middle initials
ssnstring
(nullable)
Social security number (Full or last 4 digits)
emailstring(email)
(nullable)
Personal or work email address
date_of_birthstring(date)
(nullable)
Date of birth
home_address objectHome address

Address

The values in this table are for the address object.

AttributeTypeDescription
streetstringStreet
citystringCity
statestringState
zipstringZip
countrystringCountry

Annual income summary

The values below are from the annual income summary from the last pay stub of the year.

AttributeTypeDescription
idstringUnique ID
yearintegerYear
regularstring(decimal)
(nullable)
Regular salary
bonusstring(decimal)
(nullable)
Bonuses
commissionstring(decimal)
(nullable)
Commissions
overtimestring(decimal)
(nullable)
Overtime
other_paystring(decimal)
(nullable)
All other type of income
gross_paystring(decimal)
(nullable)
Gross income
net_paystring(decimal)
(nullable)
Net income

Statements

The table below covers pay stub information.

AttributeTypeDescription
idstringUnique ID
check_numberstring
(nullable)
External ID of pay stub from payroll provider
pay_datestring(date)Pay Date
period_startstring(date)
(nullable)
Period start
period_endstring(date)
(nullable)
Period end
basis_of_paystring
(nullable)
Basis of pay:
S - Salary
H - Hourly
D - Daily
W - Weekly
hoursstring
(nullable)
Number of hours worked this pay period
gross_paystring(decimal)
(nullable)
Gross pay
gross_pay_ytdstring(decimal)
(nullable)
Gross pay year to date
net_paystring(decimal)
(nullable)
Net pay
net_pay_ytdstring(decimal)
(nullable)
Net pay year to date
regularstring(decimal)
(nullable)
Regular pay
regular_ytdstring(decimal)
(nullable)
Regular pay year to date
bonusstring(decimal)
(nullable)
Bonuses
bonus_ytdstring(decimal)
(nullable)
Bonuses year to date
commissionstring(decimal)
(nullable)
Commissions
commission_ytdstring(decimal)
(nullable)
Commission year to date
overtimestring(decimal)
(nullable)
Overtime pay
overtime_ytdstring(decimal)
(nullable)
Overtime pay year to date
other_paystring(decimal)
(nullable)
Sum of all other types of income
other_pay_ytdstring(decimal)
(nullable)
Year to date sum of all other types of income
earningsobject
(nullable)
Earnings for this pay cycle by type
earnings_ytdstring (nullable)Earnings year to date by type
     namestring (nullable)Earnings name
     amountstring (nullable)Earnings amount value
     categorystring (nullable)Title of category
Supported categories: regular, bonus, commission, overtime, other_pay
     ratestring (nullable)Pay rate for a specified earnings name
     unitsstring (nullable)Number of hours worked for a specified earnings name
deductionsobject
(nullable)
Deductions for this pay cycle by type
deductions_ytdobject
(nullable)
Deductions year to date by type
     amountstring (decimal)
(nullable)
Deductions amount value
     categorystring (nullable)Title of category
Supported categories: memo, medicare, retirement, socialsec, federal, state, garnishment, local, other
     namestring (nullable)Deductions name
md5sumstring(string)
(nullable)
Computed MD5 hash value from file content
filestring(uri)
(nullable)
Content-type format specified link to pay stub file
derived_fieldsobject
(nullable)
Array of derived fields
missing_data_fieldsobject
(nullable)
List of missing data fields in the payroll API response

Sample pay stub

The image file below is an example document for an individual pay stub.

Earnings

This field contains a statement object with an array of all earnings information.

AttributeTypeDescription
namestring (nullable)Earnings name
amountstring (decimal)
(nullable)
Earnings amount value
categorystring (nullable)Title of category
Supported categories: regular, bonus, commission, overtime, other_pay
ratestring (nullable)Pay rate for a specified earnings name
unitsstring (nullable)Number of hours worked for a specified earnings name

Earnings response

The sample below is a JSON response for earnings.

[
  {
    "name": "Regular",
    "amount": "38072.00",
    "category": "regular",
    "rate": null,
    "units": null
  },
  {
    "name": "Bonus",
    "amount": "10000.00",
    "category": "bonus"
  },
  {
    "name": "Overtime",
    "amount": "60.58",
    "category": "overtime",
    "rate": "30.29",
    "units": "2"
   }
]

Deductions

This field contains a statement object with an array of all deductions information.

AttributeTypeDescription
amountstring (decimal)
(nullable)
Deductions amount value
categorystring (nullable)Title of category
Supported categories: memo, medicare, retirement, socialsec, federal, state, garnishment, local, other
namestring (nullable)Deductions name

Deductions response

The JSON response below contains examples of deductions.

[
  {
    "amount": "127.01",
    "category": "socialsec",
    "name": "Social Security Tax"
  },
  {
    "amount": "46.23",
    "category": "state",
    "name": "VA State Income Tax"
  },
  {
    "amount": "29.70",
    "category": "medicare",
    "name": "Medicare Tax"
  }
]

W2s

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

W2 example

The image below is a sample W-2 form.

Bank accounts

This field covers bank account information from connected payroll accounts. It also includes direct deposit allocations for each.

AttributeTypeDescription
account_numberstringAccount number
routing_numberstring
(nullable)
Routing number
account_namestring
(nullable)
User friendly account name
bank_namestring
(nullable)
Bank name
account_typestring
(nullable)
Account type:
C - Checking account
S - Savings account
deposit_typestring
(nullable)
Deposit type:
E - Entire paycheck
P - Percentage of the paycheck
A - Fixed amount from the paycheck
deposit_valuestring(decimal)
(nullable)
Deposit value

Downloading PDF Reports

When users connect successfully, Truv automatically generates reports. These are available for users to download from the dashboard or through the API.