Tax Filings

This guide explains how to use Check’s filing-related APIs

The Legacy Tax Filings API will be deprecated on December 31, 2025. The Filings API replaces it.

Overview

The Tax Filings API allows you to do two key things:

Determine what filings Check will file on behalf of a company in the future based on its payroll setup and activity.
Query for information (including status) about tax filings, for companies and employees, in ~real time.

If you would like to learn more about how to generate previews of employee tax documents, or download groups of company and employee tax documents in bulk, please refer to the Employee Tax Statements and Tax Packages guide.

Why this matters for your product

Proactive visibility: You can show customers what’s coming due and what’s already filed without stitching together multiple data sources.
Clear ownership: Blocked states include actionable reasons so employers or partners can resolve issues quickly, ensuring Check can file accurate returns for employers in a timely fashion.
Reliable timelines: status_history lets you render clean, comprehensible progress views and notifications.

What is a filing?

A "Filing" represents a specific tax return Check prepares and submits to a government agency for a company for a given period and jurisdiction. It exists for both upcoming obligations and historical returns, so partners can see what Check plans to file and what has already been filed, all in one place

Each Filing includes core identifiers and timestamps to anchor it in your product:

id, company, year, period, period_start, period_end, and a human-readable label.
due_at: the date the return is due, if applicable. This is null for amendment filings.
filed_at: when the filing reached the filed status, if applicable.
closed_at: when the underlying filing was closed, if applicable.
document: the ID of the final filing document, when available.
amends and amended_by to show amendment relationships.
filing_attempts to indicate how many times Check attempted to file the return.
status and status_history to track lifecycle changes over time.

Conceptually, a Filing is the end-to-end life of a single return for a company and period. That includes:

Visibility before filing: upcoming returns that Check plans to file.
Real-time progress: whether a return is ready to file, blocked, in progress, or complete.
Outcomes and follow-ups: agency acceptance, rejections, and any required amendments.
Related documents: links to the authoritative PDF once it’s available.

Filing status model

Filings use a small, stable set of user-facing statuses. You can rely on the status field for current state, and status_history for a chronological trail of changes.

Common statuses you will see:

pending: The filing applies and is being prepared to file. It may move back to pending when an amendment begins.
blocked: Something prevents filing. Reasons are provided so the employer or partner can understand what is blocking progress and, when applicable, take action or contact Check support. This could also mean that the agency rejected the return and a correction or amendment is required.
submitted: Check submitted the filing to the agency. The date of this status is what the agency considers when assessing if the filing was on time. Filings in this status can return to blocked or pending.
filed: The agency acknowledged the filing as complete. This is usually terminal, though post‑filing corrections can move a return into an amendment flow.
inapplicable: Check has determined the filing no longer applies to the company. Reasons might include: voided payrolls, regulatory change, updated tax elections.

Status history

status_history captures changes with timestamps and, when relevant, reason details. Use it to build user timelines, audit trails, and “what changed” views.

Blocked reasons

When a Filing is blocked, the API includes a list of reason objects that identify why, plus the related resource when available. These reasons are designed to be surfaced to end users or partners so they can understand what is blocking progress and, when applicable, take action or contact Check support.

Status lifecycle diagram

The below diagram demonstrates the status lifecycle of a filing. 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. If there are blockers preventing Check from completing a successful filing, for example invalid EINs or EINs marked as applied for, the filing will be blocked with a set of reasons enumerated in the blocked_reasons field. Blocked reasons are intended to be user-facing, but not all are self-service. Some can be resolved directly by the employer or partner, while others require Check review or support intervention. When Check submits the filing to the agency, it will move to submitted. The filing may return to pending due to validation issues with the submission file that do not require any action from you. It would then return to submitted when Check resubmits to the agency. Once the filing is acknowledged by the agency as successfully filed, the filing will be marked as filed. If the agency rejects the filing for any reason, the filing will be moved back into blocked with blocked_reasons outlining next steps.

Displaying filed datetime in your product

The filed_at field represents the datetime when Check acknowledged that the agency accepted the filing. However, the agency considers the submitted time as when the filing is on time or late. We recommend that you use the status_at datetime for the most recent submitted status as the filed timestamp in your product. If you do not want to display the submitted status, you can still use the status_at for the most recent submitted status history but update the timestamp after the filing becomes filed.

Flow diagram of `status` transitions for Filings

API Integration Guide

Filings API

List filings - `GET /filings?company=com_vIFHhvyGN47ej1upyIT8`

List filing history, plus expected upcoming filings, for one or more companies available to the authenticated provider. Use the company query parameter to filter to a single company.

