--- updatedAt: 2026-06-18T14:40:34.000Z agentTools: projectIndex: https://docs.checkhq.com/llms.txt --- # Migrating from the Legacy Tax Filings API A comprehensive guide for migrating from the legacy Tax Filings API to the new Filings API, including status mappings, event changes, and webhook updates. ## Overview The new Filings API provides a more comprehensive view of the tax filing lifecycle compared to the legacy Tax Filings API. While the legacy API only showed filings after they failed, the new API displays all filings—including future ones based on your payroll setup and activity. **Key Benefits:** * View upcoming filings before they're due * Monitor all filing statuses in one place * Get a complete picture of your filing timeline * Maintain all existing failed filing functionality ## Status Changes The new API uses different status names and logic. Here's how legacy statuses map to the new system: | Legacy Status | New Status | What This Means | | :------------------- | :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pending` | `pending` | Check is creating the tax return for your company. | | `submitted` | `pending` | Filings stay in `pending` status until the tax agency responds with success or failure. | | `filed` | `filed` | The tax agency has accepted your return. This is now a final status that won't change. | | `rejected` | `blocked` | Filings may be marked as `blocked` before filing (due to issues like pending tax ID applications) or after agency rejection. The `blocking_reasons` field tells you exactly what needs to be fixed. | | `amendment_required` | N/A | Instead of this status, filing objects now include an `amended_by` field. Check this field to see if an amendment exists, then query that specific filing object for details. | ## Event Tracking Changes **Legacy:** Used `tax_filing_events` to track filing history\ **New:** Uses `status_history` for complete filing lifecycle tracking The new `status_history` provides a chronological record of every status change. When a filing becomes `blocked`, the `blocking_reasons` field explains what went wrong and how to fix it. ## Complete Field Mapping ### TaxFiling → Filing Object | Legacy Field | New Field | Notes | | :-------------- | :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` (`tlg_`) | `id` (`com_fil_`) | Different ID prefix in new API | | `company` | `company` | Same field | | `year` | `year` | Same field | | `description` | `label` | Renamed for clarity | | `frequency` | Derived from `period` | No longer a separate field. Quarterly filings show periods like Q1, Q2, etc. Monthly filings show specific months. Note: Some filings occur only in the first two months of a quarter (like Illinois monthly SUI)—these show the specific month but aren't necessarily monthly frequency. | | `period` | `period` | Now uses standardized values: Q1, Q2, Q3, Q4, annual, january, february, march, april, may, june, july, august, september, october, november, december, weekly, semi\_monthly | | `status` | `status` | Same field name, different possible values (see status mapping above) | | `can_retry` | N/A | No longer needed—`blocked` filings can always be retried after resolving the blocking issues | | `filing_events` | `status_history` | Renamed and enhanced with more detailed tracking | ### TaxFilingEvent → Status History Entry | Legacy Field | New Field | Notes | | :--------------- | :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` (`fev_`) | N/A | Individual events no longer have separate IDs | | `tax_filing` | N/A | Event is now part of the filing object | | `status` | `status` | Same concept | | `created_at` | `status_at` | Renamed for clarity | | `category` | `blocked_reason.type` | Now part of the blocked reason structure | | `label` | `blocked_reason.type` | Same as category | | `account_number` | N/A | Get this by using the `resource` field in `status_history.blocked_reasons` to query the [Company Tax Parameters](https://docs.checkhq.com/reference/list-company-tax-parameters) API | ### Blocking Reason Categories | Legacy Category | New Category | | :----------------------------- | :------------------------ | | `applied_for_invalid_ein` | `applied_for_tax_id` | | `poa_tpa_failure` | `tpa_failure` | | `partial_failure_invalid_ssn` | `invalid_ssn` | | `already_filed` | `filed_by_customer` | | `not_liable` | `not_liable` | | `corrected_and_refiled_timely` | N/A | | `inactive_account` | `inactive_account` | | `missing_prior_quarter` | `missing_prior_quarter` | | `missing_historical_data` | `missing_historical_data` | | `invalid_tax_rate` | `invalid_tax_rate` | ## Webhook Changes **Legacy Topic:** `tax_filing`\ **New Topic:** `company_filing` | Legacy Event | New Event | Notes | | :-------------- | :-------- | :---------------------------------------------------------- | | `created` | `created` | Same functionality | | `updated` | `updated` | Same functionality | | `status_change` | `updated` | Status changes now trigger the general `updated` event | | `deleted` | N/A | Filings that need deletion are now marked as `inapplicable` | ## Migration Checklist 1. **Update your webhook endpoints** to listen for `company_filing` events instead of `tax_filing` 2. **Replace API calls** from the legacy Tax Filings API to the new Filings API endpoints 3. **Update status handling** to use the new status values and `blocking_reasons` 4. **Modify event processing** to use `status_history` instead of `filing_events` 5. **Test your integration** with both successful and blocked filing scenarios