Tax Filings

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

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

Overview

The Tax Filings APIs 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 and a human-readable label.
• due_at: when the return is due.
• filed_at: when the agency acknowledges receipt, if applicable.
• document linking to the final PDF once 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 and are designed to be actionable by the employer or partner, for example applied_for_tax_id. 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. These are designed to be surfaced to end users so they can fix issues and unblock progress.

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 any determined blockers to Check completing a successful filing — e.g. invalid EINs, EINs marked as applied for, etc. — the filing will be blocked with a set of reason enumerated in the blocked_reasons field. All reasons should be actionable by the employer. When Check submits 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 thestatus_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.

API Integration Guide

Filings API

List filings - GET /filings?company=com_vIFHhvyGN47ej1upyIT8

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

{
  "next": null,
  "previous": null,
  "results": [
    {
      "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"
            },
            {
              "type": "tpa_failure",
              "resource_type": null,
              "resource": null
            }
          ]
        }
      ]
    },
    {
      "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 a filing - 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"
        }
      ]
    }
  ]
}

Add filing blockers - POST /filings/com_fil_AaeJoEAzbqqc2D9GMr3R/add_blockers

Add one or more blockers to a filing and return the updated filing. 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",
  "label": "Federal Quarterly Tax 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": "2025-04-20T15:30:00Z",
      "blocked_reasons": [
        {
          "type": "held_by_customer",
          "resource_type": null,
          "resource": null
        }
      ]
    }
  ]
}

Possible errors:

blockers_already_present blockers_not_addable

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",
  "label": "Federal Quarterly Tax Return",
  "due_at": "2025-04-30T00:00:00Z",
  "filed_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": []
    }
  ]
}

Possible errors:

blockers_not_found blockers_require_zendesk_ticket blockers_not_removable

Filing blockers

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

The Filing object

Fields non-nullable unless specified.

StatusHistory

BlockedReason