> This page is for API.
> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.spreadspace.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.spreadspace.app/_mcp/server.
# The paystub object
> The extracted paystub record: one pay period's gross pay, deductions and net pay, this period and year to date.
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" } ] }`.
## Explore
[Retrieve a paystub](/api/api-reference/paystubs/get-paystub)
GET`/api/borrowers/:borrower_id/extractions/:doc_id/paystub`
[List all paystubs](/api/api-reference/paystubs/get-paystubs)
GET`/api/borrowers/:borrower_id/extractions/paystubs`
A paystub read from a Plaid payroll income response carries
`extraction_source` `plaid_payroll_income` on its document, and one read from a
Finicity VOIE payroll report, VOIE paystub report or pay statement report
carries `finicity_voie`. The Plaid response's annual statements arrive as
[W-2 objects](/api/api-reference/w2s/object). 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. |