W-2s OCR API

Nobody wants to type a W-2. This API securely reads the form and returns wages, withholdings, EIN, SSN, and Box 12 codes as JSON ready for tax engines, income verification, and payroll checks.

Get Started for Free Free Demo
W-2s OCR API

Why Veryfi

POST /api/v8/partner/w2s · Live

W-2 in. JSON out.

Veryfi’s W-2 OCR API reads IRS Form W-2 (Wage and Tax Statement) and returns employee, employer, wage, and withholding fields as JSON via POST /api/v8/partner/w2s. Teams plug that payload into tax prep, payroll, mortgage income verification, benefits, insurance, and FAFSA workflows instead of keying Box 1–20 by hand. See supported W-2 fields and the Process a W-2 docs.

0 fields snapping into JSON

What is a W-2?

Form W-2, Wage and Tax Statement, is the IRS form employers file each year for every employee. It reports Box 1 wages, federal and FICA withholdings, employer EIN, employee SSN, Box 12 codes, Box 13 checkboxes, and state and local Boxes 15–20.

Employees use Copy B to file a 1040. SSA gets Copy A. Tax software, payroll, lenders, benefits, and FAFSA workflows need those same boxes as structured data — which is what the API above returns as JSON.

What is W-2 OCR?

W2 OCR, or Optical Character Recognition, is a technology that enables the automated extraction of data from W2 forms. W2 forms are an essential document that employees receive from their employers each year, which outlines their earnings and taxes paid. W2 OCR technology has revolutionized the way this information is processed by automating the manual data entry process, reducing errors, and increasing efficiency. With W2 OCR, businesses can quickly and accurately process W2 forms in bulk, reducing the time and effort required to input the data manually. This technology has also enabled the integration of W2 data into various software systems, making it easier for businesses to manage their tax-related processes.

In addition to its efficiency benefits, W2 OCR technology has also improved data security by reducing the need for human interaction with sensitive financial information. W2 forms contain confidential information such as social security numbers and tax withholdings, which can be compromised if handled incorrectly. With W2 OCR, the data is extracted and processed without any manual intervention, reducing the risk of errors and data breaches. Overall, W2 OCR technology has become an essential tool for businesses looking to streamline their tax-related processes while maintaining the highest levels of accuracy and security.

Request: W-2 Data Extraction
import requests
url = "https://api.veryfi.com/api/v8/partner/w2s"
headers = {
'CLIENT-ID': '<API_KEY_VALUE>',
'AUTHORIZATION': 'apikey <USERNAME_VALUE>:<API_KEY_VALUE>'
}
payload = {'file_url': 'https://cdn…'}
response = requests.post(url, headers=headers, data=payload)
print(response.json())
Response: Structured JSON
{
“employer_name”: “BESTEST HOSPITAL EVER, INC.”,
“employer_address”: “123 PAYNE LANE\nPOSTCALL, NY 11111”,
“ein”: “46-1234567”,
“employee_name”: “DOCTORED B. MONEY”,
“employee_address”: “80 WORKHOURS WAY\nSLEEPLESS HOLLOW, NY 11222”,
“employee_ssn”: “123-45-6879”,
“wages_other_comps”: 55000,
“federal_income_tax”: 4000,
“ss_wages”: 60000,
“ss_tax”: 3720,
“medicare_wages”: 60000,
“medicare_tax”: 870,
“states”: [
{
“state”: “NY”,
“state_wages_tips”: 60000,
“state_income_tax”: 1500,
“local_wages_tips”: 60000,
“local_income_tax”: 500,
“locality_name”: “NYC”
}
]
}

Developer Friendly API

The only API you will ever need to accurately extract key/value data in a standardized format you can trust across any geography, language, or format — enabling seamless international business expansion without lifting a finger.

Day-1 Ready Pre-Trained W-2 AI Model
SDKs & code samples in Python, Node.js, PHP, C#, Java, Go and more
Detailed API Docs + FAQs that make sense
Human support from experts at HQ in Silicon Valley

No bullshit. No months of training. No “contact sales” gatekeeping. Start impressing your customers today.

Free Demo
Read API Docs