{
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "com_fil_GaeJoEAzbqqc2D9GMfOF",
            "company": "com_vIFHhvyGN47ej1upyIT8",
            "year": 2025,
            "period": "q1",
            "period_start": "2025-01-01",
            "period_end": "2025-03-31",
            "label": "Texas Quarterly Employment Return",
            "due_at": "2025-04-30",
            "filed_at": null,
            "closed_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",
                            "note": null
                        },
                        {
                            "type": "tpa_failure",
                            "resource_type": null,
                            "resource": null,
                            "note": "tpa failure note"
                        }
                    ]
                }
            ]
        },
        {
            "id": "com_fil_bISuBs24PYIOF4hN2wh7",
            "company": "com_vIFHhvyGN47ej1upyIT8",
            "year": 2025,
            "period": "q1",
            "period_start": "2025-01-01",
            "period_end": "2025-03-31",
            "label": "Amended Federal Quarterly Tax Return",
            "due_at": null,
            "filed_at": "2025-05-10T16:31:00Z",
            "closed_at": null,
            "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 a filing - `GET /filings/com_fil_GaeJoEAzbqqc2D9GMfOF`

Get a single filing.

{
    "id": "com_fil_GaeJoEAzbqqc2D9GMfOF",
    "company": "com_vIFHhvyGN47ej1upyIT8",
    "year": 2025,
    "period": "q1",
    "period_start": "2025-01-01",
    "period_end": "2025-03-31",
    "label": "Texas Quarterly Employment Return",
    "due_at": "2025-04-30",
    "filed_at": null,
    "closed_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",
                    "note": null
                }
            ]
        }
    ]
}

Add filing blockers - `POST /filings/com_fil_AaeJoEAzbqqc2D9GMr3R/add_blockers`

Add one or more blockers to a filing and return the updated filing. Blockers can only be added to filings with a blocked or pending status.

In production, partners can add only the held_by_customer blocker through this endpoint. In Sandbox, invalid_ssn and inactive_account are also accepted.

Request body:

{
  "blockers": ["held_by_customer"]
}

Response:

{
    "id": "com_fil_AaeJoEAzbqqc2D9GMr3R",
    "company": "com_vIFHhvyGN47ej1upyIT8",
    "year": 2025,
    "period": "q1",
    "period_start": "2025-01-01",
    "period_end": "2025-03-31",
    "label": "Federal Quarterly Tax Return",
    "due_at": "2025-04-30",
    "filed_at": null,
    "closed_at": "2025-04-25T00:00:00Z",
    "filing_attempts": 0,
    "document": null,
    "amends": null,
    "amended_by": null,
    "status": "blocked",
    "status_history": [
        {
            "status": "blocked",
            "status_at": "2025-04-20T15:30:00Z",
            "blocked_reasons": [
                {
                    "type": "held_by_customer",
                    "resource_type": null,
                    "resource": null,
                    "note": null
                }
            ]
        }
    ]
}

Possible errors:

blockers_already_present caused by the blocker already existing on the filing
blockers_not_addable caused by trying to add an unsupported blocker type or by attempting to add blockers to a filing in a non-supported status
manual_issue_policy_violation caused by a manual issue policy preventing the requested blocker change

Remove filing blockers - `POST /filings/com_fil_AaeJoEAzbqqc2D9GMr3R/remove_blockers`

Remove one or more blockers from a filing and return the updated filing.
Only blockers that are currently open on the filing can be removed with this endpoint.
Blockers that must be resolved via Zendesk, as well as non-manual or internal blockers,
cannot be removed through the API.

Request body:

{
  "blockers": ["invalid_tax_id"]
}

Response:

{
    "id": "com_fil_AaeJoEAzbqqc2D9GMr3R",
    "company": "com_vIFHhvyGN47ej1upyIT8",
    "year": 2025,
    "period": "q1",
    "period_start": "2025-01-01",
    "period_end": "2025-03-31",
    "label": "Federal Quarterly Tax Return",
    "due_at": "2025-04-30",
    "filed_at": null,
    "closed_at": null,
    "filing_attempts": 0,
    "document": null,
    "amends": null,
    "amended_by": null,
    "status": "pending",
    "status_history": [
        {
            "status": "pending",
            "status_at": "2025-04-20T15:30:00Z",
            "blocked_reasons": null,
            "note": null
        }
    ]
}

Possible errors:

