[Coming Soon] Tax Filings

This guide explains how to use Check’s new filing-related APIs. These APIs will launch in existing versions in September 2025.

They will replace two current APIs, which will become deprecated December 31, 2025.

Key Concepts

Filings: Tax reports that must be submitted to agencies for a specific period on behalf of a company, typically managed by Check. The Filings API provides visibility into what Check plans to file for a company in upcoming filing periods, as well as what Check has filed for a company in past filing periods. Available information includes status, status history, blocking reasons, amendments, and related documents.
Employee Tax Statements: W-2s and W-2Cs. These are annual tax statements for employees to use on their personal tax returns. Similar to filings, Employee Tax Statements provide visibility into the employee W-2s and W-2Cs that are expected or 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 file downloads of PDFs. These bundles include employee copies of year end tax documents and/or employer copies of filings (coming soon). They are generated asynchronously.

API Integration Guide

Filings API

GET /filings?company=com_vIFHhvyGN47ej1upyIT8

List the filing history, plus expected upcoming filings, for a single company.

[
  {
    "id": "com_fil_GaeJoEAzbqqc2D9GMfOF",
    "company": "com_vIFHhvyGN47ej1upyIT8",
    "year": 2025,
    "period": "q1",
    "label": "Texas Quarterly Employment Return",
    "due_at": "2025-04-30",
    "filed_at": null,
    "filing_attempts": 0,
    "document": null,
    "amends": null,
    "amended_by": null,
    "status": "blocked",
    "status_history": [
      {
        "status": "blocked",
        "status_at": "2025-01-01T01:08:00.957364Z",
        "blocked_reasons": [
          {
            "type": "applied_for_tax_id",
            "resource_type": "company_tax_param",
            "resource": "spa_h7zSw4NITCtef4Taf5yA"
          }
        ]
      }
    ]
  },
  {
    "id": "com_fil_bISuBs24PYIOF4hN2wh7",
    "company": "com_vIFHhvyGN47ej1upyIT8",
    "year": 2025,
    "period": "q1",
    "label": "Amended Federal Quarterly Tax Return",
    "due_at": "2025-04-30",
    "filed_at": "2025-05-10T16:31:00Z",
    "filing_attempts": 1,
    "document": "doc_2345",
    "amends": "com_fil_AaeJoEAzbqqc2D9GMr3R",
    "amended_by": null,
    "status": "filed",
    "status_history": [
      {
        "status": "filed",
        "status_at": "2025-05-10T16:31:00.957364Z",
        "blocked_reasons": null
      },
      {
        "status": "pending",
        "status_at": "2025-01-01T01:04:00.957364Z",
        "blocked_reasons": null
      }
    ]
  },
  ...
]

GET /filings/com_fil_GaeJoEAzbqqc2D9GMfOF

Get a single filing.

{
  "id": "com_fil_GaeJoEAzbqqc2D9GMfOF",
  "company": "com_vIFHhvyGN47ej1upyIT8",
  "year": 2025,
  "period": "q1",
  "label": "Texas Quarterly Employment Return",
  "due_at": "2025-04-30",
  "filed_at": null,
  "filing_attempts": 0,
  "document": null,
  "amends": null,
  "amended_by": null,
  "status": "blocked",
  "status_history": [
    {
      "status": "blocked",
      "status_at": "2025-01-01T01:08:00.957364Z",
      "blocked_reasons": [
        {
          "type": "applied_for_tax_id",
          "resource_type": "company_tax_param",
          "resource": "spa_h7zSw4NITCtef4Taf5yA"
        }
      ]
    }
  ]
}

The Filing Object

Fields non-nullable unless specified.

field	type	description
`id`	ID	ID of the `Filing` (prefixed with `com_fil_`)
`company`	ID	ID of the `Company`
`year`	int	Year in which the filing is for
`period`	enum, one of `annual`, `q1`, `q2`, `q3`, `q4`, `january`, `february`, `march`, `april`, `may`, `june`, `july`, `august`, `september`, `october`, `november`, `december`	Filing period in the `year`.
`label`	string	Human-readable label for the filing.
`due_at`	date	ISO8601 date the filing is due to the agency by.
`filed_at`	nullable datetime in UTC	ISO8601 datetime the filing status became successfully `filed`.
`document`	nullable ID	If the `processing_status` is `filed`, the ID of the `CompanyTaxDocument`.
`filing_attempts`	int, default 0	Number of filing attempts made by Check.
`amends`	nullable ID	ID of the previous `Filing` that this resource is an amendment of. If populated, indicator of this `Filing` being an amendment.
`amended_by`	nullable ID	ID of the next `Filing` that amends this filing.
`status`	enum, one of `pending`, `blocked`, `filed` , or`inapplicable`	The current filing processing status.
`status_history`	list of `StatusHistory` objects	List of the most recent status changes, in reverse chronological order. Limited to most recent 50. Each object represents a processing status change.

