Skip to main content
Migrating from v1.7.3 to v2.0 View the migration guide for a full breakdown of what's changed and how to update your integration. View Migration Guide
Version: 2.0

Overview

Form W-2 is used by Employers to report annual Wages and the taxes withheld from an Employee's paycheck to the Social Security Administration (SSA). The TaxBandits API 2.0 lets you create, update, retrieve, validate and ultimately e-file these returns programmatically.

Supported Tax Years​

API 2.0 supports e-filing of Form W-2 for the following tax years:

Tax YearAPI Version
2026v2
2025v2, v1.7.3
2024v1.7.3

What's New for 2026 Tax Year​

To support the new reporting requirements introduced by the One Big Beautiful Bill Act (OBBBA), the W-2 payload for TY 2026 introduces new fields and Box 12 codes inside the W2FormData object. These are accepted only when SubmissionManifest.TaxYear is "2026":

  • TTOC1 — Treasury Tipped Occupation Code #1 (required when Box 12 Code TT is reported).
  • TTOC2 — Treasury Tipped Occupation Code #2 (optional secondary code).
  • Box 12 Code TT — Cash Tips reported for the Employee (supports No-Tax-on-Tips reporting).
  • Box 12 Code TP — Qualified Overtime Compensation (supports No-Tax-on-Overtime reporting).
  • Box 12 Code TA — Employer contributions to Trump Accounts (TY 2026 OBBBA addition).

Box 12 codes TT, TP and TA and the TTOC1 / TTOC2 fields are accepted only when TaxYear is "2026". They will be ignored on TY 2025 / TY 2024 submissions.

Refer to the Treasury Tipped Occupation Codes dictionary for the list of valid TTOC values, and to the Box 12 Codes dictionary for the full code list.

Endpoint Summary​

EndpointMethodDescription
FormW2/CreatePOSTCreates one or more Form W-2 returns in a single submission.
FormW2/UpdatePOSTUpdates an existing W-2 submission (before transmission).
FormW2/GetGETRetrieves the data of an existing W-2 submission and its records.
FormW2/ValidatePOSTValidates a W-2 payload against business and SSA rules without persisting it.