Skip to main content
User Reports aggregate income and employment data across all of a user’s account links into a single report. For data from a single account link, see Link Income and Employment Reports.
Link-level vs User-level reports: Link-level reports (GET /v1/links/{link_id}/income/report/) contain data from a single payroll connection and include fields like status, is_suspicious, access_token, and provider. User-level reports (POST /v1/users/{user_id}/income_and_employment/report/) aggregate across all connections and include report_id and gse_accepted for GSE submission. Use user-level reports for mortgage/GSE workflows.

​
Attributes

The tables below have the values, format, and descriptions for the responses.
AttributeTypeDescription
report_idstringUnique identifier of the report
created_atdate-timeTimestamp when the report was created
completed_atdate-timeTimestamp when the report was completed
linksarray of objectsList of employment links, see Links object
The information in this table is for values in the Links object.
AttributeTypeDescription
link_idstringUnique identifier of the link
tracking_infostringAdditional optional identifier passed by user
providerstringData provider ID
provider_namestringData provider name
employmentsarray of objectsList of employee data, see Employments object

​
Employments object

The Employments object contains the values and descriptions below.
AttributeTypeDescription
incomestringIncome amount not including commission or bonuses, only for income product. Null for employment product
income_unitstringPay 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_ratestringPayment rate per pay cycle, only for income product. Null for employment product
pay_frequencystringPay 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
statementsarray of objectsList of paystubs received from a payroll provider, only for income product, see Statements object. Null for employment product
annual_income_summaryarray of objectsAnnual income summary by years, only for income product, see Annual income summary object. Null for employment product
bank_accountsarray of objectsList of bank accounts linked to employment, only for income product, see Bank accounts object. Null for employment product
w2sarray of objectsList of W-2 forms linked to employment, only for income product, see W2s object. Null for employment product
idstringUnique ID
is_activeBooleanStatus of active employment
job_titlestringEmployee’s job title
job_typestringEmployee’s job type: F - Full Time, P - Part Time, S - Seasonal, D - Daily (per diem), C - Contract
start_datedateEmployee’s hire date
original_hire_datedateOriginal hire date
end_datedateEmployee’s end date
external_last_updatedateIndicates date of last updated employment data from Payroll Provider
derived_fieldsarray of stringsArray of derived fields
missing_data_fieldsarray of stringsList of missing data fields from payroll response
manager_namestringSupervisor’s name
profileobjectPerson’s identity information
companyobjectCompany object
gse_acceptedBooleanStatus of provider eligibility from Fannie Mae Desktop Underwriter

​
Company object

This table covers values within the company object.
AttributeTypeDescription
namestringCompany name
addressobjectAddress object
phonestringCompany phone number
einstringEmployer Identification Number
Address object
The values in this table are for the address object of the company.
AttributeTypeDescription
streetstringStreet
citystringCity
statestringState
zipstringZip
countrystringCountry

​
Statements object

View the table below for information from the Statements object.
AttributeTypeDescription
idstringUnique ID
check_numberstringExternal ID of pay stub from payroll provider
pay_datedatePay date
net_paystringNet pay
net_pay_ytdstringNet pay year to date
gross_paystringGross pay
gross_pay_ytdstringGross pay year to date
bonusstringBonus
commissionstringCommission
hoursstringWork hours during pay period
basis_of_paystringBasis of pay: S - Salary, H - Hourly, D - Daily, W - Weekly
period_startdatePeriod start
period_enddatePeriod end
regularstringRegular pay
regular_ytdstringRegular salary year to date
other_pay_ytdstringAll other payment year to date
bonus_ytdstringBonus year to date
commission_ytdstringCommission year to date
overtimestringOvertime pay
overtime_ytdstringOvertime pay year to date
other_paystringAll other payment
earningsarray of objectsEarnings for this pay cycle by type
earnings_ytdarray of objectsEarnings year to date by type
deductionsarray of objectsDeductions for pay cycle by type
deductions_ytdarray of objectsDeductions year to date by type
md5sumstringMD5 hash value computed based on file content
fileuriLink to pay stub file, format is specified in the content-type
derived_fieldsarray of stringsArray of derived fields
missing_data_fieldsarray of stringsList of missing data fields from payroll response

​
Annual income summary object

Find information for the attributes and values of the annual income summary object.
AttributeTypeDescription
idstringUnique ID
yearintegerIncome report year
regularstringRegular salary
bonusstringBonus
commissionstringCommission
overtimestringOvertime pay
other_paystringAll other payment forms
net_paystringNet pay
gross_paystringGross pay

​
Bank accounts object

The table below covers the attributes within the bank accounts object.
AttributeTypeDescription
account_numberstringAccount number
routing_numberstringRouting number
account_namestringUser friendly account name
account_typestringAccount type: C - Checking account, S - Savings account
deposit_typestringDeposit type: E - Entire paycheck, P - Percentage of the paycheck, A - Fixed amount from the paycheck
deposit_valuestringDeposit value
bank_namestringBank name

​
W2s object

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

​
Endpoints

Use the endpoints below to manage user-level reports.

​
Example response

The sample below is a JSON response for the endpoint. 
{
  "report_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2022-05-04T11:30:00Z",
  "completed_at": "2022-05-04T12:00:00Z",
  "links": [
    {
      "link_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "tracking_info": "string",
      "provider": "string",
      "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",
          "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": "john.doe@example.com",
            "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"
          },
          "gse_accepted": true
        }
      ]
    }
  ]
}