SOC 2 Type II · Live

Global Bank-Grade Security & Compliance

Veryfi SOC 2 Type II compliant Certified seal

SOC 2 Type II

CERT · VERIFIED

Certified. GDPR, CCPA, and ITAR compliant.

HIPAA Compliance

HIPAA · BAA

We sign BAAs. PHI handled under HIPAA safeguards.

99.995% Uptime SLA

SLA · SAMPLED

Dedicated NVIDIA DGX — not shared cloud GPUs.

Deployment Flexibility

REGION · READY

Cloud API, hybrid, or on-premise when required.

GDPR

GDPR · READY

EU data protection. Lawful processing and subject rights.

Audit Trail

API · LOGGED

Every API call logged and timestamped for regulators.

Built for the banks that can’t afford “good enough.”

Supported Fields

IRS Form W-2 (Wage and Tax Statement) boxes extracted as JSON from POST /api/v8/partner/w2s, including handwriting and Box 13 checkbox comprehension.

  • Basic Information
    • Employee name (Box E)
      employee_name
      Employee name is the person who earned the wages. It is the name that must match the Social Security number on this form.What it is
      • The worker’s full name, as the employer reported it
      • Not the employer, and not a dependent listed elsewhere
      • Used to file the return and to match IRS wage records
      Where to find it
      • Box e, under the employer block
      • Often last name, first name, and middle initial
      Read it with
      • SSN (Box a), which must belong to this person
      • Employee address (Box f)
      DOCTORED B. MONEY
    • Employee address (Box F)
      employee_address
      Employee address is where the worker lived or received mail when the employer issued the W-2.What it is
      • Street, city, state, and ZIP for the employee
      • A mailing address, not proof of the work location
      • Separate from the employer’s address in Box c
      Where to find it
      • Box f, directly under the employee name
      Read it with
      • Employee name (Box e)
      80 WORKHOURS WAY, SLEEPLESS HOLLOW, NY 11222
    • SSN (Box A)
      employee_ssn
      The Social Security number identifies the employee to the Social Security Administration and the IRS.What it is
      • Nine digits, usually printed as XXX-XX-XXXX
      • Belongs to the employee, not the employer
      • A wrong or truncated SSN is a reason to review the form before filing
      Where to find it
      • Box a, at the top left of the form
      Read it with
      • Employee name (Box e)
      • EIN (Box b), which identifies the employer instead
      123-45-6879
    • Employer name (Box C)
      employer_name
      Employer name is the business that paid the wages and filed this W-2.What it is
      • The legal or trade name printed by the payer
      • Not the employee’s name
      • The same employer can issue more than one W-2 in a year
      Where to find it
      • Box c, above the employee name
      Read it with
      • EIN (Box b)
      • Employer address, in the same box
      BESTEST HOSPITAL EVER, INC.
    • Employer address (Box C)
      employer_address
      Employer address is the address the payer printed with its name in Box c.What it is
      • The employer’s street, city, state, and ZIP
      • Not the employee’s home address in Box f
      • May be a payroll office rather than the worksite
      Where to find it
      • Box c, under the employer name
      Read it with
      • Employer name
      • EIN (Box b)
      123 PAYNE LANE, POSTCALL, NY 11111
    • EIN (Box B)
      ein
      The employer identification number is the IRS number for the business that paid the wages.What it is
      • Nine digits, usually printed as XX-XXXXXXX
      • Identifies the employer, not the employee
      • Box b. It is not a verification code
      Where to find it
      • Box b, next to the employee’s SSN
      Read it with
      • SSN (Box a), which identifies the worker
      • Employer name (Box c)
      46-1234567
    • Control number (Box D)
      control_number
      The control number is an optional code the employer’s payroll system assigns to this W-2.What it is
      • Used by the employer to match the form in their own records
      • Often blank. A blank box is normal
      • Not a tax amount and not the EIN
      Where to find it
      • Box d, near the employer identification number
      Read it with
      • EIN (Box b)
      0045821
    • Learn more …
  • Wage and Tax Information
    • Wages, tips, other compensation (Box 1)
      wages_other_comps
      Box 1 is the taxable wages, tips, and other compensation to report as income on the federal return.What it is
      • Federal taxable wages, not every dollar the employer paid
      • Already reduced by pre-tax items such as many 401(k) deferrals
      • The starting point for federal income tax, not for Social Security tax
      Where to find it
      • Box 1, the first numbered box
      Read it with
      • Federal income tax withheld (Box 2)
      • Social Security wages (Box 3), which can be higher
      55,000.00
    • Federal income tax withheld (Box 2)
      federal_income_tax
      Box 2 is the federal income tax the employer withheld and sent to the IRS.What it is
      • Withholding, not the tax the employee finally owes
      • Can be higher or lower than the tax on the return
      • A dollar amount, not a wage
      Where to find it
      • Box 2, beside Box 1
      Read it with
      • Wages (Box 1)
      4,000.00
    • Social Security wages (Box 3)
      ss_wages
      Box 3 is the wages subject to Social Security tax, up to the annual wage base.What it is
      • Often higher than Box 1 because some pre-tax deductions still count here
      • Stops at the Social Security wage cap for the year
      • Does not include amounts over that cap
      Where to find it
      • Box 3
      Read it with
      • Social Security tax withheld (Box 4)
      • Social Security tips (Box 7)
      60,000.00
    • Social Security tax withheld (Box 4)
      ss_tax
      Box 4 is the Social Security tax withheld from the employee, generally 6.2 percent of Social Security wages.What it is
      • The employee share only. The employer match is not on this form
      • Should track Box 3 up to the wage base
      • Not Medicare tax
      Where to find it
      • Box 4, beside Box 3
      Read it with
      • Social Security wages (Box 3)
      • Medicare tax withheld (Box 6)
      3,720.00
    • Medicare wages and tips (Box 5)
      medicare_wages
      Box 5 is wages and tips subject to Medicare tax. There is no wage cap.What it is
      • Usually at least as high as Box 3
      • Includes tips reported to the employer
      • The base for both regular Medicare tax and Additional Medicare Tax
      Where to find it
      • Box 5
      Read it with
      • Medicare tax withheld (Box 6)
      • Social Security wages (Box 3)
      60,000.00
    • Medicare tax withheld (Box 6)
      medicare_tax
      Box 6 is the Medicare tax withheld, generally 1.45 percent, plus 0.9 percent Additional Medicare Tax when wages pass the threshold.What it is
      • The employee share withheld by the employer
      • Can be higher than 1.45 percent of Box 5 when Additional Medicare Tax applies
      • Not Social Security tax
      Where to find it
      • Box 6, beside Box 5
      Read it with
      • Medicare wages and tips (Box 5)
      870.00
    • Social Security tips (Box 7)
      ss_tips
      Box 7 is tips the employee reported to the employer that are subject to Social Security tax.What it is
      • Reported tips, not the allocated tips in Box 8
      • Included in the Social Security picture along with Box 3
      • Blank when the job has no tipped wages
      Where to find it
      • Box 7
      Read it with
      • Social Security wages (Box 3)
      • Allocated tips (Box 8)
      0.00
    • Allocated tips (Box 8)
      allocated_tips
      Box 8 is tips the employer allocated to the employee, usually in a large food or beverage establishment.What it is
      • An assigned amount, not tips the employee already reported
      • Not included in Boxes 1, 3, 5, or 7
      • Blank for most jobs
      Where to find it
      • Box 8
      Read it with
      • Social Security tips (Box 7), which are the tips the employee did report
      0.00
    • Advance EIC payment (Box 9)
      advance_eic_payment
      Box 9 is the advance earned income credit an employer paid on older W-2s. Current forms no longer use it.What it is
      • A historical box. Employers stopped advancing the EIC after 2010
      • Often blank, or absent, on a modern W-2
      • Not wages and not federal withholding
      Where to find it
      • Box 9, when the form still prints it
      • Older copies of the form. Do not expect it on a current-year W-2
      Read it with
      • Federal income tax withheld (Box 2)
      0.00
    • Learn more …
  • Additional Information
    • Dependent care benefits (Box 10)
      dependent_care_benefits
      Box 10 is dependent care benefits the employer provided or paid, such as a dependent care flexible spending account.What it is
      • The amount paid into or from a dependent care benefit
      • May be taxable above the exclusion limit
      • Not the child tax credit
      Where to find it
      • Box 10
      Read it with
      • Wages (Box 1) if any taxable portion was included there
      0.00
    • Nonqualified plans (Box 11)
      non_qualified_plans
      Box 11 is distributions from a nonqualified deferred compensation plan, or amounts deferred that are taxable this year.What it is
      • Employer-sponsored deferred pay that does not qualify for normal retirement-plan treatment
      • Can be a distribution or a taxable deferral, depending on the year
      • Not a 401(k) elective deferral. Those usually appear in Box 12
      Where to find it
      • Box 11
      Read it with
      • Box 12, for qualified plan codes such as D
      • Wages (Box 1)
      0.00
    • Box 12 codes and amounts
      field_12a_col1
      Box 12 holds up to four coded amounts. Each letter explains a different kind of pay or benefit, and the number next to it is the amount.What it is
      • Returned as four pairs: field_12a through field_12d, each with a code column and an amount column
      • Codes include D for 401(k), W for HSA, C for group-term life, and DD for employer health coverage
      • Unprinted rows come back empty. Four slots do not mean four codes were used
      Where to find it
      • Box 12, lettered 12a, 12b, 12c, and 12d
      • The code is the letter. The amount is the figure beside it
      Read it with
      • Box 1 and Box 3, because some codes are already included in wages and some are not
      D 5,000.00
    • Statutory employee, retirement plan, and third-party sick pay (Box 13)
      Box 13 is three checkboxes. Each one is its own true or false value, listed again under Checkbox Comprehension.What it is
      • is_13a is statutory employee
      • is_13b is retirement plan
      • is_13c is third-party sick pay
      • Unchecked is false. A mark is true
      Where to find it
      • Box 13, the row of three boxes under Box 12
      Stays separate from
      • The Checkbox Comprehension group, which explains each flag on its own
      false, true, false
    • Other information (Box 14)
      field_14_other
      Box 14 is other tax information that does not fit a numbered box, such as union dues, state disability, or a vehicle allowance.What it is
      • A list of labels and amounts, field_14_other rows with a description and a value
      • The label is whatever the employer printed. It is not a fixed IRS code
      • Several lines can appear on one W-2
      Where to find it
      • Box 14, under the Box 12 and Box 13 area
      Read it with
      • Box 12, which uses IRS letter codes instead of free-text labels
      SDI 31.20
    • Learn more …
  • State and Local Tax Information
    • State (Box 15)
      states[].state
      State is the two-letter code for the state that taxed these wages.What it is
      • A postal abbreviation such as CA or NY
      • One W-2 can have more than one state row
      • Returned on each object in states
      Where to find it
      • Box 15, the state column in the state and local block
      Read it with
      • Employer state ID, in the same box
      • State wages (Box 16) and state income tax (Box 17)
      NY
    • Employer state ID (Box 15)
      states[].employer_state_id
      The employer state ID is the state account number the employer uses to file withholding in that state.What it is
      • The employer’s state withholding account, not the employee’s SSN
      • Format depends on the state
      • Printed in Box 15 next to the state code
      Where to find it
      • Box 15, beside the state abbreviation
      Read it with
      • EIN (Box b), the federal employer number
      • State (Box 15)
      123456789
    • State wages, tips, etc. (Box 16)
      states[].state_wages_tips
      Box 16 is the wages this state treats as taxable.What it is
      • State taxable wages for the row’s state
      • Can differ from Box 1 when the state starts from a different wage
      • One amount per state row
      Where to find it
      • Box 16, in the state row
      Read it with
      • State (Box 15)
      • State income tax (Box 17)
      60,000.00
    • State income tax (Box 17)
      states[].state_income_tax
      Box 17 is the income tax withheld for the state in that row.What it is
      • State withholding, not federal withholding
      • Pairs with the wages in Box 16
      • Zero is valid when the state has no wage tax
      Where to find it
      • Box 17, beside state wages
      Read it with
      • Federal income tax withheld (Box 2)
      • State wages (Box 16)
      1,500.00
    • Local wages, tips, etc. (Box 18)
      states[].local_wages_tips
      Box 18 is wages taxable by a city, county, or other locality.What it is
      • Local taxable wages, not state wages
      • Blank when the address has no local wage tax
      • One amount per local row
      Where to find it
      • Box 18
      Read it with
      • Local income tax (Box 19)
      • Locality name (Box 20)
      60,000.00
    • Local income tax (Box 19)
      states[].local_income_tax
      Box 19 is the local income tax withheld for the locality named in Box 20.What it is
      • City or county withholding
      • Not state tax and not federal tax
      • Blank when Box 18 is blank
      Where to find it
      • Box 19
      Read it with
      • Local wages (Box 18)
      • Locality name (Box 20)
      500.00
    • Locality name (Box 20)
      states[].locality_name
      Box 20 names the city, county, or school district that the local wages and tax belong to.What it is
      • A place name, such as NYC or a school-district code
      • Tells you which local return the Box 18 and Box 19 amounts belong on
      • Can be a string or a list when the form prints more than one
      Where to find it
      • Box 20, at the end of the state and local row
      Read it with
      • Local wages (Box 18)
      • Local income tax (Box 19)
      NYC
    • Learn more …
  • Checkbox Comprehension
    • Statutory employee (Box 13)
      is_13a
      Statutory employee is the first Box 13 checkbox. It is true when the worker is treated as an employee for Social Security and Medicare but can report expenses on Schedule C.What it is
      • True when the statutory employee box is marked
      • A withholding status, not a wage amount
      • Most W-2s leave it unchecked
      Where to find it
      • Box 13, the first checkbox
      Read it with
      • Retirement plan and third-party sick pay, the other two Box 13 flags
      false
    • Retirement plan (Box 13)
      is_13b
      Retirement plan is the second Box 13 checkbox. It is true when the employee was an active participant in an employer retirement plan.What it is
      • True when the retirement plan box is marked
      • Affects whether a traditional IRA deduction is limited
      • Not the 401(k) dollar amount. That amount is usually a Box 12 code
      Where to find it
      • Box 13, the middle checkbox
      Read it with
      • Box 12 code D or a similar deferral code, for the dollars
      true
    • Third-party sick pay (Box 13)
      is_13c
      Third-party sick pay is the third Box 13 checkbox. It is true when the employee received sick pay from an insurer or other third party.What it is
      • True when that box is marked
      • The payer may be an insurance company rather than the employer
      • The wages may still be included in Box 1
      Where to find it
      • Box 13, the last checkbox
      Read it with
      • Wages (Box 1)
      • Federal income tax withheld (Box 2)
      false
    • Learn more …

