> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.spreadspace.app/api/api-reference/w2s/object/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.spreadspace.app/_mcp/server.
# The W-2 object
> The extracted Form W-2 record: the boxes of each wage and tax statement as the readers return them.
An extracted Form W-2, uploaded on its own.
The retrieve endpoint returns this object on its own. The list endpoint
returns one per document, wrapped as
`{ "borrower_id": …, "forms": [ { "extracted_document_id", "document_category", "report_data" } ] }`.
## Explore
[Retrieve a W-2](/api/api-reference/w2s/get-w-2)
GET`/api/borrowers/:borrower_id/extractions/:doc_id/w2`
[List all W-2s](/api/api-reference/w2s/get-w-2-s)
GET`/api/borrowers/:borrower_id/extractions/w2s`
`data` carries the boxes of the first statement in the file and
`data.forms_w2` every statement, one per employer. The employee's Social
Security number is only ever its last four digits, and an employer
identification number reads masked to its last four.
The documents behind this object carry `document_category` `w2` or `form_w2`. Money keys are JSON strings with exactly two decimals (`"9200000.00"`, `"-1250.50"`). The object carries no date keys.
## Fields
| Key | Type | Present when | Description |
| ---------------------- | ---------------- | --------------------------- | ------------------------------------------------------------------------------------------------ |
| `form` | always `w2` | Always | Always `w2`. |
| `data` | object | Always | The boxes of the first statement in the file, with every statement of the file under `forms_w2`. |
| `metadata` | object | Always | How the file was read. |
| `k1_partners` | array | Always | Always empty on a Form W-2. |
| `statements` | array | Always | Always empty on a Form W-2. |
| `depreciation_reports` | object, nullable | When the document states it | Always null on a Form W-2. |
## `data`
The boxes of the first statement in the file, with every statement of the file under `forms_w2`.
| Key | Type | Present when | Description |
| --------------------------------- | ----------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `copy` | string, nullable | Always | The copy letter printed on the form (A, B, C, D, 1 or 2), when the print carries one. |
| `tax_year` | integer, nullable | Always | The tax year printed beside the form title. |
| `control_number` | string, nullable | Always | Box d, control number, as printed. |
| `employer_ein` | string, nullable | Always | Box b, employer identification number, masked to the last four digits. |
| `employer_name` | string, nullable | Always | Box c, the employer's name. |
| `employer_address` | string, nullable | Always | Box c, the employer's address below the name, on one line. |
| `employee_name` | string, nullable | Always | Box e, the employee's first name, initial and last name, as printed. |
| `employee_ssn_last4` | string, nullable | Always | Box a, the last four digits of the employee's social security number; the rest of the number is never served. |
| `box_1_wages` | string (money), nullable | Always | Box 1, wages, tips, other compensation. |
| `box_2_federal_tax_withheld` | string (money), nullable | Always | Box 2, federal income tax withheld. |
| `box_3_ss_wages` | string (money), nullable | Always | Box 3, social security wages. |
| `box_4_ss_tax_withheld` | string (money), nullable | Always | Box 4, social security tax withheld. |
| `box_5_medicare_wages` | string (money), nullable | Always | Box 5, Medicare wages and tips. |
| `box_6_medicare_tax_withheld` | string (money), nullable | Always | Box 6, Medicare tax withheld. |
| `box_7_ss_tips` | string (money), nullable | Always | Box 7, social security tips. |
| `box_8_allocated_tips` | string (money), nullable | Always | Box 8, allocated tips. |
| `box_10_dependent_care_benefits` | string (money), nullable | Always | Box 10, dependent care benefits. |
| `box_11_nonqualified_plans` | string (money), nullable | Always | Box 11, nonqualified plans. |
| `box_12` | array of W2Box12Item | Always | Box 12, one entry per printed code and amount, 12a through 12d. |
| `box_13_statutory_employee` | boolean, nullable | Always | Box 13, the statutory employee box, true when checked. |
| `box_13_retirement_plan` | boolean, nullable | Always | Box 13, the retirement plan box, true when checked. |
| `box_13_third_party_sick_pay` | boolean, nullable | Always | Box 13, the third-party sick pay box, true when checked. |
| `box_14_other` | array of W2Box14Item | Always | Box 14, other, one entry per printed label and amount. |
| `box_14b_tipped_occupation_codes` | array of string | Always | Box 14b, Treasury tipped occupation codes, on a form that prints the box. |
| `state_rows` | array of W2StateRow | Always | Boxes 15 through 17, one row per state. |
| `local_rows` | array of W2LocalRow | Always | Boxes 18 through 20, one row per locality. |
| `omb_number` | string, nullable | Always | The OMB number printed on the form, 1545-0008 or 1545-0029. |
| `layout` | string, one of `irs_1up`, `irs_4up`, `substitute`, nullable | Always | The printing of the statement: irs\_1up, the IRS form with one statement per page; irs\_4up, the four-per-page sheet; substitute, a payroll or preparer print. |
| `source_pages` | array of integer | Always | The pages of the uploaded file the statement is printed on, counting from one; several when the upload repeats it. |
| `rescued_fields` | array of string | Always | The boxes whose figure was read from the page as a whole rather than from the box itself; empty when every figure was read from its box. |
| `forms_w2` | array of objects | Always | Every distinct statement the upload prints, one per employer, in document order; the first is the one at the top level. |
| `taxpayer_name` | string, nullable | Always | The employee's name printed in box e of the first statement. |
| `ssn_last4` | string, nullable | Always | The last four digits of the employee's social security number printed in box a of the first statement. |
### `data.forms_w2[]`
Form W-2, Wage and Tax Statement, one employer's statement of one employee's wages and withholding for one year.
| Key | Type | Present when | Description |
| --------------------------------- | ----------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `copy` | string, nullable | Always | The copy letter printed on the form (A, B, C, D, 1 or 2), when the print carries one. |
| `tax_year` | integer, nullable | Always | The tax year printed beside the form title. |
| `control_number` | string, nullable | Always | Box d, control number, as printed. |
| `employer_ein` | string, nullable | Always | Box b, employer identification number, masked to the last four digits. |
| `employer_name` | string, nullable | Always | Box c, the employer's name. |
| `employer_address` | string, nullable | Always | Box c, the employer's address below the name, on one line. |
| `employee_name` | string, nullable | Always | Box e, the employee's first name, initial and last name, as printed. |
| `employee_ssn_last4` | string, nullable | Always | Box a, the last four digits of the employee's social security number; the rest of the number is never served. |
| `box_1_wages` | string (money), nullable | Always | Box 1, wages, tips, other compensation. |
| `box_2_federal_tax_withheld` | string (money), nullable | Always | Box 2, federal income tax withheld. |
| `box_3_ss_wages` | string (money), nullable | Always | Box 3, social security wages. |
| `box_4_ss_tax_withheld` | string (money), nullable | Always | Box 4, social security tax withheld. |
| `box_5_medicare_wages` | string (money), nullable | Always | Box 5, Medicare wages and tips. |
| `box_6_medicare_tax_withheld` | string (money), nullable | Always | Box 6, Medicare tax withheld. |
| `box_7_ss_tips` | string (money), nullable | Always | Box 7, social security tips. |
| `box_8_allocated_tips` | string (money), nullable | Always | Box 8, allocated tips. |
| `box_10_dependent_care_benefits` | string (money), nullable | Always | Box 10, dependent care benefits. |
| `box_11_nonqualified_plans` | string (money), nullable | Always | Box 11, nonqualified plans. |
| `box_12` | array of W2Box12Item | Always | Box 12, one entry per printed code and amount, 12a through 12d. |
| `box_13_statutory_employee` | boolean, nullable | Always | Box 13, the statutory employee box, true when checked. |
| `box_13_retirement_plan` | boolean, nullable | Always | Box 13, the retirement plan box, true when checked. |
| `box_13_third_party_sick_pay` | boolean, nullable | Always | Box 13, the third-party sick pay box, true when checked. |
| `box_14_other` | array of W2Box14Item | Always | Box 14, other, one entry per printed label and amount. |
| `box_14b_tipped_occupation_codes` | array of string | Always | Box 14b, Treasury tipped occupation codes, on a form that prints the box. |
| `state_rows` | array of W2StateRow | Always | Boxes 15 through 17, one row per state. |
| `local_rows` | array of W2LocalRow | Always | Boxes 18 through 20, one row per locality. |
| `omb_number` | string, nullable | Always | The OMB number printed on the form, 1545-0008 or 1545-0029. |
| `layout` | string, one of `irs_1up`, `irs_4up`, `substitute`, nullable | Always | The printing of the statement: irs\_1up, the IRS form with one statement per page; irs\_4up, the four-per-page sheet; substitute, a payroll or preparer print. |
| `source_pages` | array of integer | Always | The pages of the uploaded file the statement is printed on, counting from one; several when the upload repeats it. |
| `rescued_fields` | array of string | Always | The boxes whose figure was read from the page as a whole rather than from the box itself; empty when every figure was read from its box. |
## `metadata`
How the file was read.
| Key | Type | Present when | Description |
| ------------------ | ----------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `form_key` | string | Always | The form's key, w2. |
| `detected_year` | integer, nullable | Always | The tax year the form was printed for. |
| `parent_form` | string, nullable | Always | Null on a form uploaded on its own. |
| `base_page` | integer | On a document where a Form W-2 was read; absent when none was. | The page of the uploaded file the form starts on, counting from zero. |
| `faces_read` | integer | Always | The number of statement faces printed across the upload, every copy counted, on a Form W-2. |
| `copies_collapsed` | integer | Always | The number of printed faces that repeat another face of the same statement, on a Form W-2. |
| `layout` | string, one of `irs_1up`, `irs_4up`, `substitute`, nullable | On a document where a Form W-2 was read; absent when none was. | The printing of the first statement on a Form W-2: irs\_1up, the IRS form with one statement per page; irs\_4up, the four-per-page sheet; substitute, a payroll or preparer print. |
| `w2_count` | integer | Always | The number of distinct statements the upload prints, one per employer, on a Form W-2. |
| `rescued_fields` | array of string | When the document states it | The boxes whose figure the page-level read supplied rather than the box itself, on a Form W-2; absent when every figure was read from its box. |
| `standalone` | boolean | When the document states it | True on a form uploaded on its own. |
## Shared objects
Object types that several keys above carry. The Type column names them.
### W2Box12Item
One box 12 entry of a Form W-2.
| Key | Type | Present when | Description |
| -------- | ------------------------ | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code` | string, nullable | Always | The one or two letter code printed beside the amount. |
| `amount` | string (money), nullable | Always | The amount printed for the code. |
| `slot` | string, nullable | When the document states it | The letter of the box 12 line the entry is printed on, a through d, when the form letters its box 12 lines; null when the form prints one box 12 caption. |
### W2Box14Item
One box 14 entry of a Form W-2.
| Key | Type | Present when | Description |
| -------- | ------------------------ | ------------ | ------------------------------------ |
| `label` | string, nullable | Always | The label the employer printed. |
| `amount` | string (money), nullable | Always | The amount printed beside the label. |
### W2LocalRow
One local row of a Form W-2, boxes 18 through 20.
| Key | Type | Present when | Description |
| -------------------- | ------------------------ | ------------ | ------------------------------- |
| `box_18_local_wages` | string (money), nullable | Always | Box 18, local wages, tips, etc. |
| `box_19_local_tax` | string (money), nullable | Always | Box 19, local income tax. |
| `box_20_locality` | string, nullable | Always | Box 20, locality name. |
### W2StateRow
One state row of a Form W-2, boxes 15 through 17.
| Key | Type | Present when | Description |
| -------------------- | ------------------------ | ------------ | ----------------------------------- |
| `state` | string, nullable | Always | Box 15, the state. |
| `employer_state_id` | string, nullable | Always | Box 15, employer's state ID number. |
| `box_16_state_wages` | string (money), nullable | Always | Box 16, state wages, tips, etc. |
| `box_17_state_tax` | string (money), nullable | Always | Box 17, state income tax. |
> The extracted Form W-2 record: the boxes of each wage and tax statement as the readers return them.