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.
• 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 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. 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.

API Integration Guide

Filings API

List filings - 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, // nullable list
    "amended_by": null, // nullable list
    "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 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"
        }
      ]
    }
  ]
}

The Filing object

Fields non-nullable unless specified.

StatusHistory

BlockedReason

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