Employee Tax Statements

Overview

The Employee Tax Statements API provides a modern replacement for the Get W-2 Preview Report API.

Migration Timeline:

Through 2025: Both APIs will work
Starting 2026: The W-2 Preview Report API will no longer return data

What This API Enables

The Employee Tax Statements API offers significant improvements over the W-2 Preview Report:

Complete Visibility: Track the full lifecycle of W-2 and W-2C documents, from draft through publication, including amendment history
Enhanced Integration: Connect seamlessly with Check's filing and document ecosystem through associated filings and document endpoints
Bulk Processing: Generate previews and download documents for multiple employees simultaneously via Tax Packages

Key concepts

Employee Tax Statements

W-2 and W-2C documents that show:

Current and future tax documents Check will file
Already submitted documents
Filing dates and amendment history
Relationships between employee documents and company filings

Documents

Individual tax documents that reflect the actual data Check filed with tax agencies.

Tax Packages

ZIP files containing employee tax documents (and, optionally, employer copies of company filings) as PDFs. A package requested with at least one employee tax statement also contains a CSV of that statement data. See the Tax Packages guide for details.

API Reference

Employee Tax Statement Object

The core object representing an employee's tax document.

field	type	description
`id`	ID	ID of the employee tax statement
`employee`	ID	ID of the employee this statement belongs to
`company`	ID	ID of the company this statement belongs to
`year`	int	Tax year for this statement
`amends`	nullable ID	Previous statement this one amends (if applicable). If populated, this means this statement is an amendment.
`amended_by`	nullable ID	Newer statement that amends this one (if applicable)
`document`	nullable ID	Filed document ID (null if not yet filed)
`filings`	list of IDs	Company filings that include this employee data
`published_at`	nullable datetime in UTC	When the document was published (UTC)
`publication_status`	enum	Publication status: `draft`, `published`, or `pending_correction`
`delivery_method`	enum	Delivery method: `manual` or `mail`
`mail_recipient`	nullable enum	Mail recipient: `employee` or `company`. Null if manual delivery.

Key Point: When document is null, the statement hasn't been published yet. You can generate previews by creating a tax package.

List Employee Tax Statements

GET /employee_tax_statements

Returns W-2 and W-2C statements matching the specified filters.

Query Parameters

parameter	type	description
`company`	ID	Filter by company ID
`employee`	ID	Filter by employee ID
`publication_status`	enum (optional)	Filter by publication status: `draft`, `published`, or `pending_correction`
`type`	enum (optional)	Filter by type: `original` or `amendment`

Example Requests

GET /employee_tax_statements?employee=emp_123
GET /employee_tax_statements?company=com_123&publication_status=draft
GET /employee_tax_statements?company=com_123&publication_status=published
GET /employee_tax_statements?company=com_123&type=original

Example Response

[
  {
    "id": "ets_789",
    "employee": "emp_123",
    "company": "com_123",
    "year": 2025,
    "amends": null,
    "amended_by": null,
    "document": null,
    "filings": ["com_fil_999"],
    "filed_at": null,
    "published_at": null,
    "publication_status": "draft",
    "delivery_method": "manual",
    "mail_recipient": null
  },
  {
    "id": "ets_456",
    "employee": "emp_123",
    "company": "com_123",
    "year": 2024,
    "amends": "ets_123",
    "amended_by": null,
    "document": "doc_456",
    "filings": ["com_fil_789", "com_fil_888"],
    "filed_at": "2025-02-10T15:30:00Z",
    "published_at": "2025-02-10T15:30:00Z",
    "publication_status": "published",
    "delivery_method": "mail",
    "mail_recipient": "employee"
  },
  {
    "id": "ets_123",
    "employee": "emp_123",
    "company": "com_123",
    "year": 2024,
    "amends": null,
    "amended_by": "ets_456",
    "document": "doc_123",
    "filings": ["com_fil_123", "com_fil_234"],
    "filed_at": "2025-02-10T15:30:00Z",
    "published_at": "2025-02-10T15:30:00Z",
    "publication_status": "published",
    "delivery_method": "mail",
    "mail_recipient": "company"
  }
]

Previewing and Downloading Statements

Employee tax statements are metadata objects — to get the underlying PDF documents, you have two options:

Tax Packages: generate previews of draft statements, or download filed documents in bulk, by creating a tax package. See the Tax Packages guide.
Employee Tax Documents: for straightforward access to individual official (already filed) documents, use the List employee tax documents API.