Tax Filings
Gain visibility into the status of quarterly tax filings
On a quarterly basis, Check files returns with tax agencies on behalf of the companies for which it runs payroll. Using Check's List tax filings endpoint, users can gain visibility into these Tax Filings and notify employers of failed filings, which may require follow-up actions. Additionally, Check will send webhooks upon the creation, update, and deletion of any Tax Filings.
The initial version of this API will only contain failed filings. In future versions, this API will include all filings across the entire filing lifecycle, regardless of whether or not they've failed.
Tax Filing Lifecycle
Upon creation, a Tax Filing will have a description, frequency, period, and status. It will also have a Tax Filing Event, which represents the status transitions of a Tax Filing. When displayed together, Tax Filing Events display an immutable event log that represents the lifecycle of a Tax Filing. The status of the most recent Tax Filing Event will populate the status of the Tax Filing related to it. Tax Filing Events are returned in descending order of their created_at values.
See Tax filing status to see the list of all possible status values for a given Tax Filing. From a lifecycle perspective, a Tax Filing can transition through these stages as seen below:
Listing Tax Filings
Below is an example response of the List tax filings API.
{
"id": "flg_GaeJoEAzbqqc2D9GMfOF",
"company": "com_vIFHhvyGN47ej1upyIT8",
"year": 2023,
"description": "Michigan State Unemployment Tax",
"frequency": "quarterly",
"period": "q2",
"status": "filed",
"can_retry": false,
"tax_filing_events": [
{
"id": "fev_jIFHhvyGN47ej1upyIT8",
"tax_filing": "flg_jIFHhvyGN47ej1upyIT8",
"status": "filed",
"created_at": "2023-04-12T21:32:44.957364Z",
"category": null,
"label": null,
"account_number": "123456789",
},
{
"id": "fev_jupyIT8upyIT8upyIT87",
"tax_filing": "flg_jIFHhvyGN47ej1upyIT8",
"status": "submitted",
"created_at": "2023-04-12T21:32:44.957364Z",
"category": null,
"label": null,
"account_number": "123456789",
},
{
"id": "fev_jHhvyHhvyHhvyHhvyHhv",
"tax_filing": "flg_jIFHhvyGN47ej1upyIT8",
"status": "pending",
"created_at": "2023-04-12T21:32:44.957364Z",
"category": null,
"label": null,
"account_number": "123456789",
},
{
"id": "fev_7ej1upy7ej1upy7ej1up",
"tax_filing": "flg_jIFHhvyGN47ej1upyIT8",
"status": "rejected",
"created_at": "2023-04-12T21:32:44.957364Z",
"category": "applied_for_invalid_ein",
"label": "EIN is either invalid or Applied For. Return will not be accepted by the agency. If filed, the agency will reject the return",
"account_number": "Applied For",
},
{
"id": "fev_pyITpyITpyITpyITpyIT",
"tax_filing": "flg_jIFHhvyGN47ej1upyIT8",
"status": "submitted",
"created_at": "2023-04-12T21:32:44.957364Z",
"category": null,
"label": null,
"account_number": "Applied For",
},
{
"id": "fev_GN47eGN47eGN47eGN47e",
"tax_filing": "flg_jIFHhvyGN47ej1upyIT8",
"status": "pending",
"created_at": "2023-04-12T21:32:44.957364Z",
"category": null,
"label": null,
"account_id": "Applied For",
},
],
}
Testing in Sandbox
While the production endpoints for the Tax Filing API are read-only (GET and LIST), Check also exposes POST endpoints in sandbox to help mock a more comprehensive integration experience. These endpoints will enable you to test the full Tax Filing lifecycle in your product.
To try this out, first create a Tax Filing via the POST /tax_filings endpoint and then transition the Tax Filing through the entire lifecycle via the POST /tax_filing_events endpoint.
Lastly, Tax Filing resources are unique and immutable for a given combination of company, year, period, tax. This means that once a Tax Filing is created for a given combination, it cannot be created again with the same request body. If such a request is made, a 400 error will be raised.
POST /tax_filings
Creation of a new Tax Filing will also create a pending Tax Filing Event
Request Body
{
"company": "com_vIFHhvyGN47ej1upyIT8",
"year": 2023,
"tax": "tax_uG74nkmtogYKRKBm2ArU",
"period": "q2",
"account_number": "Applied For",
}
Response Body
{
"id": "flg_GaeJoEAzbqqc2D9GMfOF",
"company": "com_vIFHhvyGN47ej1upyIT8",
"year": 2023,
"description": "Michigan State Unemployment Tax",
"frequency": "quarterly"
"period": "q2",
"status":"pending",
"can_retry": false,
"tax_filing_events":[
{
"id": "fev_GN47eGN47eGN47eGN47e",
"tax_filing": "flg_GaeJoEAzbqqc2D9GMfOF",
"status": "pending",
"created_at": "2023-04-12T21:32:44.957364Z",
"category": null,
"label": null
"account_number": "Applied For",
},
],
}
POST /tax_filing_events
Creation of a new Tax Filing Event will update the Tax Filing’s status and trigger a STATUS_CHANGE webhook with a tax_filing topic.
Request Body
{
"tax_filing": "flg_GaeJoEAzbqqc2D9GMfOF",
"status": "submitted",
"category": null,
"label": null
"account_number": "Applied For",
}
Response Body (same as GET tax_filing_events/{tax_filing_event_id}
{
"id" : "fev_jIFHhvyGN47ej1upyIT8",
"tax_filing": "flg_GaeJoEAzbqqc2D9GMfOF",
"status": "submitted",
"created_at": "2023-04-12T21:32:44.957364Z",
"category": null,
"label": null
"account_number": "Applied For",
}
The triggered webhook will have the following payload with the newly created submitted Tax Filing Event as 0-indexed objected within the tax_filing_events list:
{
"id": "flg_GaeJoEAzbqqc2D9GMfOF",
"company": "com_vIFHhvyGN47ej1upyIT8",
"year": 2023,
"description": "Michigan State Unemployment Tax",
"frequency": "quarterly",
"period": "q2",
"status": "submitted",
"can_retry": false,
"tax_filing_events":[
{
"id": "fev_jIFHhvyGN47ej1upyIT8",
"tax_filing": "flg_GaeJoEAzbqqc2D9GMfOF",
"status": "submitted",
"created_at": "2023-04-12T22:00:00.957364Z",
"category": null,
"label": null
"account_number": "Applied For",
},
{
"id": "fev_GN47eGN47eGN47eGN47e",
"tax_filing": "flg_GaeJoEAzbqqc2D9GMfOF",
"status": "pending",
"created_at": "2023-04-12T21:32:44.957364Z",
"category": null,
"label": null
"account_number": "Applied For",
},
],
}
Updated 9 months ago