GET
/
v1-preview
/
models
/
us-form-w2
/
{documentId}
from abbyy_document_ai import DocumentAi
import os


with DocumentAi(
    api_key_auth=os.getenv("DOCUMENTAI_API_KEY_AUTH", ""),
) as document_ai:

    res = document_ai.models.us_form_w2.get_extracted_fields(document_id="wh23anb5xjf0ntw5taase5qz")

    assert res.us_form_w2 is not None

    # Handle response
    print(res.us_form_w2)
{
  "meta": {
    "id": "wh23anb5xjf0ntw5taase5qz",
    "name": "document.jpg",
    "createdAt": "2025-02-07T17:44:06.949Z",
    "model": "us-form-w2",
    "status": "Processed",
    "pageCount": 10,
    "errors": [
      {
        "message": "Total is required"
      }
    ]
  },
  "fields": {
    "year": "2023",
    "boxAEmployeesSocialSecurityNumber": "123-45-6789",
    "boxBEmployerIdentificationNumberEin": "12-3456789",
    "boxCEmployersName": "ACME Corporation",
    "boxCEmployersAddress": "123 Business Ave, Suite 100",
    "boxDControlNumber": "123456",
    "boxEEmployeesName": "John A. Smith",
    "boxFEmployeesAddress": "456 Home Street",
    "box1WagesTipsOtherCompensation": 75000,
    "box2FederalIncomeTaxWithheld": 15000,
    "box3SocialSecurityWages": 75000,
    "box4SocialSecurityTaxWithheld": 4650,
    "box5MedicareWagesAndTips": 75000,
    "box6MedicareTaxWithheld": 1087.5,
    "box7SocialSecurityTips": 5000,
    "box8AllocatedTips": 0,
    "box9VerificationCode": "123456",
    "box10DependentCareBenefits": 5000,
    "box11NonqualifiedPlans": 0,
    "box12aCode": "D",
    "box12aAmount": 5000,
    "box12bCode": "E",
    "box12bAmount": 3000,
    "box12cCode": "F",
    "box12cAmount": 2000,
    "box12dCode": "G",
    "box12dAmount": 1000,
    "box13StatutoryEmployee": true,
    "box13RetirementPlan": true,
    "box13ThirdPartySickPay": false,
    "box14Other": "Additional information",
    "boxes1520": [
      {
        "box15EmployersStateIDNumber": "123456789",
        "box15State": "CA",
        "box16StateWagesTips": 75000,
        "box17StateIncomeTax": 5000,
        "box18LocalWagesTips": 75000,
        "box19LocalIncomeTax": 1000,
        "box20LocalityName": "San Francisco"
      }
    ]
  }
}

Authorizations

​
Authorization
string
header
required

Our API offers authentication via API keys. You can obtain an API key from https://developer.abbyy.com

Path Parameters

​
documentId
string
required

The id of the document

Response

200
application/json

Extracted US Form W2 Data Response

​
meta
object
required

Represents a document that has been submitted for processing.

Example:
{
  "id": "wh23anb5xjf0ntw5taase5qz",
  "name": "document.jpg",
  "createdAt": "2025-02-07T17:44:06.949Z",
  "model": "image-to-text",
  "status": "Processed",
  "pageCount": 10,
  "errors": [{ "message": "Total is required" }]
}
​
fields
object

Fields extracted from a US Form W-2

Example:
{
  "year": "2023",
  "boxAEmployeesSocialSecurityNumber": "123-45-6789",
  "boxBEmployerIdentificationNumberEin": "12-3456789",
  "boxCEmployersName": "ACME Corporation",
  "boxCEmployersAddress": "123 Business Ave, Suite 100",
  "boxDControlNumber": "123456",
  "boxEEmployeesName": "John A. Smith",
  "boxFEmployeesAddress": "456 Home Street",
  "box1WagesTipsOtherCompensation": 75000,
  "box2FederalIncomeTaxWithheld": 15000,
  "box3SocialSecurityWages": 75000,
  "box4SocialSecurityTaxWithheld": 4650,
  "box5MedicareWagesAndTips": 75000,
  "box6MedicareTaxWithheld": 1087.5,
  "box7SocialSecurityTips": 5000,
  "box8AllocatedTips": 0,
  "box9VerificationCode": "123456",
  "box10DependentCareBenefits": 5000,
  "box11NonqualifiedPlans": 0,
  "box12aCode": "D",
  "box12aAmount": 5000,
  "box12bCode": "E",
  "box12bAmount": 3000,
  "box12cCode": "F",
  "box12cAmount": 2000,
  "box12dCode": "G",
  "box12dAmount": 1000,
  "box13StatutoryEmployee": true,
  "box13RetirementPlan": true,
  "box13ThirdPartySickPay": false,
  "box14Other": "Additional information",
  "boxes1520": [
    {
      "box15EmployersStateIDNumber": "123456789",
      "box15State": "CA",
      "box16StateWagesTips": 75000,
      "box17StateIncomeTax": 5000,
      "box18LocalWagesTips": 75000,
      "box19LocalIncomeTax": 1000,
      "box20LocalityName": "San Francisco"
    }
  ]
}
​
validationErrors
object[]

An array of validation errors that occurred while processing the document. These typically do not prevent field extraction, but rather indicate issues extracting key fields.

Was this page helpful?