CHcheckhq

[Sandbox] Add blocked reason

Changed on

Add a blocked reason to a filing to simulate a filing failure, transitioning the filing to blocked. Sandbox-only: in production this endpoint returns a 404.

The filing must be in pending or blocked status. Most blocker IDs from the Filing blockers table are accepted. Blockers that Check sets automatically (applied_for_tax_id, missing_tax_funds, collection_failed, company_bad_standing) return rule_violation. Blockers that apply only in certain cases, such as incorrect_experience_factor (Washington L&I filings only), return manual_issue_policy_violation when added to a filing they don't apply to, with a message explaining why. Returns the updated filing. An updated webhook with the company_filing topic is sent.

post/filings/{filing_id}/simulate/add_blocked_reason

Request

Path parameters

filing_idstring required

ID of the company filing

Request body

blocked_reasonstring required

ID of the blocker to add to the filing. See the Filing blockers table for the full list.

notestring nullable

Optional note to attach to the blocked reason. If the blocked reason is already present on the filing, the note is updated.

Example request

{
  "blocked_reason": "poa_failure",
  "note": "Waiting on signed POA"
}

Response

200

idstring
companystring
yearinteger
periodstring
labelstring
jurisdictionstring nullable

Lowercase region code for the filing (fed or lowercased ISO 3166-2:US region code).

agencystring nullable

ID of the Agency that receives this filing.

due_atstring
filed_atstring nullable
closed_atstring nullable
documentstring nullable
filing_attemptsinteger
amendsstring[]
amended_bystring[]
statusstring

Example response

{
  "id": "com_fil_AaeJoEAzbqqc2D9GMr3R",
  "company": "com_vIFHhvyGN47ej1upyIT8",
  "year": 2025,
  "period": "q1",
  "label": "Federal Quarterly Filing - Q1",
  "jurisdiction": "fed",
  "agency": "agc_ukjABgbD0hQ3dfBRyMPD",
  "due_at": "2025-04-30",
  "closed_at": "2025-04-25T00:00:00.000Z",
  "status": "blocked",
  "status_history": [
    {
      "status": "blocked",
      "status_at": "2025-04-20T15:30:00.000Z",
      "blocked_reasons": [
        {
          "type": "held_by_customer"
        }
      ]
    }
  ]
}

Changes