Try W-2 Data Extraction

Use Cases

Same POST /api/v8/partner/w2s payload, different workflows. Jump from a card or start with what Veryfi extracts from a W-2.

Frequently Asked Questions

  • What is a W-2 OCR API?

    A W-2 OCR API accepts an image or PDF of IRS Form W-2 and returns labeled fields (wages, withholdings, EIN, SSN, state boxes) as JSON. Veryfi exposes this as POST /api/v8/partner/w2s.

  • Which W-2 boxes does Veryfi extract?

    The model covers employee and employer identity (Boxes A–F), Boxes 1–9 wages and tax (Box 9 is Advance EIC on older W-2s), Boxes 10–14 extras and codes, Box 13 checkboxes, and state/local Boxes 15–20. Full list: supported W-2 fields.

  • Can I use W-2 OCR for mortgage or lending income verification?

    Yes. Lenders send borrower W-2s to the same endpoint and use Box 1 wages, employer, and multi-year extracts for income and DTI. See W-2 OCR for mortgage and lending.

  • Does W-2 OCR work for FAFSA?

    Yes. Extract family wages and tax withheld from uploaded W-2s and map them into aid forms. See W-2 OCR for FAFSA and student aid.

  • Related tax-form APIs

    W-9 OCR API, W-8BEN-E OCR API. Start from the W-2 API reference or a 14-day trial.

Full FAQ Discover More