• pending: Once a tax filing is determined to be applicable for a company at the start of a filing period, this object will be created as pending or blocked (see below). Check is responsible for action. Note, this will become available for all filings in early 2026.
• blocked: If there are any determined blockers to Check completing a successful filing—invalid EINs, EINs marked as applied for, etc.—the filing will be blocked with a set of reason enumerations. All reasons should be actionable by the employer. The Partner/Employer is responsible for action.
• filed: Once the filing is acknowledged by the agency as successfully filed, it will be marked as filed.
• inapplicable: Check has determined the filing no longer applies to the company. Reasons might include include: voided payrolls, regulatory change, updated tax elections.

StatusHistory

field	type	description
`status`	enum	One of `pending`, `blocked`, `filed` , `inapplicable`
`status_at`	datetime in UTC	When the previous status was changed to `status`.
`blocked_reasons`	nullable list of `BlockedReason` objects	Optional list of reason enumerations for the status change to `blocked`.

BlockedReason

field	type	description
`type`	enum	Options enumerated below.
`resource_type`	nullable `company_tax_param` or `requirement`	CompanyTaxParam or Requirement
`resource`	nullable ID	ID of the resource for resolving the blocker

Possible BlockedReason types

The accompanying resource_type is specified in parentheses, if applicable.

already_filed
applied_for_tax_id (company_tax_param)
company_bad_standing
held_by_customer
inactive_account
incorrect_account_setup
invalid_ssn
invalid_tax_id
invalid_tax_rate
late_company_reactivation
missing_historical_data
missing_prior_quarter
not_liable
poa_failure
previous_filing_in_progress
tpa_failure

status lifecycle:

Employee Tax Statements API

GET /employee_tax_statements/?employee=emp_123

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

[
  {
    "id": "ets_789",
    "employee": "emp_123",
    "year": 2025,
    "amends": null,
    "amended_by": null,
    "document": null,
    "filings": ["com_fil_999"],
    "filed_at": null
  },
  {
    "id": "ets_456",
    "employee": "emp_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",
    "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 EmployeeTaxStatement Object

Fields non-nullable unless specified.

field	type	description
`id`	ID	ID of the `EmployeeTaxStatement`
`employee`	ID	ID of the `Employee`
`company`	ID	ID of the `Company`
`year`	int	Year in which the filing is for
`amends`	nullable ID	ID of the previous `EmployeeTaxStatement` that this resource amends. If populated, indicator of this `Filing` being an amendment.
`amended_by`	nullable ID	ID of the next `EmployeeTaxStatement` that amends this employee data.
`document`	nullable ID	If filed, the ID of the `EmployeeDocument`.
`filings`	list of IDs	List of IDs that are the company `Filings` in which this worker data has been submitted
`filed_at`	nullable datetime in UTC	ISO8601 datetime when all related filings became successfully `filed`.

POST /tax_packages

Request individual employee tax statement download

{
  "company": "com_myKIvCGb7M86G2CQbYe5",
  "contents": {
    "employee_tax_statements": ["ets_123"],
    "contractor_tax_statements": [],
    "filings": []
  },
  "metadata": {...}
}

Request all employee tax statement downloads for a company

{
  "company": "com_myKIvCGb7M86G2CQbYe5",
  "contents": {
    "employee_tax_statements": ["ets_123", "ets_456"],
    "contractor_tax_statements": [],
    "filings": []
  },
  "metadata": {...}
}

[Coming Soon] Request all company tax returns for a filing period

{
  "company": "com_myKIvCGb7M86G2CQbYe5",
  "contents": {
    "employee_tax_statements": [],
    "contractor_tax_statements": [],
    "filings": ["com_fil_123", "com_fil_345"]
  },
  "metadata": {...}
}

The TaxPackage Object

Fields non-nullable unless specified.

field	type	description
`id`	ID	ID of the `TaxPackage`
`company`	ID	ID of the `Company`
`status`
`contents`
`created_at`	nullable datetime in UTC	ISO8601 datetime when all related filings became successfully `filed`.
`succeeded_at`	nullable datetime in UTC	ISO8601 datetime when all related filings became successfully `filed`.
`result`
`error`
`metadata`

When generating:

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

When generation succeeds:

{
  "id": "tax_pkg_1MrQwrLkdIwHu7ixUov4x2b3",
  "company": "com_myKIvCGb7M86G2CQbYe5",
  "status": "succeeded",
  "contents": {
    "employee_tax_statements": ["ets_123", "ets_456"],
    "contractor_tax_statements": [],
    "filings": []
  },
  "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,
  "metadata": {...}
}

When generation fails:

{
  "id": "tax_pkg_1MrQwrLkdIwHu7ixUov4x2b3",
  "company": "com_myKIvCGb7M86G2CQbYe5",
  "status": "failed",
  "contents": {
    "employee_tax_statements": ["ets_123", "ets_456"],
    "contractor_tax_statements": [],
    "filings": []
  },
  "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."
  },
  "metadata": {...}
}