Docyield's W-2 parser reads a US Wage and Tax Statement — scanned, photographed, or supplied as a PDF — and returns its boxes as clean, structured data. A W-2 reports an employee's annual wages and the taxes withheld from them, and it is one of the most rigidly laid-out documents in American payroll: numbered boxes, fixed labels, and the same fields every year. The parser captures the tax year, the employee and employer identities, and the dollar amounts from the key boxes, then hands them back as JSON, CSV, or Excel.
The catch is that the rigid layout exists on the official form, not on every copy that crosses your desk. W-2s arrive as employer-printed PDFs, payroll-portal exports, faded photocopies, and phone photos of the paper Copy B an employee was handed. The box positions shift slightly between vendors, and a scan can skew or blur the small print. Docyield reads the form by its box meaning — Box 1 is wages, Box 2 is federal withholding — so it stays aligned even when the printout is not the pristine IRS template.
What a W-2 reports
A W-2 summarises a single employee's earnings and tax withholding for one tax year from one employer. The identity fields anchor it: the tax year, the employee's name and Social Security Number, and the employer's name and Employer Identification Number (EIN). The financial boxes then break down the money. Box 1 carries taxable wages, tips, and other compensation, while Box 2 carries the federal income tax withheld against them.
The remaining boxes the parser captures cover the payroll-tax detail: Boxes 3 and 4 for Social Security wages and the tax withheld, Boxes 5 and 6 for Medicare wages and tax, and Boxes 16 and 17 for state wages and state income tax. Together these are the figures that flow onto a tax return and into payroll reconciliations, which is why getting them into a structured form matters.
Why structured extraction beats keying boxes by hand
Typing W-2 boxes into tax software or a spreadsheet is precise, repetitive work, and the precision is the problem: transposing two digits in Box 1 or putting a Box 4 figure where Box 2 belongs produces a return that does not reconcile. Doing it across a workforce, or across a season of client returns, multiplies the chance of a slip.
Pulling each box into a named, typed field removes the manual step and the box-confusion that comes with it. Because the output maps Box 1 to a wages field and Box 2 to a federal-withholding field on every form, the numbers go where they belong without anyone matching label to value by eye. Amounts come back as numbers, so totals and cross-checks work immediately.
Who uses a W-2 parser
- Tax preparers and CPA firms entering client W-2s into filing software during tax season.
- Payroll teams reconciling issued W-2s against payroll records at year end.
- Bookkeepers digitising employee tax forms into accounting or spreadsheet systems.
- Lenders and verification services reading reported wages from a borrower's W-2.
- HR and onboarding teams capturing prior-employer wage and withholding details.
- Developers adding W-2 capture to a tax or payroll product through the API.
Box numbers and why they keep things unambiguous
The W-2's numbered boxes are its great advantage for extraction. Unlike a free-form invoice where "total" might be labelled three different ways, a W-2 has Box 1 mean the same thing on every form in the country. The parser leans on that, mapping each captured amount to the box it came from so the meaning is never in doubt.
This also helps with the figures people most often confuse. Social Security wages (Box 3) frequently differ from taxable wages (Box 1) because of pre-tax deductions, and federal withholding (Box 2) is not the Social Security tax (Box 4). Keeping each in its own field preserves those distinctions instead of flattening them into one "tax" number.
Accuracy, sensitive data, and review
No parser reads every form perfectly, and tax work is exactly where the honest cases matter. Accuracy is highest on clean, flat scans and native PDFs; a creased photocopy or an angled phone photo of the small box print is where a digit can be misread. A sharper image is the simplest fix. Any figure that lands on a filed return is worth a quick check against the source, and the parser keeps the original document beside the extracted values so that is fast.
A W-2 contains sensitive personal data — a Social Security Number and earnings. Where a box is blank on the form, the field comes back empty rather than filled with a guessed amount, since a fabricated figure on a tax document is far worse than a gap. This describes data extraction only and is not tax or legal advice; the figures should be reviewed before any return is filed.
Output formats, API, and batch
Each parse exports as JSON, CSV, Excel, or XML from the same result. CSV and Excel suit a preparer building a worksheet of client wages and withholdings; JSON suits a tax or payroll integration; XML fits an older filing or back-office import. The free tool handles one W-2 at a time.
When a firm processes many W-2s at once — a payroll year-end run or a tax-season intake — the Docyield API and batch dashboard run the same extraction at scale, return results by webhook, and let you apply your own validation, such as checking that withholding never exceeds wages. The field names are identical between the free tool and the API.
What the W-2 parser extracts
Each W-2 is returned against a fixed schema mapped to the form's boxes. Boxes that are blank on the form come back empty rather than guessed.
- Tax year
- The tax year the W-2 reports.
- Employee name
- The employee's full name.
- Employee SSN
- The employee's Social Security Number.
- Employer name
- The employer's name.
- Employer EIN
- The Employer Identification Number.
- Wages (Box 1)
- Wages, tips, and other compensation.
- Federal income tax withheld (Box 2)
- Federal income tax withheld.
- Social Security wages (Box 3)
- Wages subject to Social Security tax.
- Social Security tax withheld (Box 4)
- Social Security tax withheld.
- Medicare wages (Box 5)
- Wages and tips subject to Medicare tax.
- Medicare tax withheld (Box 6)
- Medicare tax withheld.
- State wages (Box 16)
- Wages reported to the state.
- State income tax (Box 17)
- State income tax withheld.
How to convert a W-2 to JSON, CSV, or Excel
- 1Upload your W-2 — drop a scan, photo, or PDF of the form onto the box above, or choose a file.
- 2Wait a few seconds while Docyield reads the form and maps each numbered box to its field.
- 3Review the structured result, checking the dollar amounts against the original boxes.
- 4Pick your output tab — JSON, CSV, Excel, or XML.
- 5Copy the result or download the file, ready for your tax software, payroll system, or spreadsheet.
Frequently asked questions
Processing documents at scale?
Batch upload, an extraction API, and webhooks for 100+ documents a month.