blockers_not_found caused by attempting to remove blockers that are not currently present on the filing
blockers_require_zendesk_ticket caused by attempting to remove blockers that require a support ticket
blockers_not_removable caused by attempting to remove blockers that are not removable through the API
manual_issue_policy_violation caused by a manual issue policy preventing the requested blocker change

Filing blockers

held_by_customer is the only blocker that can be added via add_blockers. Many blockers are eligible to be removed (detailed below).

Blocked Reason Code	Description	Resource Type	Resolution path
`applied_for_tax_id`	Company has not registered for an account number with the agency.	`company_tax_param`	This will resolve automatically when a value is added for the linked setup param.
`already_filed`	Filing was rejected by the agency because it was already filed (typically by the prior payroll provider, or the company itself).	`None`	Contact Check support in Zendesk.
`company_bad_standing`	The company has an unresolved failed debit or existing unresolved issue.	`payment` if available	This will resolve automatically when the company returns to good standing.
`held_by_customer`	Company has requested a hold on the filing.	`None`	Removable via `remove_blockers`.
`inactive_account`	Either an invalid Tax ID was provided by the company or the agency has closed the account due to inactivity.	`None`	Removable via `remove_blockers`.
`incorrect_account_setup`	Either an invalid Tax ID was provided or the full setup was not completed with the agency.	`None`	Removable via `remove_blockers`.
`invalid_ssn`	Employees have invalid SSNs that are not accepted by the agency.	`employee`	Removable via `remove_blockers`.
`invalid_tax_id`	The agency does not recognize the tax ID provided by the company as valid or associated with that company.	`company_tax_param`	Removable via `remove_blockers`.
`invalid_tax_rate`	The tax rate on file does not match the value with the agency.	`company_tax_param`	Removable via `remove_blockers`.
`late_company_reactivation`	Company was reactivated after the filing month.	`None`	Contact Check support in Zendesk.
`missing_historical_data`	A state may require the tax return filing to reflect each tax payment that was paid to them in the quarter. If the filing does not reconcile to the payments, the agency will reject the return.	`None`	Contact Check support in Zendesk.
`missing_prior_quarter`	A prior quarter was not filed and the agency prevents filing future periods until that is resolved.	`None`	Removable via `remove_blockers`.
`missing_tax_funds`	The filing is blocked because required tax funding has not yet been confirmed for the filing.	`payroll` if available	This blocker clears once funding is confirmed. If funding is already expected to be available, contact Check support.
`not_liable`	The agency indicated that the company is not liable for this filing.	`None`	Removable via `remove_blockers`.
`other`	Miscellaneous blocked reason.	`None`	Removable via `remove_blockers`.
`poa_failure`	Power of attorney is not on file with the agency.	`None`	Removable via `remove_blockers`.
`tpa_failure`	Third-party administrator is not granted with the agency.	`None`	Removable via `remove_blockers`.

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`.
`period_start`	date	Start date for the filing period
`period_end`	date	End date for the filing period
`label`	string	Human-readable label for the filing.
`due_at`	nullable* date	ISO8601 date the filing is due to the agency by. This is `null` for amendment filings.
`filed_at`	nullable* datetime in UTC	ISO8601 datetime the filing status became successfully `filed`.
`closed_at`	nullable* datetime in UTC	ISO8601 datetime when the underlying filing was closed.
`document`	nullable* ID	If available, the ID of the filing document associated with this Filing.
`filing_attempts`	int, default 0	Number of filing attempts made by Check.
`amends`	nullable* list of IDs	List of original `Filing` IDs that this resource is an amendment of. If populated, indicator of this `Filing` being an amendment. Will contain only one ID for now, but may contain multiple IDs in the future.
`amended_by`	nullable* list of IDs	List of `Filing` IDs that amend this filing.
`status`	enum, one of `pending`, `blocked`, `submitted`,`filed` , or`inapplicable`	The current filing processing status.
`status_history`	list of `StatusHistory` objects	List of status changes, in reverse chronological order. This includes transitions triggered by blockers being added, removed, or otherwise resolved. Each object represents a public processing status change.

StatusHistory

field	type	description
`status`	enum	One of `pending`, `blocked`, `submitted`, `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 blocked reasons associated with the filing while it was in the `blocked` status. This is `null` for non-`blocked` status history entries.

BlockedReason

field	type	description
`type`	enum	Options enumerated below.
`resource_type`	nullable string	Related resource type when available. Current values may include `company_tax_param`, `employee`, `payroll`, `payment`, or `null`.
`resource`	nullable ID	ID of the resource for resolving the blocker
`note`	nullable string	Note provided by Check operators that provides more context on the blocker reason, when available. For example, "John Smith's SSN is all 0s."