IRS Form W-2 - Wage and Tax State

Suggest Edits

IRS Form W-2, Wage and Tax Statement, is a form that employers must send to employees and the Social Security Administration (SSA) each year. It reports an employee's annual wages and the amount of taxes withheld from their paycheck, including federal, state, and other taxes. Employees use this form to file their federal and state tax returns.

To use the Upload PDF endpoint for this document, you must use W2 in the form_type parameter. To learn more about this document processing, see processing W2s.

Field descriptions

The following fields are available on this document type:

JSON Attribute	Data Type	Description
`year`	Integer	Year
`employeeSocialSecurityNumber`	Social Security Number	(Box A) Employee Social Security Number
`employerIdNo`	EIN	(Box B) Employer ID No. (EIN)
`wagesTipsOtherComp`	Money	(Box 1) Wages Tips Other Comp
`federalIncomeTaxWithheld`	Money	(Box 2) Federal Income Tax Withheld
`socialSecurityWages`	Money	(Box 3) Social Security Wages
`socialSecurityTaxWithheld`	Money	(Box 4) Social Security Tax Withheld
`medicareWagesAndTips`	Money	(Box 5) Medicare Wages And Tips
`medicareTaxWithheld`	Money	(Box 6) Medicare Tax Withheld
`employerName`	Text	(Box C) Employer Name
`employerAddressLine1`	Text	(Box C) Employer Address
`employerAddressLine2`	Text	(Box C) Employer Address
`employerAddressCity`	Text	(Box C) Employer Address
`employerAddressState`	State	(Box C) Employer Address
`employerAddressZip`	ZIP Code	(Box C) Employer Address
`employeeName`	Text	(Box E/F) Employee Name
`employeeAddressLine1`	Text	(Box E/F) Employee Address
`employeeAddressLine2`	Text	(Box E/F) Employee Address
`employeeAddressCity`	Text	(Box E/F) Employee Address
`employeeAddressState`	State	(Box E/F) Employee Address
`employeeAddressZip`	ZIP Code	(Box E/F) Employee Address
`socialSecurityTips`	Money	(Box 7) Social Security Tips
`allocatedTips`	Money	(Box 8) Allocated Tips
`box9`	Text	(Box 9)
`dependentCareBenefits`	Money	(Box 10) Dependent Care Benefits
`nonqualifiedPlans`	Money	(Box 11) Nonqualified Plans
`box12aCode`	Text	(Box 12a)
`box12aAmount`	Money	(Box 12a)
`box12bCode`	Text	(Box 12b)
`box12bAmount`	Money	(Box 12b)
`box12cCode`	Text	(Box 12c)
`box12cAmount`	Money	(Box 12c)
`box12dcode`	Text	(Box 12d)
`box12dAmount`	Money	(Box 12d)
`statutoryEmployee`	`CHECKED`, `UNCHECKED`	(Box13) Statutory Employee
`retirementPlan`	`CHECKED`, `UNCHECKED`	(Box13) Retirement Plan
`third-PartySickPay`	`CHECKED`, `UNCHECKED`	(Box13) Third-Party Sick Pay
`box14Other`	Text	(Box 14) Other
`statePrimary`	State	(Box 15) State
`stateSecondary`	State	(Box 15) State
`employerStateIdNumberPrimary`	Text	(Box 15) Employer state ID Number
`employerStateIdNumberSecondary`	Text	(Box 15) Employer state ID Number
`stateWagesTipsPrimary`	Money	(Box 16) State Wages Tips
`stateWagesTipsSecondary`	Money	(Box 16) State Wages Tips
`stateIncomeTaxPrimary`	Money	(Box 17) State Income Tax
`stateIncomeTaxSecondary`	Money	(Box 17) State Income Tax
`localWagesTipsPrimary`	Money	(Box 18) Local Wages Tips
`localWagesTipsSecondary`	Money	(Box 18) Local Wages Tips
`localIncomeTaxPrimary`	Money	(Box 19) Local Income Tax
`localIncomeTaxSecondary`	Money	(Box 19) Local Income Tax
`localityNamePrimary`	Text	(Box 20) Locality Name
`localityNameSecondary`	Text	(Box 20) Locality Name

Sample document

Coming soon...

Sample JSON result

