HomeGuidesAPI ReferenceChangelog
Get API Keys

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.

Suggest Edits

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.

NameTypeDescription
idstringUnique ID of the report
statusstringTask status from Connection Lifecycle
completed_atstringTimestamp of completed report
access_tokenstringaccess_token for a Link to payroll provider
tracking_infostringProvided string value when bridge_token was created
refresh_statusstringStatus of most recent refresh task
providerstringUser connected payroll provider
employmentsobjectList of payroll provider employments received

Employment and income data

The table below covers payroll provider records of income and employment information.

NameTypeDescription
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
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

Employer data

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

NameTypeDescription
namestringEmployer name
addressobject
(nullable)		Employer address
streetstring
(nullable)		Employer street
citystring
(nullable)		Employer city
statestring
(nullable)		Employer state
zipstring
(nullable)		Employer zip code
phonestring
(nullable)		Employer phone number

Identity data

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

NameTypeDescription
first_namestringFirst name
last_namestringLast 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_addressobject
(nullable)		Home address
streetstring
(nullable)		Street
citystring
(nullable)		City
statestring
(nullable)		State
zipstring
(nullable)		Zip code

Annual income summary

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

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

NameTypeDescription
idstring
(nullable)		Unique ID
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
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_ytdobject
(nullable)		Earnings year to date by type
deductionsobject
(nullable)		Deductions for this pay cycle by type
deductions_ytdobject
(nullable)		Deductions year to date by type
md5sumstring(string)
(nullable)		Computed MD5 hash value from file content
filestring(uri)
(nullable)		Content-type format specified link to pay stub file

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.

NameTypeDescription
namestring (nullable)Earnings name
amountstring (decimal)
(nullable)		Earnings amount value
categorystring (nullable)Title of category
Supported categories: regular, bonus, commission, overtime, other_pay

Earnings response

The sample below is a JSON response for earnings.

[
  {
    "name": "Regular",
    "amount": "38072.0",
    "category": "regular"
  },
  {
    "name": "Bonus",
    "amount": "10000.0",
    "category": "bonus"
  }
]

Deductions

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

NameTypeDescription
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.7",
    "category": "medicare",
    "name": "Medicare Tax"
  }
]

W-2s

This field lists W-2s from the payroll account.

NameTypeDescription
yearintegerYear of W-2
md5sumstring
(nullable)		MD5 hash value computed based on the file content
filestring(uri)Link to a W2 report file (format is specified in the content-type)

W-2 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.

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

Updated 21 days ago