Attributes

The table below covers information from the report response.

Attribute	Type	Description
id	string	Unique identifier
status	string	Status from Connection Lifecycle
finished_at	string	Time when report was finished
completed_at	string	~~Time when report was completed~~ (Deprecated, invalid datetime format)
access_token	string	Access token for Link to payroll provider
tracking_info	string	Information passed to Truv Bridge from partner
refresh_status	string	Status of most recent refresh task
employments	array of objects	List of employments, see Employments object
pdf_report	uri	Verification report in PDF format
provider	string	Payroll provider name
data_source	string	Source of data `payroll` - Payroll provider parsing `docs` - User-uploaded documents

Employments object

The Employments object contains the values and descriptions below.

Attribute	Type	Description
income	string	Income amount not including commission or bonuses, only for income product Null for employment product
income_unit	string	Pay interval for income field, only for income product `YEARLY` - Annual income `MONTHLY` - Monthly income `WEEKLY` - Weekly income `DAILY` - Daily income `HOURLY` - Hourly income Null for employment product
pay_rate	string	Payment rate per pay cycle, only for income product Null for employment product
pay_frequency	string	Pay frequency, only for income product `M` - Monthly `SM` - Semi-Monthly `W` - Weekly `BW` - Bi-Weekly `A` - Annually `SA` - Semiannually `C` - Commission Null for employment product
statements	array of objects	List of paystubs received from a payroll provider, only for income product, see Statements object Null for employment product
annual_income_summary	array of objects	Annual income summary by years, only for income product, see Annual income summary object Null for employment product
bank_accounts	array of objects	List of bank accounts linked to employment, only for income product, see Bank accounts object Null for employment product
w2s	array of objects	List of W-2 forms linked to employment, only for income product, see W2s object Null for employment product
id	string	Unique ID
is_active	Boolean	Status of active employment
job_title	string	Employee's job title
job_type	string	Employee's job type `F` - Full Time `P` - Part Time `S` - Seasonal `D` - Daily (per diem) `C` - Contract
start_date	date	Employee's hire date
original_hire_date	date	Original hire date
end_date	date	Employee's end date
external_last_update	date	Indicates date of last updated employment data from Payroll Provider
derived_fields	array of strings	Array of derived fields
missing_data_fields	array of strings	List of missing data fields from payroll response
manager_name	string	Supervisor's name
profile	object	Person's identity information
company	object	Company object
gse_accepted	Boolean	Status of provider eligibility from Fannie Mae Desktop Underwriter

Company object

This table covers values within the company object.

Attribute	Type	Description
name	string	Company name
address	object	Address object
phone	string	Company phone number
ein	string	Employer Identification Number

Address object

The values in this table are for the address object of the company.

Attribute	Type	Description
street	string	Street
city	string	City
state	string	State
zip	string	Zip
country	string	Country

Statements object

View the table below for information from the Statements object.

Attribute	Type	Description
id	string	Unique ID
check_number	string	External ID of pay stub from payroll provider
pay_date	date	Pay date
net_pay	string	Net pay
net_pay_ytd	string	Net pay year to date
gross_pay	string	Gross pay
gross_pay_ytd	string	Gross pay year to date
bonus	string	Bonus
commission	string	Commission
hours	string	Work hours during pay period
basis_of_pay	string	Basis of pay `S` - Salary `H` - Hourly `D` - Daily `W` - Weekly
period_start	date	Period start
period_end	date	Period end
regular	string	Regular pay
regular_ytd	string	Regular salary year to date
other_pay_ytd	string	All other payment year to date
bonus_ytd	string	Bonus year to date
commission_ytd	string	Commission year to date
overtime	string	Overtime pay
overtime_ytd	string	Overtime pay year to date
other_pay	string	All other payment
earnings	array of objects	Earnings for this pay cycle by type
earnings_ytd	array of objects	Earnings year to date by type
deductions	array of objects	Deductions for pay cycle by type
deductions_ytd	array of objects	Deductions year to date by type
md5sum	string	MD5 hash value computed based on file content
file	uri	Link to pay stub file, format is specified in the content-type
derived_fields	array of strings	Array of derived fields
missing_data_fields	array of strings	List of missing data fields from payroll response

Annual income summary object

Find information for the attributes and values of the annual income summary object.

Attribute	Type	Description
id	string	Unique ID
year	integer	Income report year
regular	string	Regular salary
bonus	string	Bonus
commission	string	Commission
overtime	string	Overtime pay
other_pay	string	All other payment forms
net_pay	string	Net pay
gross_pay	string	Gross pay

Bank accounts object

The table below covers the attributes within the bank accounts object.

Attribute	Type	Description
account_number	string	Account number
routing_number	string	Routing number
account_name	string	User friendly account name
account_type	string	Account type `C` - Checking account `S` - Savings account
deposit_type	string	Deposit type `E` - Entire paycheck `P` - Percentage of the paycheck `A` - Fixed amount from the paycheck
deposit_value	string	Deposit value
bank_name	string	Bank name

W2s object

The values in this table are for the W-2s object field.

