w2.md

name	w2
schema	W2
version	1
mime_types	application/pdf image/jpeg image/png
filename_patterns	*w2* *w-2* *wage* *tax-statement*
classification_hints	US IRS Wage and Tax Statement form Contains 'W-2', 'Wage', 'Tax', 'EIN', 'SSN' keywords Has boxes labeled '1 Wages', '2 Federal income tax withheld', etc.

W-2 Wage and Tax Statement

Fields

• employee_name — the employee's full legal name (Box e).
• employee_ssn_last4 — last 4 digits of SSN, only (NEVER the full SSN). W-2s in the wild often redact the full SSN; capture the masked form.
• employer_name — the company's legal name.
• employer_ein — Employer Identification Number (Box b). Format: XX-XXXXXXX.
• tax_year — calendar year the wages were earned (Box 1 context).
• wages_tips_compensation — Box 1 amount (taxable wages).
• federal_income_tax_withheld — Box 2 amount.
• social_security_wages — Box 3 amount.
• social_security_tax_withheld — Box 4 amount.
• medicare_wages — Box 5 amount.
• medicare_tax_withheld — Box 6 amount.

Common mistakes

• NEVER extract a full SSN. US law (and py-idp's safety policy) requires only the last 4 digits. If the form shows a full 9-digit SSN, truncate to the last 4 and leave a validation_errors note.
• Box 1 ≠ Box 3. Box 1 is taxable wages (federal); Box 3 is Social Security wages (capped). Don't conflate.
• EIN is NOT SSN. EIN is 9 digits with a dash after the 2nd digit; SSN is 9 digits with dashes after 3rd and 5th.