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
- Example Report
- Verification Metadata
- Income and Employment data
- Employer
- Identity
- Annual income summary
- Pay statements
- Earnings from statements
- Deductions form statements
- Bank accounts and pay allocations
- Summary report in PDF
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.
Name | Type | Description |
---|---|---|
id | string | Unique ID of the report |
status | string | Task status from Connection Lifecycle |
completed_at | string | Timestamp of completed report |
access_token | string | access_token for a Link to payroll provider |
tracking_info | string | Provided string value when bridge_token was created |
refresh_status | string | Status of most recent refresh task |
provider | string | User connected payroll provider |
employments | object | List of payroll provider employments received |
Employment and income data
The table below covers payroll provider records of income and employment information.
Name | 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 TimeP - Part TimeS - SeasonalD - 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 |
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 |
income_unit | string (nullable) | Pay interval for income :YEARLY - AnnualMONTHLY - MonthlyWEEKLY - WeeklyDAILY - DailyHOURLY - Hourly |
pay_frequency | string (nullable) | Pay frequency:M - MonthlySM - Semi-MonthlyBW - Bi-WeeklyW - Weekly |
pay_rate | string(decimal) (nullable) | Yearly income amount employee earns per pay period |
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 |
Employer data
This table covers information about employers within our payroll provider records.
Name | Type | Description |
---|---|---|
name | string | Employer name |
address | object (nullable) | Employer address |
street | string (nullable) | Employer street |
city | string (nullable) | Employer city |
state | string (nullable) | Employer state |
zip | string (nullable) | Employer zip code |
phone | string (nullable) | Employer phone number |
Identity data
The table below is a summary of personal employee information from the payroll provider.
Name | Type | Description |
---|---|---|
first_name | string | First name |
last_name | string | Last name |
middle_initials | string (nullable) | Middle initials |
ssn | string (nullable) | Social security number (Full or last 4 digits) |
string(email) (nullable) | Personal or work email address | |
date_of_birth | string(date) (nullable) | Date of birth |
home_address | object (nullable) | Home address |
street | string (nullable) | Street |
city | string (nullable) | City |
state | string (nullable) | State |
zip | string (nullable) | Zip code |
Annual income summary
The values below are from the annual income summary from the last pay stub of the year.
Name | 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.
Name | Type | Description |
---|---|---|
id | string (nullable) | Unique ID |
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 - SalaryH - HourlyD - DailyW - Weekly |
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 | object (nullable) | Earnings year to date by type |
deductions | object (nullable) | Deductions for this pay cycle by type |
deductions_ytd | object (nullable) | Deductions year to date by type |
md5sum | string(string) (nullable) | Computed MD5 hash value from file content |
file | string(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.
Name | 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 |
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.
Name | 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.7",
"category": "medicare",
"name": "Medicare Tax"
}
]
W-2s
This field lists W-2s from the payroll account.
Name | Type | Description |
---|---|---|
year | integer | Year of W-2 |
md5sum | string (nullable) | MD5 hash value computed based on the file content |
file | string(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.
Name | 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 accountS - Savings account |
deposit_type | string (nullable) | Deposit type:E - Entire paycheckP - Percentage of the paycheckA - 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.
Updated 21 days ago