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

Create filings for a company

Pre-requisite: Generate a company in Sandbox with basic payroll data. Once you have a company with payroll data, you'll be able to simulate filing of that payroll data.

If you have a Sandbox company that has payroll data, you can POST to the /companies/:company_id/refresh_filings endpoint with the payroll IDs and employee IDs for which you want generate filings.

The request body is:

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

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

The refresh_filingsendpoint will return a 202 when the async job is enqueued, or a 200 if there is already a job in progress for that company with the same payroll and employee data.

You will get a created webhook with the topic company_filing, encapsulating the data 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_filingwith no request body.

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

The response body is the same as the The filing object.

You will get an updated webhook with the topic company_filing, encapsulating the data modified.

Simulating failed filings

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

You can POST to /filings/:filing_id/simulate/add_blocked_reasonwith the following body:

{
  "blocked_reason": "applied_for_tax_id" // any of the blocked reasons below
}

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

The response body is the same as the The filing object.

You will get an updated webhook with the topic company_filing, encapsulating the data modified.

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 filing, then simulate the filing again using the API above.

You can POST to /filings/:filing_id/simulate/remove_blocked_reasonwith the same body as above:

{
  "blocked_reason": "applied_for_tax_id" // any of the blocked reasons below
}

Removing all blocked reasons will transition the status to pending .

The response body is the same as the The filing object.

You will get an updated webhook with the topic company_filing, encapsulating the data modified.

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