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.

Attribute

Type

Description

id

string

Unique ID of the report

status

string

Task status from Connection Lifecycle

completed_at

string

Timestamp of completed report

finished_at

string

Time when report was finished

access_token

string

access_token for a Link to payroll provider

tracking_info

string

Provided string value when bridge_token was created

is_suspicious

boolean

Flag 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

provider

string

User connected payroll provider

data_source

string

Source of data
payroll - Payroll provider aggregation
docs - User-uploaded documents
financial_accounts - Financial account aggregation

pdf_report

uri

Employer verification report in PDF format

refresh_status

string

Status of most recent refresh task

employments

array of objects

List of employer data, see Employments

📘

Employment and Income data will depend on the data source

Payroll connections provide the most comprehensive view of the income and employment data, while uploaded documents and income derived from the bank transactions might have some elements missing. Read more about using multiple data sources here.

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.

Attribute

Type

Description

id

string

Unique ID for an employment

job_title

string
(nullable)

Employee's job title

job_type

string
(nullable)

Type of employment recorded in payroll provider:
F - Full Time
P - Part Time
S - Seasonal
D - Daily (per diem)
C - Contract

start_date

string(date)

Date when employment started

end_date

string(date)
(nullable)

Date when employment ended

external_last_updated

string(date)
(nullable)

Date of last update from payroll provider for employment data

original_hire_date

string(date)
(nullable)

Date when employee was originally hired

is_active

boolean
(nullable)

Status of active employment

dates_from_statements

boolean
(nullable)

Status of employee's hire and termination dates from first and last pay statements (Deprecated)

derived_fields

object
(nullable)

Array of derived fields

missing_data_fields

object
(nullable)

List of missing data fields in the payroll API response

income

string(decimal)
(nullable)

Income amount not including commission or bonuses. The annual amount will be displayed for salaried individuals.

income_unit

string
(nullable)

Pay interval for income:
YEARLY - Annual
MONTHLY - Monthly
WEEKLY - Weekly
DAILY - Daily
HOURLY - Hourly

pay_frequency

string
(nullable)

Pay frequency:
M - Monthly
SM - Semi-Monthly
BW - Bi-Weekly
W - Weekly

pay_rate

string(decimal)
(nullable)

Amount paid per pay cycle for salaried individuals. For hourly workers, refer to the income and income_unit fields for the corresponding pay information.

manager_name

string
(nullable)

Direct supervisor's name

company

object
(nullable)

Employer information

profile

object
(nullable)

Identity information

annual_income_summary

object
(nullable)

Annual income summary from last pay stub of the year

statements

object
(nullable)

List of paystubs found in the payroll account

w2s

object
(nullable)

List of W-2 forms found in the payroll account

bank_accounts

object
(nullable)

List of bank accounts linked to the payroll account and allocations for direct deposit

gse_accepted

Boolean

Status 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.

Attribute

Type

Description

name

string

Employer name

address

object

Employer address.

phone

string
(nullable)

Employer phone number

ein

string
(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.

Attribute

Type

Description

id

string

ID of the object

created_at

string

Person's identity info was retrieved first time (ISO 8601)

updated_at

string

Person's identity info was retrieved last time (ISO 8601)

first_name

string

First name

last_name

string

Last name

full_name

string

Full name

middle_initials

string
(nullable)

Middle initials

ssn

string
(nullable)

Social security number (Full or last 4 digits)

email

string(email)
(nullable)

Personal or work email address

date_of_birth

string(date)
(nullable)

Date of birth

home_address

object

Home 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.

Attribute

Type

Description

id

string

Unique ID

year

integer

Year

regular

string(decimal)
(nullable)

Regular salary

bonus

string(decimal)
(nullable)

Bonuses

commission

string(decimal)
(nullable)

Commissions

overtime

string(decimal)
(nullable)

Overtime

other_pay

string(decimal)
(nullable)

All other type of income

gross_pay

string(decimal)
(nullable)

Gross income

net_pay

string(decimal)
(nullable)

Net income

Statements

The table below covers pay stub information.

Attribute

Type

Description

id

string

Unique ID

check_number

string
(nullable)

External ID of pay stub from payroll provider

pay_date

string(date)

Pay Date

period_start

string(date)
(nullable)

Period start

period_end

string(date)
(nullable)

Period end

basis_of_pay

string
(nullable)

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

hours

string
(nullable)

Number of hours worked this pay period

gross_pay

string(decimal)
(nullable)

Gross pay

gross_pay_ytd

string(decimal)
(nullable)

Gross pay year to date

net_pay

string(decimal)
(nullable)

Net pay

net_pay_ytd

string(decimal)
(nullable)

Net pay year to date

regular

string(decimal)
(nullable)

Regular pay

regular_ytd

string(decimal)
(nullable)

Regular pay year to date

bonus

string(decimal)
(nullable)

Bonuses

bonus_ytd

string(decimal)
(nullable)

Bonuses year to date

commission

string(decimal)
(nullable)

Commissions

commission_ytd

string(decimal)
(nullable)

Commission year to date

overtime

string(decimal)
(nullable)

Overtime pay

overtime_ytd

string(decimal)
(nullable)

Overtime pay year to date

other_pay

string(decimal)
(nullable)

Sum of all other types of income

other_pay_ytd

string(decimal)
(nullable)

Year to date sum of all other types of income

earnings

object
(nullable)

Earnings for this pay cycle by type

earnings_ytd

string (nullable)

Earnings year to date by type

     name

string (nullable)

Earnings name

     amount

string (nullable)

Earnings amount value

     category

string (nullable)

Title of category
Supported categories: regular, bonus, commission, overtime, other_pay

     rate

string (nullable)

Pay rate for a specified earnings name

     units

string (nullable)

Number of hours worked for a specified earnings name

deductions

object
(nullable)

Deductions for this pay cycle by type

deductions_ytd

object
(nullable)

Deductions year to date by type

     amount

string (decimal)
(nullable)

Deductions amount value

     category

string (nullable)

Title of category
Supported categories: memo, medicare, retirement, socialsec, federal, state, garnishment, local, other

     name

string (nullable)

Deductions name

md5sum

string(string)
(nullable)

Computed MD5 hash value from file content

file

string(uri)
(nullable)

Content-type format specified link to pay stub file

derived_fields

object
(nullable)

Array of derived fields

missing_data_fields

object
(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.

Attribute

Type

Description

name

string (nullable)

Earnings name

amount

string (decimal)
(nullable)

Earnings amount value

category

string (nullable)

Title of category
Supported categories: regular, bonus, commission, overtime, other_pay

rate

string (nullable)

Pay rate for a specified earnings name

units

string (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.

Attribute

Type

Description

amount

string (decimal)
(nullable)

Deductions amount value

category

string (nullable)

Title of category
Supported categories: memo, medicare, retirement, socialsec, federal, state, garnishment, local, other

name

string (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.

Attribute

Type

Description

account_number

string

Account number

routing_number

string
(nullable)

Routing number

account_name

string
(nullable)

User friendly account name

bank_name

string
(nullable)

Bank name

account_type

string
(nullable)

Account type:
C - Checking account
S - Savings account

deposit_type

string
(nullable)

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

deposit_value

string(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.