Tax Packages

Overview

A tax package is a ZIP file of tax documents, 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.
• Contractor tax statements: contractor copies of 1099-NEC documents, when contractor tax statements are enabled for your account. See the Contractor 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: A tax package contains one PDF per requested document. When the package includes employee or contractor tax statements, it also contains one CSV per kind of statement (W-2 or 1099-NEC), so an employer can scan many statements at once instead of opening each PDF. A package of company filings alone has no CSV. JSON is not available. For straightforward access to individual official employee tax documents, use the List employee tax documents API, or the List contractor tax documents API for published 1099-NECs.

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, contractor 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.
• Contractor tax statement IDs: query List contractor tax statements. For example, GET /contractor_tax_statements?company=com_123&publication_status=draft returns the draft 1099-NECs Check will publish for a company. This applies only when contractor tax statements are enabled for your account.
• 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 tax documents you need:

POST /tax_packages

{
  "company": "com_myKIvCGb7M86G2CQbYe5",
  "contents": {
    "employee_tax_statements": ["ets_123", "ets_456"],
    "contractor_tax_statements": ["cts_789"],
    "filings": ["com_fil_999"]
  },
  "statement_csv_format": "standard"
}

Every field in contents is optional — a package may contain any combination of employee tax statements, contractor tax statements, and company filings. contractor_tax_statements applies only when contractor tax statements are enabled for your account; otherwise it is ignored.

statement_csv_format is optional and defaults to standard. Set it to with_ids to include a leading Statement ID column on each statement CSV in the downloaded ZIP ({tax_package_id}_employee_tax_statements.csv and {tax_package_id}_contractor_tax_statements.csv, when present). Omit the field or use standard for the existing column layout.

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

Requests are idempotent: repeating a POST with the same company, contents, and statement_csv_format 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

Instead of polling, you can subscribe to the tax_package webhook. Check sends one status_change event when generation succeeds or fails, with the tax package object as its payload. The webhook's result.url is a relative path, so use the package id to call the download endpoint in Step 4.

While Generating

{
  "id": "tax_pkg_1MrQwrLkdIwHu7ixUov4x2b3",
  "company": "com_myKIvCGb7M86G2CQbYe5",
  "status": "generating",
  "contents": {
    "employee_tax_statements": ["ets_123", "ets_456"],
    "contractor_tax_statements": ["cts_789"],
    "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"],
    "contractor_tax_statements": ["cts_789"],
    "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"
  },
  "error": null
}

If Generation Fails

{
  "id": "tax_pkg_1MrQwrLkdIwHu7ixUov4x2b3",
  "company": "com_myKIvCGb7M86G2CQbYe5",
  "status": "failed",
  "contents": {
    "employee_tax_statements": ["ets_123", "ets_456"],
    "contractor_tax_statements": ["cts_789"],
    "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 — one PDF per employee tax statement, one PDF per contractor tax statement, and one PDF per company filing.

The archive can also contain a CSV for each kind of statement in the package:

• When the package includes at least one employee tax statement, a CSV named {tax_package_id}_employee_tax_statements.csv, with one row per requested employee tax statement, covering every box on the W-2.
• When the package includes at least one contractor tax statement, a CSV named {tax_package_id}_contractor_tax_statements.csv, with one row per requested contractor tax statement, covering every box on the 1099-NEC.

A package of company filings alone has no CSV.

To download a single 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 or contractor tax statement and no filings. That request returns the statement PDF alone; the CSV is available only in the ZIP.