The paystub object | SpreadSpace

An extracted paystub, one pay period.

The retrieve endpoint returns this object on its own. The list endpoint returns one per document, wrapped as { "borrower_id": …, "paystubs": [ { "extracted_document_id", "document_category", "report_data" } ] }.

A paystub read from a Plaid payroll income response carries extraction_source plaid_payroll_income on its document; the same response’s annual statements arrive as W-2 objects. The employee’s Social Security number is only ever its last four digits, and a deposit account only its last four.

The documents behind this object carry document_category paystub or pay_stub. Money keys are JSON strings with exactly two decimals ("9200000.00", "-1250.50"). Date keys are YYYY-MM-DD, as each key’s Type column shows.

Fields

Key	Type	Present when	Description
`employer_name`	string, nullable	Always	The employer’s name.
`employer_address`	string, nullable	Always	The employer’s address on one line: street, city, state and postal code.
`employee_name`	string, nullable	Always	The employee’s name.
`employee_address`	string, nullable	Always	The employee’s address on one line: street, city, state and postal code.
`employee_ssn_last4`	string, nullable	Always	The last four digits of the employee’s social security number; the rest of the number is never served.
`marital_status`	string, nullable	Always	The employee’s marital status for tax withholding, lower case as stated.
`pay_date`	string (YYYY-MM-DD), nullable	Always	The date the pay was issued, as YYYY-MM-DD.
`period_start`	string (YYYY-MM-DD), nullable	Always	The first day of the pay period, as YYYY-MM-DD.
`period_end`	string (YYYY-MM-DD), nullable	Always	The last day of the pay period, as YYYY-MM-DD.
`pay_frequency`	string, nullable	Always	How often the employee is paid: weekly, biweekly, semimonthly, monthly, quarterly, annual, or unknown when the frequency stated is none of these.
`pay_basis`	string, nullable	Always	How the employee is paid, for example salary or hourly, lower case as stated.
`rate_of_pay_amount`	string (money), nullable	Always	The employee’s rate of pay, in the unit rate_of_pay_basis names.
`rate_of_pay_basis`	string, nullable	Always	The unit of the rate of pay, for example annual or hourly, lower case as stated.
`gross_current`	string (money), nullable	Always	Gross pay for the pay period.
`gross_ytd`	string (money), nullable	Always	Gross pay for the year to date.
`net_current`	string (money), nullable	Always	Net pay for the pay period.
`net_ytd`	string (money), nullable	Always	Net pay for the year to date.
`deductions_total_current`	string (money), nullable	Always	Total deductions for the pay period.
`deductions_total_ytd`	string (money), nullable	Always	Total deductions for the year to date.
`hours_current`	string, nullable	Always	Hours worked in the pay period, as a decimal string.
`earnings`	array of PaystubLine	Always	The earnings rows the stub lists, one per kind of pay, in the order stated.
`deductions`	array of PaystubLine	Always	The deductions rows the stub lists, one per tax or withholding, in the order stated.
`distributions`	array of objects	Always	Where the net pay was deposited, one row per receiving account.
`status`	always `EXTRACTED`	Always	Always `EXTRACTED` on a paystub the API returns.
`signals`	array of objects	Always	Notes about the paystub; empty when there are none.

`distributions[]`

One deposit of the net pay.

Key	Type	Present when	Description
`bank_name`	string, nullable	Always	The receiving bank’s name.
`account_name`	string, nullable	Always	The receiving account’s name.
`account_type`	string, nullable	Always	The receiving account’s type, for example checking or savings.
`account_last4`	string, nullable	Always	The last four digits of the receiving account number; the rest of the number is never served.
`amount`	string (money), nullable	Always	The amount deposited to the account.

`signals[]`

A note about the paystub.

Key	Type	Present when	Description
`severity`	string, one of `info`, `warn`	Always	How much weight the note carries: info or warn.
`code`	string	Always	The note’s identifier.
`detail`	string	Always	The note in words.

Shared objects

Object types that several keys above carry. The Type column names them.

PaystubLine

One earnings or deductions row of a paystub.

Key	Type	Present when	Description
`description`	string, nullable	Always	The row’s label as stated.
`kind`	string, nullable	Always	The row’s standard kind when the payroll provider states one, for example `regular_pay`, `overtime` or `bonus`; null otherwise.
`hours`	string, nullable	Always	Hours for the row in the pay period, as a decimal string, when stated.
`rate`	string (money), nullable	Always	The hourly rate for the row, when stated.
`current_amount`	string (money), nullable	Always	The row’s amount for the pay period.
`ytd_amount`	string (money), nullable	Always	The row’s amount for the year to date.