The W-2 object | SpreadSpace

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

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.