IRS IRIS XML Format Guide

IRIS XML Schema Overview

The IRS IRIS system accepts XML submissions through the A2A (Application-to-Application) channel. The separate Taxpayer Portal supports manual entry and IRS CSV templates; it does not accept user-supplied XML files.

Publication 5718 explains the A2A specifications. Obtain the separate IRS schema and business-rule package through the IRS A2A setup steps. The schema defines every element, attribute, data type, and constraint for each supported form type. Your XML must validate against these XSD files before the IRS will accept the submission.

Unlike FIRE's flat, position-based format, IRIS XML is hierarchical. Data is organized into nested elements with explicit names, making it self-describing and easier to validate — but also more verbose and more complex to generate correctly.

Key XML Elements

The TY2025 schema uses IRTransmission in the namespace urn:us:gov:treasury:irs:ir. Its manifest identifies the transmission; submission groups contain issuer headers and form-specific recipient records.

Download the complete TY2025 1099-NEC XML example. This synthetic example passes the IRS TY2025 2.0.3 XSD package. It uses placeholder credentials and a test indicator, so it is for local format checks only, not transmission or proof of IRS acceptance.

Structure excerpt: The shortened XML below omits required fields to show the hierarchy. Use the complete download when testing schema validation.

<IRTransmission xmlns="urn:us:gov:treasury:irs:ir">
  <IRTransmissionManifest>
    <SchemaVersionNum>2.0.3</SchemaVersionNum>
    <!-- Additional required manifest fields are in the complete example. -->
  </IRTransmissionManifest>
  <IRSubmission1Grp>
    <IRSubmission1Header>
      <SubmissionId>1</SubmissionId>
      <TaxYr>2025</TaxYr>
      <!-- IssuerDetail, form type, counts, and totals go here. -->
    </IRSubmission1Header>
    <IRSubmission1Detail>
      <Form1099NECDetail>
        <!-- Record identifiers and RecipientDetail precede the amounts. -->
        <NonemployeeCompensationAmt>1234.56</NonemployeeCompensationAmt>
        <!-- Other required and applicable fields are omitted in this excerpt. -->
      </Form1099NECDetail>
    </IRSubmission1Detail>
  </IRSubmission1Grp>
</IRTransmission>

Manifest Element

IRTransmissionManifest contains the schema version, unique transmission identifier, tax year, original/correction/replacement indicator, test indicator, transmitter information (including your IRIS-specific TCC), software information, and counts. Follow the exact sequence in the XSD. A SubmissionId belongs in a submission header; it is not a substitute for the manifest's UniqueTransmissionId.

FormData Element

Form data is organized into the IRS-defined submission groups, not a literal FormData element. In the example, IRSubmission1Grp contains IRSubmission1Header and IRSubmission1Detail. The header identifies the issuer and form type; the detail contains Form1099NECDetail records. Other form families use the groups specified in their schema.

Payer Element

The payer is represented by IssuerDetail in the submission header. This is the information commonly mapped from a FIRE A record:

• TIN and type: TIN and TINSubmittedTypeCd identify the issuer. Use the allowed values from the schema and confirm the actual TIN type.
• Legal name: Use the applicable business or person name group, including the name-control field where required.
• Address: MailingAddressGrp contains the applicable U.S. or foreign address structure.
• Contact details: Populate the required phone and other contact fields in their defined locations.

Payee Element

A recipient is represented by RecipientDetail inside the form-specific detail record. This corresponds to information from a FIRE B record:

• Identity: The recipient's TIN, TINSubmittedTypeCd, name, and address groups.
• Record information: The tax year, record ID, correction indicator, and applicable account number.
• Amount elements: Form-specific elements such as NonemployeeCompensationAmt and FederalIncomeTaxWithheldAmt for Form 1099-NEC.
• State information: Use the form's supported state/local groups and applicable CF/SF election. Federal XML validation alone does not establish that a state filing obligation is satisfied.

Supported Form Types in the XML Schema

IRIS supports a range of information return form types. Coverage depends on the tax year and processing year; confirm it against the IRS supported-form list and your schema package. These TY2025 examples show detail elements and the data they report:

