Data schema
Income and Employment report combines verification, employment, employer and employee identity information. Go to Income and Employment report in API reference to see an example of a response in JSON.
Available data:
- Sample response
- Verification
- Employment and income
- Employer
- Identity
- Annual income summary
- Pay statements
- Earnings from statements
- Deductions form statements
- Bank accounts and allocations
- Summary report in PDF
Sample 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_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
Data associated with employment and income verification.
Name | Type | Description |
---|---|---|
id | string | Unique ID of the report |
status | string | Task status from the Task Lifecycle |
completed_at | string | Timestamp of report completion |
access_token | string | access_token for a Link to payroll provider |
tracking_info | string | Any string value provided by you when bridge_token was created |
refresh_status | string | Status of most recent refresh task |
provider | string | Payroll provider which user connected |
employments | object | List of employments received from a payroll provider |
Employment and income data
Employment and income information that was found in payroll provider records.
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 when employment data was last updated in payroll provider |
original_hire_date | string(date) (nullable) | Date when employee was originally hired. |
is_active | boolean (nullable) | Indicates whether the employment is still active |
dates_from_statements | boolean (nullable) | Indicates whether employee's hire and/or termination dates were derived from first/last pay statements |
derived_fields | object (nullable) | Array of derived fields |
missing_data_fields | object (nullable) | List of data fields which are missing 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 |
manager_name | string (nullable) | Supervisor's name |
company | object (nullable) | Employer information |
profile | object (nullable) | Identity information |
annual_income_summary | object (nullable) | Annual income summary based on last paystub 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 |
annual_salary (Deprecated) | string(decimal) (nullable) | Annual income |
hourly_salary (Deprecated) | string(decimal) (nullable) | Hourly income |
Employer data
Information about all employers that were found in 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
Employee's personal information found in 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
Annual income summary based on the last paystub 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
Information found on a paystub
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 - HourlyW - 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) | MD5 hash value computed based on the file content |
file | string(uri) (nullable) | Link to a pay stub file (format is specified in the content-type) |
Example of a paystub file:
Earnings
Earnings and earnings_ytd field of the Statement object is an array that contains all earnings. Supported categories are: regular, bonus, commission, overtime, other_pay. Sample response:
[
{
"name": "Regular",
"amount": "38072.0",
"category": "regular"
},
{
"name": "Bonus",
"amount": "10000.0",
"category": "bonus"
}
]
Deductions
Deductions and deductions_ytd field of the Statement object is an array that contains all deductions. Supported categories are: memo, medicare, retirement, benefit, socialsec, federal, state, garnishment, local, other. Sample response:
[
{
"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
List W-2s found in 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) |
Example of W-2 file:
Bank accounts
Information about bank accounts connected to the payroll account and direct deposit allocations for each of the accounts.
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 |
PDF report
Truv automatically generates a report that combines information for income and employment verification in PDF and available to download after full_parse.
Updated about 2 years ago