[Coming Soon] Filings Related APIs

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

They will replace two current APIs:

We plan to deprecate those later this year.

Key Concepts

Filings: Tax reports that must be submitted to agencies for a specific period on behalf of a company, typically managed by Check. Filings are tax reports that must be submitted to agencies for a specific period on behalf of a company, typically managed by Check.
The Filings API is an API that gives partners the ability to see 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. Information like status, status history, blocking reasons, amendments, and related documents are all be queryable through the Filings API. Using this API partners can communicate to customers with confidence what the status of their past and upcoming filings are.
EmployeeTaxStatements: 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 employee copies of filings (coming soon). They are generated asynchronously.

API Integration Guide

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-30T00:00:00Z",
	  "filed_at": null,
	  "filing_attempts": 0,
	  "document": null,
	  "amends": null,
	  "amended_by": null,
	  "status": "blocked",
	  "status_history": [
	    {
			  "status": "blocked",
			  "status_at": "2023-04-12T21:32:44.957364Z",
			  // "blocked_reasons": ["applied_for_ein"]
			  "blocked_reasons": [
				  "type": "applied_for_ein",
				  "resource_id": "spa_h7zSw4NITCtef4Taf5yA",
			  ]
	    },
	    ...
	  ]
	},
	{
	  "id": "com_fil_AaeJoEAzbqqc2D9GMr3R",
	  "company": "com_vIFHhvyGN47ej1upyIT8",
	  "year": 2025,
	  "period": "q1",
	  "label": "Federal Quarterly Tax Return",
	  "due_at": "2025-04-30T00:00:00Z",
	  "filed_at": "2025-04-20T15:30:00Z",
	  "filing_attempts": 0,
	  "document": "doc_1234",
	  "amends": null,
	  "amended_by": "com_fil_bISuBs24PYIOF4hN2wh7",
	  "status": "filed",
	  "status_history": [
	    {
			  "status": "filed",
			  "status_at": "2025-04-20T15:30:00Z",
			  "blocked_reasons": null
	    },
	    ...
	  ]
	},
	{
	  "id": "com_fil_bISuBs24PYIOF4hN2wh7",
	  "company": "com_vIFHhvyGN47ej1upyIT8",
	  "year": 2025,
	  "period": "q1",
	  "label": "Amended Federal Quarterly Tax Return",
	  "due_at": null,
	  "filed_at": "2025-05-10T16:31:00Z",
	  "filing_attempts": 0,
	  "document": "doc_2345",
	  "amends": "com_fil_AaeJoEAzbqqc2D9GMr3R",
	  "amended_by": null,
	  "status": "filed",
	  "status_history": [
	    {
			  "status": "filed",
			  "status_at": "2025-05-10T16:31:00Z",
			  "blocked_reasons": null
	    },
	    ...
	  ]
	}
]

GET /filings/com_fil_GaeJoEAzbqqc2D9GMfOF

Get details about a particular blocked filing for a company.

{
  "id": "com_fil_GaeJoEAzbqqc2D9GMfOF",
  "company": "com_vIFHhvyGN47ej1upyIT8",
  "year": 2025,
  "period": "q1",
  "label": "Texas Quarterly Employment Return",
  "due_at": "2025-04-30T00:00:00Z",
  "filed_at": null,
  "filing_attempts": 0,
  "document": null,
  "amends": null,
  "amended_by": null,
  "status": "blocked",
  "status_history": [
    {
		  "status": "blocked",
		  "status_at": "2023-04-12T21:32:44.957364Z",
		  "blocked_reasons": ["applied_for_ein"]
    },
    ...
  ]
}

The Filing Object

Fields non-nullable unless specified.

field	type	description
`id`	ID	ID of the `Filing`
`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 (≤255 characters)	Human-readable label for the filing.
`due_at`	datetime in UTC	ISO8601 datetime 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.

• pending: Once we determine a tax filing is applicable to a company at the start of a filing period, we will create this object and start it in pending or blocked (see below). Check is responsible for action.
• 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.

•status_history | List of the most recent status changes, in reverse chronological order.

Limited to most recent 50. | Each object represents a processing status change.

status: One of pending, blocked, filed , inapplicable
status_at: When the previous status was changed to status.
blocked_reasons, nullable: Optional list of reason enumerations for the status change to blocked.

status lifecycle:

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