TY2025 Detail Element	Form	Reported Data (Examples)
<Form1099NECDetail>	1099-NEC	Nonemployee Compensation, Federal Income Tax Withheld
<Form1099MISCDetail>	1099-MISC	Rents, Royalties, Other Income, Fishing Boat Proceeds, Medical Payments, Substitute Payments, Crop Insurance, Attorney Fees, Fish Purchased, Section 409ADeferrals, Nonqualified Deferred Compensation
<Form1099INTDetail>	1099-INT	Interest Income, Early Savings Withdrawal Penalty, U.S. Bond Interest, Federal Income Tax Withheld, Investment Expenses, Foreign Tax Paid, Tax Exempt Interest, Private Activity Bond Interest, Market Discount, Bond Premium
<Form1099DIVDetail>	1099-DIV	Ordinary Dividends, Qualified Dividends, Capital Gain Distributions, Unrecaptured Section 1250Gain, Section 1202Gain, Collectibles Gain, Nondividend Distributions, Federal Income Tax Withheld, Foreign Tax Paid
<Form1099RDetail>	1099-R	Gross Distribution, Taxable Amount, Capital Gain, Federal Income Tax Withheld, Employee Contributions, Net Unrealized Appreciation, Distribution Codes
<Form1099KDetail>	1099-K	Gross Amount, Card Not Present, Monthly Amounts (Jan-Dec), Federal Income Tax Withheld, Number Of Payment Transactions
<Form1099BDetail>	1099-B	Proceeds, Cost Basis, Market Discount, Wash Sale Loss Disallowed, Federal Income Tax Withheld, Gain Loss Indicator
<Form1099SDetail>	1099-S	Gross Proceeds, Buyer Part Of Real Estate Tax
<Form1099CDetail>	1099-C	Amount Of Debt Discharged, Interest Included, Debt Description, Identifiable Event Code
<Form1099SADetail>	1099-SA	Gross Distribution, Earnings, Distribution Code
<Form1098Detail>	1098	Mortgage Interest, Points Paid, Refund Of Overpaid Interest, Mortgage Insurance Premiums, Outstanding Mortgage Principal
<FormW2GDetail>	W-2G	Gross Winnings, Federal Income Tax Withheld, Type Of Wager, Date Won

The full list of elements and their data types is defined in the IRS XSD files. Always use the latest published schema for the tax year you are filing.

Validation Rules and Common Errors

IRIS applies multi-layer validation to every XML submission. Understanding these rules is critical for building a reliable integration:

Schema Validation (XSD)

The first layer is XML schema validation. Your submission must conform to the published XSD. Common failures:

Error	Cause	Fix
Missing required element	A required TIN, TaxYr, or group is omitted	Supply the required value and honor schema choice groups; do not fill every missing field with zero
Invalid element order	Child elements out of sequence	Follow exact element order specified in XSD
Invalid data type	Amount field contains non-numeric characters	Use xs:decimal format: 50000.00
Unexpected element	Using an element that does not exist in the schema	Check element names against the current-year XSD
Namespace mismatch	Root element does not declare the correct namespace	Use the IRS-published namespace URI exactly

Business Rule Validation

After XSD validation, check the IRS business rules for the same release. They can require fields that are optional in the XSD, check totals and indicators, and validate relationships between records. Name/TIN matching and transmission authorization also require information that a local schema check cannot establish.

Retain the IRS acknowledgment and record identifiers. Use the documented correction or replacement process when appropriate; resubmitting an accepted original can create duplicate reporting. See the IRIS error-code guide for help interpreting responses.

Common Developer Mistakes

<!-- Convert FIRE implied cents to dollars: 0000000123456 becomes 1234.56. -->
<NonemployeeCompensationAmt>1234.56</NonemployeeCompensationAmt>

<!-- TINs have no display hyphens; use the correct parent group and type code. -->
<TIN>330000001</TIN>
<TINSubmittedTypeCd>BUSINESS_TIN</TINSubmittedTypeCd>

<!-- Let your XML library escape a literal ampersand in the business name. -->
<BusinessName>
  <BusinessNameLine1Txt>Smith &amp; Jones LLC</BusinessNameLine1Txt>
</BusinessName>

Check an existing file: Use the free TY2026 IRIS XML validator for a local schema check of TY2026 files. Validate this guide's TY2025 download with the matching TY2025 package and the code examples below. If you are starting with Publication 1220 data, use the FIRE-to-IRIS converter. Review the supported tax year before uploading or converting.

Testing with the IRIS Sandbox Environment

The IRS provides a testing (sandbox) environment for A2A integrations. You should test every submission scenario before going to production. Key points:

• ATS access: Follow the IRS Assurance Testing System requirements for your A2A role, software, and TCC. Complete the applicable software or communication test before production.
• Test endpoint: Use the designated ATS endpoint and test indicator. A test flag does not make a production endpoint suitable for experiments.
• Test data: Use the data specified in the IRS test scenarios. The downloadable example on this page is for local XSD validation and is not an IRS ATS test scenario.
• Availability and results: Check the published test-system schedule and review acknowledgments. A successful local schema check is only one part of testing.

Follow the IRIS testing and sandbox guide alongside the current IRS ATS instructions.

Test the following scenarios at minimum:

