Typically, filings transition through their lifecycle in response to Check filing taxes with agencies. You can simulate this lifecycle using the sandbox-only APIs described below.

Create filings for a company

Prerequisites

Before creating test filings, ensure you have:

• Generated a company with employees in Sandbox and fully onboarded the company to Check by running through the Start implementation endpoint with basic payroll data. The company's implementation.status field will show complete once this is done.
• Created and approved a payroll for that company with some of their employees in one of the supported states listed below.

Generating test Filings

If you have a Sandbox company with payroll data, you can POST to the Refresh filings endpoint at /companies/:company_id/refresh_filings with the payroll IDs and employee IDs for which you want to generate filings. You may also omit the payroll_ids and employee_ids to generate data for the entire company, including employee W2s. This endpoint is only available in Sandbox; in production it returns a 404.

The request body is:

{
  "payroll_ids": ["pay_123", "pay_456"],
  "employee_ids": ["emp_123", "emp_456"] 
}

This will trigger an asynchronous workflow in Check to generate the filing data. Depending on the size of payroll data and employee count at the company, the async job will take a few minutes to complete.

The refresh_filings endpoint returns a 202 status once the async job is enqueued. If a job is already in progress for the company, the request is added to that job rather than starting a second one.

You will receive a created webhook with the topic company_filing, containing the data that was created.

Simulating the filing lifecycle

After you have created filings in Sandbox, you can call the List filings endpoint to see the filings in the Tax Filing API at GET /filings?company=com_123.

To simulate Check's submission of a specific filing, you can POST to the Simulate filing endpoint at /filings/:filing_id/simulate/simulate_filing. Like the other endpoints on this page, it is only available in Sandbox.

The endpoint takes a request body of {"status": "pending" | "submitted" | "filed"}.

Simulating the filing will return the updated filing object as if Check had completed the filing. The status will transition to the specified status.

The response body follows the same format as the The filing object.

You will receive an updated webhook with the topic company_filing, containing the modified data.

Simulating failed filings

To simulate filing failures, you may first add blocked reasons to the filing, then simulate the filing using the API described above.

You can POST to the Add blocked reason endpoint at /filings/:filing_id/simulate/add_blocked_reason with the following body:

{
  "blocked_reason": "poa_failure" // one of the blocked reasons listed below
}

Adding a blocked reason will transition the filing to a status of blocked.

The response body follows the same format as the The filing object.

You will receive an updated webhook with the topic company_filing, containing the modified data.

Possible blocked reasons

You can add most of the blocked reason codes documented in the Filing blockers section of the Tax Filings guide, which is the source of truth for the full list and each code's meaning. Two kinds are refused:

• Blockers that Check sets automatically: applied_for_tax_id, missing_tax_funds, collection_failed, and company_bad_standing. These can't be added here.
• Blockers that apply only in certain cases, such as incorrect_experience_factor, which applies only to Washington L&I filings. Adding one to a filing it doesn't apply to returns an error whose message explains why.

See Add blocked reason for the error codes.

Simulating failed filing resolution

To simulate resolving a filing failure, you may remove a blocked reason from the filing, then simulate the filing again using the API described above.

You can POST to the Remove blocked reason endpoint at /filings/:filing_id/simulate/remove_blocked_reason with the same body format as above:

{
  "blocked_reason": "poa_failure" // one of the blocked reasons listed above
}

Removing all blocked reasons will transition the status to pending.

The response body follows the same format as the The filing object.

You will receive an updated webhook with the topic company_filing, containing the modified data.

Then you can call /filings/:filing_id/simulate/simulate_filing to simulate the actual filing again, transitioning the filing to a status of filed.