{
  "status": 200,
  "response": {
    "pk": 16561616,
    "uuid": "10fa8ec9-2b3b-4937-bb6b-4bc7a6ae3593",
    "name": "W2 JSON Output",
    "created": "2022-02-08T00:18:18Z",
    "created_ts": "2022-02-08T00:18:18Z",
    "verified_pages_count": 1,
    "book_status": "ACTIVE",
    "id": 16561616,
    "forms": [
      {
        "pk": 34391430,
        "uuid": "958de4cf-54f1-4b06-bd11-ddca40933f78",
        "form_type": "W2",
        "raw_fields": {
          "box9": {
            "value": "",
            "is_empty": true,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "year": {
            "value": "2018",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "box12aCode": {
            "value": "",
            "is_empty": true,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "box12bCode": {
            "value": "",
            "is_empty": true,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "box12cCode": {
            "value": "",
            "is_empty": true,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "box12dcode": {
            "value": "",
            "is_empty": true,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "box14Other": {
            "value": "",
            "is_empty": true,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "box12aAmount": {
            "value": "",
            "is_empty": true,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "box12bAmount": {
            "value": "",
            "is_empty": true,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "box12cAmount": {
            "value": "",
            "is_empty": true,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "box12dAmount": {
            "value": "",
            "is_empty": true,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "employeeName": {
            "value": "DAVID P BECON",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "employerIdNo": {
            "value": "32-1203146",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "employerName": {
            "value": "WFH ENTERPRISES, INC.",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "statePrimary": {
            "value": "AL",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "allocatedTips": {
            "value": "",
            "is_empty": true,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "retirementPlan": {
            "value": "CHECKED",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "stateSecondary": {
            "value": "",
            "is_empty": true,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "nonqualifiedPlans": {
            "value": "",
            "is_empty": true,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "statutoryEmployee": {
            "value": "UNCHECKED",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "employeeAddressZip": {
            "value": "35570",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "employerAddressZip": {
            "value": "36330",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "socialSecurityTips": {
            "value": "450.00",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "third-PartySickPay": {
            "value": "UNCHECKED",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "wagesTipsOtherComp": {
            "value": "10000.00",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf",
            "validation_error": "Box 1 should be greater than 250 and less than 400000. User should verify document."
          },
          "employeeAddressCity": {
            "value": "HAMILTON",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "employerAddressCity": {
            "value": "ENTERPRISE",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "localityNamePrimary": {
            "value": "",
            "is_empty": true,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "medicareTaxWithheld": {
            "value": "740.00",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf",
            "validation_error": "Box 6 should be greater than 1.45% of Box 5 and less than 2.36% of Box 5. User should verify document."
          },
          "socialSecurityWages": {
            "value": "20000.00",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf",
            "validation_error": "Amount should be greater than Box 4 Social Security Tax Withheld. Maximum amount should 147000. User should verify document."
          },
          "employeeAddressLine1": {
            "value": "1706 MILITARY STREET SOUTH",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "employeeAddressLine2": {
            "value": "AVE 2506",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "employeeAddressState": {
            "value": "AL",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "employerAddressLine1": {
            "value": "600 BOLL WEEVIL CIRCLE",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "employerAddressLine2": {
            "value": "",
            "is_empty": true,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "employerAddressState": {
            "value": "AL",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "medicareWagesAndTips": {
            "value": "652.00",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf",
            "validation_error": "Amount should be greater than Box 6 Medicare Tax Withheld. User should verify document."
          },
          "dependentCareBenefits": {
            "value": "",
            "is_empty": true,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "localIncomeTaxPrimary": {
            "value": "30.00",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "localWagesTipsPrimary": {
            "value": "260.00",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "localityNameSecondary": {
            "value": "",
            "is_empty": true,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "stateIncomeTaxPrimary": {
            "value": "320.00",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "stateWagesTipsPrimary": {
            "value": "6520.00",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "localIncomeTaxSecondary": {
            "value": "",
            "is_empty": true,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "localWagesTipsSecondary": {
            "value": "",
            "is_empty": true,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "stateIncomeTaxSecondary": {
            "value": "",
            "is_empty": true,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "stateWagesTipsSecondary": {
            "value": "",
            "is_empty": true,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "federalIncomeTaxWithheld": {
            "value": "15000.00",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf",
            "validation_error": "Box 2 should be less than 37% of Box 1. User should verify document."
          },
          "socialSecurityTaxWithheld": {
            "value": "25000.00",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf",
            "validation_error": "Box 4 should be greater than 6.16% of Box 3 and less than 6.201% of Box 3 if Box 3 is less than or equal to 147000. Maximum amount should be 9114. User should verify document."
          },
          "employeeSocialSecurityNumber": {
            "value": "653-32-0120",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "employerStateIdNumberPrimary": {
            "value": "203-62-1230",
            "is_empty": false,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          },
          "employerStateIdNumberSecondary": {
            "value": "",
            "is_empty": true,
            "alias_used": null,
            "source_filename": "W2 Sample 1.pdf"
          }
        },
        "form_config_pk": 46033,
        "tables": []
      }
    ],
    "book_is_complete": true
  },
  "message": "OK"
}

Updated 10 months ago