Migrating from the Legacy Tax Filings API

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
`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 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`	`already_filed`
`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

Update your webhook endpoints to listen for company_filing events instead of tax_filing
Replace API calls from the legacy Tax Filings API to the new Filings API endpoints
Update status handling to use the new status values and blocking_reasons
Modify event processing to use status_history instead of filing_events
Test your integration with both successful and blocked filing scenarios