Attribute	Type	Description
file	uri	Link to W2 report file, format is specified in the content-type
md5sum	string	MD5 hash value computed based on file content
year	integer	Year
wages	string	Wages, tips, other compensation (Section 1)
federal_tax	string	Federal income tax withheld (Section 2)
social_security_wages	string	Social security wages (Section 3)
social_security_tax	string	Social security tax withheld (Section 4)
medicare_wages	string	Medicare wages (Section 5)
medicare_tax	string	Medicare tax withheld (Section 6)
gross_pay	string	Gross pay

Earnings Object

The earnings or earnings_ytd field is an array that contains all earnings. Below is an example of the earnings object with the supported categories: regular, bonus, commission, overtime, other_pay.

[
  {
    "name": "Regular",
    "amount": "38072.0",
    "category": "regular",
    "rate": "475.9",
    "units": "80"
  },
  {
    "name": "Bonus",
    "amount": "10000.0",
    "category": "bonus",
    "rate": null,
    "units": null
  }
]

Deductions Object

The deductions or deductions_ytd field is an array that contains all deductions. Below is an example of the deductions object. The supported categories are the following: memo, medicare, retirement, benefit, socialsec, federal, state, garnishment, local, other.

[
  {
    "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"
  }
]

Endpoints

Use the endpoints below to get information on reports.

Example response

The sample below is a JSON response for the endpoint.

{
  "id": "24d7e80942ce4ad58a93f70ce4115f5c",
  "status": "new",
  "finished_at": "2021-04-06T11:30:00Z",
  "completed_at": "2021-04-06 11:30:00+00:00",
  "access_token": "48427a36d43c4d5aa6324bc06c692456",
  "tracking_info": "user123456",
  "refresh_status": "new",
  "employments": [
    {
      "income": "70000.00",
      "income_unit": "YEARLY",
      "pay_rate": "6500.00",
      "pay_frequency": "M",
      "statements": [
        {
          "id": "24d7e80942ce4ad58a93f70ce4115f5c",
          "check_number": "29205182",
          "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",
          "other_pay_ytd": "700.00",
          "bonus_ytd": "1000.00",
          "commission_ytd": "24000.00",
          "overtime": "45.00",
          "overtime_ytd": "500.00",
          "other_pay": "60.00",
          "earnings": [
            {
              "name": "Regular",
              "amount": "1935.77",
              "category": "regular",
              "rate": null,
              "units": null
            },
            {
              "name": "Overtime",
              "amount": "60.58",
              "category": "overtime",
              "rate": "30.29",
              "units": "2"
            }
          ],
          "earnings_ytd": [
            {
              "name": "Regular",
              "amount": "1935.77",
              "category": "regular",
              "rate": null,
              "units": null
            },
            {
              "name": "Overtime",
              "amount": "60.58",
              "category": "overtime",
              "rate": "30.29",
              "units": "2"
            }
          ],
          "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"
            }
          ],
          "deductions_ytd": [
            {
              "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"
            }
          ],
          "md5sum": "03639d6a6624f69a54a88ea90bd25e9d",
          "file": "https://citadelid-resources.s3-us-west-2.amazonaws.com/paystub_sample.pdf",
          "derived_fields": [
            "basis_of_pay"
          ],
          "missing_data_fields": [
            "earnings_ytd"
          ]
        }
      ],
      "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"
        }
      ],
      "w2s": [
        {
          "file": "https://citadelid-resources.s3-us-west-2.amazonaws.com/W2_sample.pdf",
          "md5sum": "f65e30c39124ad707ac4b3aeaee923a7",
          "year": 2020,
          "wages": "900.50",
          "federal_tax": "75.01",
          "social_security_wages": "900.50",
          "social_security_tax": "56.30",
          "medicare_wages": "900.50",
          "medicare_tax": "13.15",
          "gross_pay": "18211.48"
        }
      ],
      "id": "24d7e80942ce4ad58a93f70ce4115f5c",
      "is_active": false,
      "job_title": "PR associate",
      "job_type": "F",
      "start_date": "2018-01-01",
      "original_hire_date": "2017-06-21",
      "end_date": "2023-04-29",
      "external_last_updated": "2023-04-29",
      "dates_from_statements": false,
      "derived_fields": [
        "is_active"
      ],
      "missing_data_fields": [
        "w2s"
      ],
      "manager_name": "Jenny McDouglas",
      "profile": {
        "id": "48427a36d43c4d5aa6324bc06c692456",
        "created_at": "2022-06-07T15:00:00Z",
        "updated_at": "2022-06-31T15:00:00Z",
        "first_name": "John",
        "last_name": "Doe",
        "full_name": "John Doe",
        "middle_initials": "K",
        "email": "[email protected]",
        "ssn": "123456789",
        "date_of_birth": "1992-03-03",
        "home_address": {
          "street": "1 Morgan Ave",
          "city": "Los Angeles",
          "state": "CA",
          "zip": "90210",
          "country": "US"
        }
      },
      "company": {
        "name": "Facebook Demo",
        "address": {
          "street": "1 Morgan Ave",
          "city": "Los Angeles",
          "state": "CA",
          "zip": "90210",
          "country": "US"
        },
        "phone": "6503087300",
        "ein": "12-345678"
      }
    }
  ],
  "pdf_report": "https://citadelid-resources.s3-us-west-2.amazonaws.com/report.pdf",
  "provider": "adp",
  "data_source": "payroll"
}