Employee Tax Statements and Tax Packages

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:

Bulk Processing: Generate tax document previews for multiple employees simultaneously
Enhanced Integration: Connect seamlessly with Check's filing and document ecosystem through associated filings and document endpoints
Asynchronous Generation: Handle large requests without timeout issues

Important: This API only returns PDF documents. CSV and JSON formats are not supported at this time.

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

Tax Packages

Zip files containing multiple employee tax documents in PDF format. These are generated asynchronously to handle large requests efficiently.

Documents

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

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 (see below).

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_corrections`

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

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"
  }
]

Tax Package Object

Manages the asynchronous generation of tax document bundles.

field	type	description
`id`	ID	Unique identifier for the tax package
`company`	ID	Company this package belongs to
`status`	`generating`, `succeeded`, `failed`	Current status: `generating`, `succeeded`, or `failed`
`contents`	`{"employee_tax_statements": ["ets_123", "ets_456"]}`	Requested employee tax statements
`created_at`	nullable datetime in UTC	When the package request was created (UTC)
`succeeded_at`	nullable datetime in UTC	When generation completed successfully (UTC)
`result`	nullable `{"url": downloadable_url}`	Download URL where you may access the generated tax package
`error`	nullable `{"type": "content_not_found", "message": "Human readable error message"}`	Error details if generation failed

Important: Tax packages generate previews of documents Check will file when employee tax statements are not yet filed. However, once an employee tax statements have been filed, and is therefore associated with a document, a tax package that is generated which contains that employee tax statement will include the actual filed document. For straightforward access to official tax documents, use the List employee tax documents API.

How to Use Tax Packages

The Tax Package API does three things:

Provides an interface to request a tax package containing one or more employee tax statements.
Shows the state of the asynchronous generation job.
Returns a URL at which users can download the tax package.

Step 1: Request a Tax Package

Create a package containing the employee tax statements you need:

POST /tax_packages

{
  "company": "com_myKIvCGb7M86G2CQbYe5",
  "contents": {
    "employee_tax_statements": ["ets_123", "ets_456"]
  }
}

Response: Returns the tax package object with status: "generating". Save the id for polling.

Step 2: Poll for Completion

Check the generation status regularly:

GET /tax_packages/:id

While Generating

{
  "id": "tax_pkg_1MrQwrLkdIwHu7ixUov4x2b3",
  "company": "com_myKIvCGb7M86G2CQbYe5",
  "status": "generating",
  "contents": {
    "employee_tax_statements": ["ets_123", "ets_456"]
  },
  "created_at": "2024-11-03T19:52:15Z",
  "succeeded_at": null,
  "result": null,
  "error": null
}

When Complete

{
  "id": "tax_pkg_1MrQwrLkdIwHu7ixUov4x2b3",
  "company": "com_myKIvCGb7M86G2CQbYe5",
  "status": "succeeded",
  "contents": {
    "employee_tax_statements": ["ets_123", "ets_456"],
  },
  "created_at": "2024-11-03T19:52:15Z",
  "succeeded_at": "2024-11-03T19:55:11Z",
  "result": {
    "url": "https://api.checkhq.com/tax_packages/tax_pkg_1MrQwrLkdIwHu7ixUov4x2b3/download",
    "expires_at": "2024-11-03T20:55:11Z"
  },
  "error": null
}

If Generation Fails

{
  "id": "tax_pkg_1MrQwrLkdIwHu7ixUov4x2b3",
  "company": "com_myKIvCGb7M86G2CQbYe5",
  "status": "failed",
  "contents": {
    "employee_tax_statements": ["ets_123", "ets_456"],
  },
  "created_at": "2024-11-03T19:52:15Z",
  "succeeded_at": null,
  "result": null,
  "error": {
    "type": "generation_timeout",
    "message": "Generation took longer than one hour to generate. Create a new package with fewer contents."
  }
}

Step 3: Download the Package

Once status is succeeded, download your ZIP file:

GET /tax_packages/:id/download

This endpoint returns the complete tax package as a downloadable ZIP file containing all requested tax documents in PDF format.