Skip to main content
Version: 1.7.3

API Components

Understanding the structure of TaxBandits API requests is essential to building a clean, reliable integration. This page covers the key components that make up the request body across form types, and the unique identifiers used throughout the API.

1099 Forms​

Most form creation and update requests in the TaxBandits API share a common top-level structure.

ComponentDescription
SubmissionManifestDefines the tax year and scheduling options for the submission
ReturnHeaderContains the business (payer or employer) details for the submission.
ReturnDataAn array of recipient, filing services, and form-level records. Up to 250 records per request.

This page describes the API request structure for v2.0. If you are on v1.7.3, the structure may differ slightly. Refer to the v1.7.3 API Reference for the corresponding details.

SubmissionManifest​

The SubmissionManifest object applies to the entire submission. It defines what tax year is being filed and which services are opted into.

FieldDescription
TaxYearThe tax year for which forms are being filed.
IsFederalFilingSet to TRUE to schedule transmission to a future date
IsStateFiling or StateFilingThe date to transmit to the IRS. Required when IsScheduleFiling is TRUE. Format: MM/DD/YYYY

In v2.0, Filing services are configured at the ReturnManifest level within each record in ReturnData, not at the submission level. This allows different distribution preferences per recipient within the same submission.

ReturnHeader​

The ReturnHeader object contains the business (payer or employer) details that apply to all records in the submission. The Business object within ReturnHeader is shared across 1099, W-2, 94X, and ACA forms.

You can either provide full business details when a business is being created or referenced using BusinessId or PayerRef.

Key fields​

FieldDescription
BusinessIdUnique identifier generated by TaxBandits when a business is created. Use this to reference an existing business without repeating its details.
PayerRefYour own identifier for the business. Can be used in place of BusinessId.
TINDetailsTIN information for the business. Includes Format (PLAIN_TIN, ENCRYPTED_TIN, or TOKENIZED_TIN) and TINType, and TIN.
BusinessNmLegal name of the business. Required when TINType is EIN.
IndividualNmRequired when TINType is SSN. Provide FirstNm and LastNm instead of BusinessNm.
DBADetailsOptional. DBA (Doing Business As) information. Each DBA has its own DBAId.
AddressPrimary address of the business.
ContactDetailsIRS contact person details for the business.

ReturnData​

ReturnData is an array that holds individual return records. Each record contains filing options, recipient details, and form data. Up to 250 records can be submitted in a single request.

ReturnManifest​

Defines the filing services for a specific record. Settings here override or supplement the submission-level configuration.

FieldDescription
IsFederalSet to TRUE to e-file the return with the IRS
IsStateSet to TRUE to file with the state agency. State filing will not be created for states that do not require it.
IsDistributionSet to TRUE to enable recipient copy distribution
DistributionDetails.DistributionTypeDistribution method.

Allowed values
  • POSTAL_ONLY
  • ONLINE_ACCESS
  • POSTAL_AND_ONLINE
DistributionDetails.PostalTypePostal service type.

Allowed value
  • USPS_FIRST_CLASS
IsForcedWhen TRUE, TaxBandits skips duplicate validation and creates a new return regardless of matching prior records

Recipient​

Contains the recipient's identity and contact details. You can reference an existing recipient using RecipientId or PayeeRef, or provide full recipient details inline.

FieldDescription
RecipientIdUnique identifier generated by TaxBandits for the recipient. Use to reference an existing recipient.
PayeeRefYour own identifier for the recipient. Can be used in place of RecipientId.
TINDetailsTIN information for the recipient. Includes Format, TINType, and TIN.
RecipientNmLegal name of the recipient business. Required when TINType is EIN.
FirstNmRequired when TINType is SSN, ITIN, or ATIN.
DBADetailsOptional DBA details for the recipient.
AddressPrimary address of the recipient.
EmailRequired when DistributionType includes ONLINE_ACCESS.

Form Data​

Form data fields are specific to each form type and are nested within the return record. For 1099-NEC, this object is NECFormData. For W-2, it is W2FormData, and so on.

Form data includes:

  • Federal income fields reported to the IRS
  • States array for state-level income and withholding data
  • StateReconData for state-specific reconciliation fields where required

W-2 Forms​

W-2 forms follow the same top-level structure as 1099 forms with the following differences:

  • ReturnData uses employee details rather than recipient details. The employee identifier is EmployeeId.
  • Federal data is reported to the SSA, not the IRS.
  • Form-specific fields such as KindOfEmployer and KindOfPayer must be set on the Business object.
  • StateReconData applies where required by state agencies.

94X Forms​

94X forms (941, 940, 943, 944, 945) use a slightly different top-level wrapper called Form94XRecords, which contains ReturnHeader and ReturnData.

Key requirements specific to 94X:

  • SigningAuthority must be set on the Business object before any 94X form can be filed.
  • BusinessType must also be set on the Business object.
  • Schedule R (for 941 and 940 aggregate filers) is submitted as part of the parent form's return data.

ACA Forms​

ACA forms (1094-C, 1095-C) follow the same SubmissionManifest, ReturnHeader, ReturnData structure. ACA-specific fields such as ACASpecific on the Business object apply only to these form types.

Unique Identifiers​

TaxBandits generates unique identifiers for every entity and record created through the API. These identifiers should be stored in your system for use in subsequent requests.

IdentifierScopeDescription
BusinessIdBusinessGenerated when a business is created. Primary reference for all form filings and entity operations.
PayerRefBusinessYour own identifier for the business. Accepted in place of BusinessId across all endpoints.
RecipientIdRecipientGenerated when a recipient record is created. Use to reference the recipient without repeating their details.
PayeeRefRecipientYour own identifier for the recipient. Accepted in place of RecipientId.
SubmissionIdSubmissionGenerated when a form submission is created. Required for Update, Get, and Transmit operations.
RecordIdReturn RecordGenerated for each individual return within a submission. Use to update or reference a specific record.
DBAIdDBAGenerated when a DBA is added to a business or recipient.
DBARefDBAYour own identifier for the DBA.

State Filing​

When IsState is TRUE in ReturnManifest, the States array inside the form data object must be populated with state-specific fields:

FieldDescription
StateCdTwo-letter state code
StateWHState income tax withheld
StateIdNumPayer's state identification number
StateIncomeState income amount
StateReconDataState-specific reconciliation data where required

State filing will not be created for states that do not require it, even if IsState is set to TRUE.