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.

Applicable states for company-level filings

Currently, generating test filings for companies will only work in the following states. We will update this guide as we include additional states:

• Texas
• Indiana
• Kansas
• Tennessee
• Missouri
• Maryland
• Oklahoma

Generating test Filings

If you have a Sandbox company with payroll data, you can POST to the /companies/:company_id/refresh_filings endpoint 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.

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 will return:

• A 202 status when the async job is enqueued
• A 200 status if there is already a job in progress for that company with the same payroll and employee data

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 /filings/:filing_id/simulate/simulate_filing with no request body.

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

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 /filings/:filing_id/simulate/add_blocked_reason with the following body:

{
  "blocked_reason": "applied_for_tax_id" // any 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

• already_filed
• applied_for_tax_id
• 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

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 /filings/:filing_id/simulate/remove_blocked_reason with the same body format as above:

{
  "blocked_reason": "applied_for_tax_id" // any 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.