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 link-exclusive fields like status, is_suspicious, and access_token. User-level reports (POST /v1/users/{user_id}/reports/) aggregate across all connections, exposing the top-level report_id plus the per-employment gse_accepted flag (nested under links[].employments[]) for GSE submission. Both report types include provider. Use user-level reports for mortgage/GSE workflows.

Attributes

The tables below have the values, format, and descriptions for the responses.

Attribute	Type	Description
report_id	string	Unique identifier of the report
created_at	date-time	Timestamp when the report was created
completed_at	date-time	Timestamp when the report was completed
links	array of objects	List of employment links, see Links object

Links object

The information in this table is for values in the Links object.

Attribute	Type	Description
link_id	string	Unique identifier of the link
tracking_info	string	Additional optional identifier passed by user
provider	string	Data provider ID
provider_name	string	Data provider name
employments	array of objects	List of employee data, see Employments object

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_updated	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, null	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, `M` - Monthly
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

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
        }
      ]
    }
  ]
}

​Attributes

​Links object

​Employments object

​Company object

​Address object

​Statements object

​Annual income summary object

​Bank accounts object

​W2s object

​Endpoints

​Example response