Employee Tax Statements and Tax Packages

This will replace the Get W-2 Preview Report API. The W2 Preview report will work through 2025, then in 2026 information will no longer be returned.

The employee tax statements API unlocks the following use cases over the W2 preview report:

1. Asynchronously generate previews of tax documents for many employees at once.
2. Associations to the rest of the tax filing API ecosystem through associated filings, and document endpoints.

The API only returns PDF documents. CSV and JSON responses are not supported in this new API.

Key concepts

• Employee tax statements: W-2s and W-2Cs. Similar to filings, employee tax statements provide visibility into the employee W-2s and W-2Cs that Check will file in the future and those that are already submitted. The employee tax statements API shows partners when Check filed these documents, whether they were amended, and their relationship to company filings.
• Tax packages: Zip files containing PDFs. These bundles include employee copies of year end tax documents. They are generated asynchronously.
• Documents: A tax document reflecting data that Check filed with an agency.

Employee tax statements and tax packages APIs

The employee tax statement object

Fields non-nullable unless specified.

When document is null, that means the document is not yet filed. You can generate previews of documents by sending a post request to /tax_packages with the employees for which you want to generate a tax package.

GET /employee_tax_statements/?employee=emp_123

List W-2 and W-2Cs for a single employee.

[
  {
    "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
  },
  {
    "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"
  },
  {
    "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"
  }
]

The tax package object

Fields non-nullable unless specified.

The tax package API does three things:

1. Provides an entry point to request a tax package containing employee tax statements.
2. Shows the state of the asynchronous job.
3. Returns a URL at which users can download the tax package.

Each of these steps are outlined below.

Note: documents generated by the tax package API are previews of what Check will file. When filing taxes, employees should use the tax document in the List employee tax documents API.

Request a tax package containing employee tax statements

POST /tax_packageswith the following request body:

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

This request will return the full object above and enqueue an asynchronous job. Keep track of the id returned. You may poll via GET /tax_packages/:id

Once the status changes to succeeded, the documents are ready in single PDF package at the url field in the result object.

Get state of the asynchronous job through polling

Tax package object when generating

GET /tax_packages/:id

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

Tax package object when generation completes successfully

GET /tax_packages/:id

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

Tax package object when generation fails

GET /tax_packages/:id

{
  "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."
  }
}

Results URL: Download the tax package

The last step is to download the ZIP file generated and stored at the result.url field.

GET /tax_packages/:id/download

This request sends back the contents to the user's application.