Tax Packages

Overview

A tax package is a ZIP file of tax documents in PDF format, generated asynchronously so that large requests complete reliably. A single tax package can contain any combination of:

• Employee tax statements: employee copies of W-2 and W-2C documents. See the Employee Tax Statements guide for details on the underlying objects.
• Company filings: employer copies of the tax returns Check files on a company's behalf. See the Tax Filings guide for details on the underlying objects.

The key capability of tax packages is previewing documents before Check files them. When you request a document that has not yet been filed, the package contains a preview generated from the data Check will file. Once a document has been filed, the package contains the actual filed document instead.

Common use cases

• Year-end review: let employers review draft W-2s and draft employer copies of company returns before Check files them, so discrepancies can be caught and corrected early.
• Bulk document access: download all of a company's tax documents for a year in a single request instead of fetching documents one at a time.
• Employer recordkeeping: provide employers with copies of the returns Check filed on their behalf.

Important: Tax packages only contain PDF documents. CSV and JSON formats are not supported at this time. For straightforward access to individual official employee tax documents, use the List employee tax documents API.

The Tax Package Object

How to Use Tax Packages

The Tax Package API does three things:

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

Step 1: Gather the content IDs

• Employee tax statement IDs: query List employee tax statements. For example, GET /employee_tax_statements?company=com_123&publication_status=draft returns the draft statements Check will publish for a company.
• Company filing IDs: query the Filings API. Filings in any state may be requested — unfiled filings (including blocked filings) produce DRAFT-watermarked previews, and filed filings produce the final employer copy.

Step 2: Request a Tax Package

Create a package containing the employee tax statements and company filings you need:

POST /tax_packages

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

Both fields in contents are optional — a package may contain only employee tax statements, only company filings, or both.

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

Requests are idempotent: repeating a POST with the same contents returns the existing package rather than generating a new one. All requested content must belong to the specified company; requesting filings that don't belong to the company (or can't be previewed) returns a 400 error.

Step 3: 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"],
    "filings": ["com_fil_999"]
  },
  "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"],
    "filings": ["com_fil_999"]
  },
  "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"],
    "filings": ["com_fil_999"]
  },
  "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 4: Download the Package

Once status is succeeded, download the generated tax package:

GET /tax_packages/:id/download

By default, this endpoint returns JSON with a short-lived download_url for the ZIP archive containing all requested tax documents in PDF format — one PDF per employee tax statement and one PDF per company filing.

To download a single employee tax statement directly as a PDF, send an Accept: application/pdf request header. PDF downloads are available only when the tax package contains exactly one employee tax statement and no filings.