Tax Filings

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

The filings API replaces the tax_filings API, will become deprecated December 31, 2025.

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, // 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 /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 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 be 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`, `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:

Further reading: Employee Tax Statements