1. Original submission with a single payer and payee
2. Multi-payee submission (50+ payees under one payer)
3. Multi-payer submission (multiple payer groups in one file)
4. Correction submission linked to the previously accepted record using its IRS UniqueRecordId
5. Submission with state tax information (Combined Federal/State)
6. Submission with foreign payee addresses
7. Invalid submission (intentional errors) to verify error handling

A2A vs Taxpayer Portal: Key Differences

The IRS offers two ways to submit through IRIS. Understanding the differences helps you choose the right approach:

Feature	A2A (Application-to-Application)	Taxpayer Portal
Input method	XML via REST API	Browser-based UI (manual entry or CSV upload)
Authentication	IRS API Client ID and the authentication flow specified for A2A	IRS ID.me identity verification
Volume capacity	Designed for high volume (thousands of forms)	Practical for smaller volumes
TCC requirement	Required (A2A-specific TCC type)	IRIS Taxpayer Portal TCC required
Automation	Fully automated, no human interaction	Manual process, requires browser session
XML knowledge	Required — you build and submit XML directly	Not required — portal users enter data manually or use IRS CSV templates
Error handling	Programmatic XML responses for automated processing	On-screen error messages
Best for	Software companies, service bureaus, enterprise IT	Small businesses, occasional filers

For a detailed guide on setting up A2A integration, including authentication and endpoint configuration, see our IRIS API integration guide.

Tools and Libraries for XML Generation

If you are building your own IRIS XML generation, here are approaches by language:

.NET / C#

Generate model classes from the complete IRS XSD package, populate its actual types, and serialize using an XML library. Validate the output before building the transmission request. This example validates the downloadable TY2025 file:

using System.Xml;
using System.Xml.Schema;

// Keep the complete IRS schema package and its relative directories together.
var settings = new XmlReaderSettings { ValidationType = ValidationType.Schema };
// Resolve includes from the trusted, locally extracted IRS schema package.
settings.Schemas.XmlResolver = new XmlUrlResolver();
settings.Schemas.Add("urn:us:gov:treasury:irs:ir",
    "MSG/IRS-IRIntakeTransmissionMessage.xsd");
settings.ValidationEventHandler += (_, e) =>
    throw new XmlSchemaValidationException(e.Message);

using var reader = XmlReader.Create("ty2025-1099-nec-iris-example.xml", settings);
while (reader.Read()) { }
// Passing XSD validation does not verify credentials or IRS business rules.

Python

Use namespace-aware XML elements or schema-generated models when constructing a file. The lxml example below validates and serializes the complete sample; it does not transmit returns:

from lxml import etree

# Use the complete IRS package for the same tax year as your XML.
schema = etree.XMLSchema(etree.parse("MSG/IRS-IRIntakeTransmissionMessage.xsd"))
parser = etree.XMLParser(resolve_entities=False, no_network=True)
document = etree.parse("ty2025-1099-nec-iris-example.xml", parser)
schema.assertValid(document)  # Raises DocumentInvalid for XSD failures.

# Serialize with the declared encoding; the XML library handles escaping.
document.write("validated-example.xml", encoding="UTF-8", xml_declaration=True)
# Check the matching business rules and filing workflow separately.

Java

Use a namespace-aware XML library or models generated from the actual IRS XSD package to build the transmission. Validate the serialized XML against MSG/IRS-IRIntakeTransmissionMessage.xsd, keeping the package's relative schema references intact. The downloadable example provides a starting point for checking your Java validation workflow.

These approaches assume the IRS package is extracted with its MSG, COMMON, and other included directories intact. Select the matching tax-year release. If you need A2A access first, follow the IRS IRIS registration and TCC application guide.

BoomTax API: Skip XML Generation Entirely

Building and maintaining an IRIS XML generator is a significant engineering investment. The IRS updates schemas annually, form types change, validation rules evolve, and edge cases multiply. If you do not want to maintain this infrastructure, the BoomTax API provides an alternative:

• JSON in, IRIS filing out: Submit your data as simple JSON to the BoomTax REST API. No XML, no XSD, no schema validation on your side.
• BoomTax handles XML generation: We build the IRIS-compliant XML, validate it, and submit through IRIS.
• Status tracking: Poll the API for submission status, acknowledgments, and any errors.
• Corrections: Submit correction data through the API; BoomTax generates the correction XML with the required reference to the previously accepted record.
• All form types: The API supports all 1099 series forms and other information return types.

If you already have FIRE-format files, you can also upload them directly to BoomTax for parsing and filing through our service. For spreadsheet data, see our CSV/Excel bulk upload guide.

For organizations evaluating build vs. buy: building your own IRIS XML generation requires 4-12 weeks of development, ongoing maintenance for annual schema updates, and a dedicated testing process against the IRIS sandbox. The BoomTax API or file upload eliminates all of this.

Frequently Asked Questions