v1.7.3 → v2.0 Migration Guide
We release version upgrades to the TaxBandits Public API periodically, improving performance, addressing compliance changes, and keeping the platform aligned with how modern integrations are built. TaxBandits API 2.0 is a major upgrade of the Public API, designed for scale, security, and the direction the tax compliance landscape is heading.
v1.7.3 has served its purpose well. But the compliance landscape has shifted significantly — the IRS is retiring FIRE and mandating IRIS for all electronic information return filings, security expectations around sensitive data like TINs have risen, and the scale at which our integrators operate has grown considerably. Alongside this, the rise of AI-assisted development and no-code workflows has changed what developers expect from an API.
These aren't incremental changes. They call for a ground-up rebuild, and that's what v2.0 is.
Endpoint Currently Available in API 2.0
API 2.0 is released in phases. Each phase includes a sandbox period before going live, allowing integrators to test and validate changes ahead of production rollout.
Here are the endpoints that are currently available in version 2.0:
- Business
- Recipient
- Form W-2
- Form 1099-NEC
- Form 1099-MISC
- Form 1099-INT
- Form 1099-K
- Form 1099-SA
- Form 5498-SA
- Form W-2G
Additional endpoints and form types will be released in subsequent phases. Each phase will be communicated in advance, with sandbox access provided before the live rollout.
Key Changes in API 2.0
Before reviewing endpoint-specific changes, the following are architectural and behavioral changes that apply broadly across API 2.0.
1. Authentication Process
The OAuth in v2.0 introduces improved functionality, including scope-based access and category-level restrictions. The core authentication flow stays the same, and integrations on v1.7.3 will continue to function without changes. What's new is the addition of scopes and category-level restrictions, giving you finer control over token permissions when you choose to use them.
Review the OAuth documentation to see how these additions work and where they might be useful for your integration.
2. IRIS-Only Filing
With the IRS's transition to IRIS and the new requirements introduced under OBBBA, additional data points are now required as part of the filing process. This means changes to how information is collected through the API. v2.0 incorporates all of these changes, so your integration stays aligned with current IRS requirements as you migrate.
- The IRS is retiring the FIRE system starting in January 2027. After this date, all filings — including prior tax years and any corrections — must be filed through IRIS.
- Tax Year 2026 is only supported in v2.0. Prior tax years 2025 and 2024 are available in both v1.7.3 and v2.0.
3. Bulk Processing
In v1.7.3, operations like transmitting, checking status, and listing filings are performed against individual submissions. v2.0 shifts this to a bulk model — you can transmit, retrieve status, and list filings in bulk, scoped either to a specific business or across your entire account. This significantly reduces the number of calls required to manage filings at scale.
4. Standardized Node Naming
Request and response field names have been reviewed and standardized across v2.0. Some node names from v1.7.3 have been renamed or reorganized for consistency.
To make migration easier, we will provide a node-mapping document for every endpoint, showing exactly how each v1.7.3 field maps to its v2.0 equivalent. Refer to this document alongside the v2.0 API reference when updating your integration.
5. Standardized Request and Response Structure
v2.0 uses consistent request and response structures across form types. Common patterns — such as how errors are returned, how success and failure records are separated, and how bulk results are structured — are uniform across all endpoints.
6. Status Tracking
v2.0 provides more granular status information for transmitted returns. If your integration relies on status polling or status-based logic, the expanded status response structure in v2.0 should be reviewed and accounted for.
Migration Notes
The following sections outline what has changed for each endpoint in v2.0. Each section includes a comparison table followed by field-level details and integration guidance.
- OAuth 2.0
- Business endpoint
- Recipient endpoint
- 1099 endpoints
- W-2 endpoints
OAuth 2.0
v1.7.3 uses a standard OAuth token that grants broad access to the API. v2.0 introduces a scope-based token model, where each token is issued with an explicit scope and, optionally, restricted to specific endpoint categories.
- The scope defines which HTTP methods the token can use — read-only, write-only, or full access.
- The category restriction narrows the token further to specific areas of the API, such as 1099 forms, 94X payroll forms, or state payroll endpoints.
A token issued with Read scope and a 1099 category, for example, can only call GET methods on 1099 endpoints — nothing else.
This model gives integrators precise control over what each token can access, which is particularly useful for multi-tenant platforms, delegated access scenarios, and integrations where different workflows require different permission levels.
| v1.7.3 | v2.0 | |
|---|---|---|
| Token Scope | A single access token grants broad API access | Tokens are issued with explicit scopes - Read, Write, Read_Write, Transmit, or FullAccess - controlling exactly which HTTP methods the token can use. |
| Category Restrictions | No category-level restrictions on token access | Tokens can be restricted to specific endpoint categories — such as 1099 forms, 94X, ACA, or State Payroll — limiting access to only what is needed |
| Transmit Access | Transmit endpoint accessible with standard token | Transmit access requires a token issued with Transmit or FullAccess scope explicitly. |
Business Endpoint
| v1.7.3 | v2.0 | |
|---|---|---|
| Bulk Creation | One business per request | Up to 250 businesses in a single request. |
| TIN Handling | TIN passed as plain text directly in the payload | TIN wrapped in TINDetails object. Set Format to one of the following:* PLAIN - Pass the TIN directly as plain text in the payload.* ENCRYPTED - Pass the TIN in an encrypted format, recommended for the highest level of security* TOKEN - Pass a tokenized TIN obtained via the TIN Tokenization endpoint, recommended for the highest level of security. |
| Deactivation | Businesses cannot be deleted if a return has already been filed with the IRS — the business record remains active and appears in List and other endpoints even when no longer in use. | Deactivate suspends a business without deleting historical data. Even if the business has a return filed with the IRS, you can deactivate it. Once deactivated, these business records will not be included in the List and other endpoints unless it is requested or reactivated. Reactivate restores it. |
| DBA Management | DBA names can be included at business creation but cannot be managed independently | Dedicated endpoints are available for DBA creation and management. Each DBA has its own DBAId and can be managed separately from the business record. |
| Address Handling | Separate field configurations required for domestic and foreign addresses | Address type determined automatically based on the Country value — no separate configuration needed |
Recipient Endpoint
| v1.7.3 | v2.0 | |
|---|---|---|
| Entity Coupling | Recipients must be associated with a business at the time of creation | Recipients are created and stored globally — a single recipient record can be used across multiple businesses without needing to be linked each time. |
| Reusability | If the same recipient is associated with multiple businesses, a separate record must be created for each | A single recipient record identified by RecipientId can be linked to multiple businesses — no duplicate creation needed |
| TIN Handling | TIN passed as plain text directly in the payload | TIN wrapped in TINDetails object. Set Format to one of the following:* PLAIN - Pass the TIN directly as plain text in the payload.* ENCRYPTED - Pass the TIN in an encrypted format, recommended for the highest level of security.* TOKEN - Pass a tokenized TIN obtained via the TIN Tokenization endpoint, recommended for the highest level of security. |
| Deactivation | Recipients cannot be deactivated — only deleted | Deactivate suspends a recipient without deleting historical data. Even if the recipient has a return filed with the IRS, you can deactivate it. Once deactivated, these recipient records will not be included in the List and other endpoints unless it is requested or reactivated. Reactivate restores it. |
| DBA Support | DBA information not supported for recipients | DBA details can be maintained for recipients — useful when a recipient operates under a trade name rather than their legal name |
Form 1099 Endpoints
| v1.7.3 | v2.0 | |
|---|---|---|
| Filing Path | Supports both FIRE and IRIS. FIRE supported through Tax Year 2025 only. | IRIS only. The filing type selection is removed in v2.0 — all filings default to IRIS automatically. Any FIRE-specific logic in your integration must be removed. |
| Bulk Operations | Limited | Create and update up to 250 returns in a single payload. Additionally, separate endpoints support bulk creation via a .csv file or a FIRE format file as a background process. |
| Endpoint Design | Each 1099 form type has its own dedicated endpoints | Create, ValidateForm, Update, and Get endpoints remain form-specific. All other operations — status checks, submissions, and retrievals — use common utility endpoints shared across all 1099 form types |
| Node Naming | Field names vary across form types | Field names standardized across all 1099 forms in v2.0. Some nodes from v1.7.3 have been renamed or reorganized — review the v2.0 API reference for each form before updating your integration. |
| Request / Response Structure | Structure varies by form type | Consistent structure across all form types — errors, success records, and bulk results follow the same pattern |
| Status Tracking | Limited visibility into transmitted return processing | Detailed status logs and transmission tracking available |
Form W-2 Endpoint
| v1.7.3 | v2.0 | |
|---|---|---|
| Bulk Operations | Limited | Full bulk create, update, and management support via array-based payloads |
| Node Naming | Standard field naming | Field names standardized and updated in v2.0. Some nodes from v1.7.3 have been renamed or reorganized — review the v2.0 API reference before updating your integration |
| Request / Response Structure | Standard structure | Consistent structure across all form types — errors, success records, and bulk results follow the same pattern |
| Status Tracking | Limited visibility into transmitted return processing | Detailed status logs and transmission tracking available. |