Migrating from the Legacy Tax Filings API

The legacy Tax Filings API only provided visibility into filings after a filing failure occurred, whereas the new Filings API surfaces all filings, including those in the future based on payroll setup and activity. Existing integrations can replicate any failed filing experience, but also show a more holistic summary of filing status (what's upcoming, what's filed, etc.)

Filing Statuses

Legacy Status	New Status	Explanation
`pending`	`pending`	Check is in the process of creating the tax return for the company.
`submitted`	`pending`	Filings will remain in `pending` until a success or failure response is returned by tax agencies.
`filed`	`filed`	The return has been accepted by the agency as filed. This status is now a terminal state.
`rejected`	`blocked`	In the new API, filings may be flagged as `blocked` before filing is attempted due to known blocking reasons (like an applied-for-tax-ID). They will also be marked as `blocked` after rejection from an agency, with accompanying blocking reasons indicating path to resolution.
`amendment_required`	N/A	Filing objects now have an `amended_by` field that may be used to determine that an amendment is needed, and resolve the status and any details about that amendment by querying its filing object directly.

Filing Events

tax_filing_events is replaced by status_history, which provides a complete chronology of a filing's progression through its lifecycle. When status goes to blocked, blocking_reasons indicate the problem and subsequent path to resolution.

Complete Mapping From Legacy Objects

TaxFiling to Filing

Legacy	New	Details
`id` (`tlg_`)	`id` (`com_fil_`)
`company`	`company`
`year`	`year`
`description`	`label`
`frequency`	Can be derived from `period`
`period`	`period`
`status`	`status`
`can_retry`	N/A	`blocked` filings may always be re-attempted after resolving blockers
`filing_events`	`status_history`

TaxFilingEvent

Legacy	New	Details
`id` (`fev_`)	N/A
`tax_filing`	N/A
`status`	`status`
`created_at`	`status_at`
`category`	`blocked_reason.type`
`label`	`blocked_reason.type`
`account_number`	N/A	Can be retrieved from Company Tax Parameters

Category to BlockedReason

Legacy	New
`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`

Webhooks

Previous topic: tax_filing

New topic: filing

Legacy	New	Details
`created`	`created`
`updated`	`updated`
`status_change`	`updated`
`deleted`	N/A	Filings that need to be deleted are set to `not_applicable`