IRS IRIS XML Format Guide

IRIS XML Schema Overview

The IRS IRIS system accepts XML submissions through two channels: the Taxpayer Portal (manual, browser-based) and the A2A (Application-to-Application) API (programmatic). Both channels use the same underlying XML schema, but the A2A channel is the one developers care about when building integrations.

The XML schema is published by the IRS in Publication 5717 and accompanying XSD (XML Schema Definition) files. 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

An IRIS XML submission consists of several core element groups. Here is the high-level structure:

<?xml version="1.0" encoding="UTF-8"?>
<IRISSubmission xmlns="urn:us:gov:treasury:irs:iris">

  <!-- 1. Manifest: Submission metadata -->
  <Manifest>
    <SubmissionId>uuid-format-unique-id</SubmissionId>
    <ElectronicPostmark>2026-01-15T10:30:00Z</ElectronicPostmark>
    <TaxYear>2025</TaxYear>
    <Transmitter>
      <TIN>123456789</TIN>
      <TCC>ABCDE</TCC>
      <TransmitterName>Filing Service Corp</TransmitterName>
    </Transmitter>
    <OriginalSubmissionId />  <!-- For corrections only -->
  </Manifest>

  <!-- 2. FormData: One or more form groups -->
  <FormData>

    <!-- 3. Payer block (one per payer per form type) -->
    <Form1099NEC>
      <Payer>
        <PayerTIN>987654321</PayerTIN>
        <PayerName>
          <BusinessName>Acme Corporation</BusinessName>
        </PayerName>
        <PayerAddress>
          <Address1>123 Main Street</Address1>
          <Address2 />
          <City>Springfield</City>
          <State>IL</State>
          <ZipCode>62704</ZipCode>
        </PayerAddress>
        <PayerPhone>2175551234</PayerPhone>
      </Payer>

      <!-- 4. Payee records (one per recipient) -->
      <Payee>
        <PayeeTIN>111223333</PayeeTIN>
        <TINType>SSN</TINType>
        <PayeeName>
          <FirstName>Jane</FirstName>
          <MiddleName>M</MiddleName>
          <LastName>Doe</LastName>
        </PayeeName>
        <PayeeAddress>
          <Address1>456 Oak Avenue</Address1>
          <City>Chicago</City>
          <State>IL</State>
          <ZipCode>60601</ZipCode>
        </PayeeAddress>
        <PayerAccountNumber>ACCT-12345</PayerAccountNumber>
        <NonemployeeCompensation>50000.00</NonemployeeCompensation>
        <FederalIncomeTaxWithheld>0.00</FederalIncomeTaxWithheld>
        <StateTaxInfo>
          <StateCode>IL</StateCode>
          <StateIdNumber>12345678</StateIdNumber>
          <StateIncome>50000.00</StateIncome>
          <StateTaxWithheld>0.00</StateTaxWithheld>
        </StateTaxInfo>
      </Payee>

      <!-- Additional Payee elements for more recipients... -->

    </Form1099NEC>
  </FormData>

</IRISSubmission>

Manifest Element

The Manifest is the envelope for every submission. It contains:

• SubmissionId: A unique identifier you generate (UUID format recommended). Must be unique across all your submissions.
• ElectronicPostmark: ISO 8601 timestamp of when the submission was created.
• TaxYear: The tax year for the returns being filed (e.g., "2025").
• Transmitter: Your organization's TIN and IRIS-specific TCC. Note: FIRE TCCs do not work with IRIS.
• OriginalSubmissionId: Used only for correction submissions. References the original submission being corrected.

FormData Element

Contains one or more form-type elements (e.g., <Form1099NEC>, <Form1099MISC>). Each form-type element groups a payer with its payees. A single submission can contain multiple form types, and each form type can contain multiple payer-payee groups.

Payer Element

Identifies the entity issuing the information returns. This maps to the A record in FIRE flat files. Key fields:

• PayerTIN: 9-digit EIN or SSN, no hyphens or formatting.
• PayerName: Contains <BusinessName> for entities or <FirstName>/<LastName> for individuals.
• PayerAddress: Structured address with separate elements for each component. Foreign addresses use a different element structure (<ForeignAddress>).
• PayerPhone: 10-digit phone number, digits only.

Payee Element

One per recipient. This is the core data element — equivalent to the B record in FIRE files. Contains:

• PayeeTIN: 9-digit TIN (SSN or EIN).
• TINType: Explicit indicator: "SSN", "EIN", or "ITIN". In FIRE, this was a single-digit code at position 11.
• PayeeName: Structured name with <FirstName>, <MiddleName>, <LastName>, <Suffix>, or <BusinessName>.
• PayeeAddress: Same structure as PayerAddress.
• Amount elements: Form-specific. For 1099-NEC: <NonemployeeCompensation>, <FederalIncomeTaxWithheld>. For 1099-MISC: <Rents>, <Royalties>, <OtherIncome>, etc.
• StateTaxInfo: State-level reporting data for Combined Federal/State filing.

Supported Form Types in the XML Schema

The IRIS XML schema supports all information return form types that were previously filed through FIRE, plus additional forms being migrated before the December 31, 2026 deadline. Each form type has its own XML element with form-specific amount fields:

XML Element	Form	Key Amount Fields
<Form1099NEC>	1099-NEC	NonemployeeCompensation, FederalIncomeTaxWithheld
<Form1099MISC>	1099-MISC	Rents, Royalties, OtherIncome, FishingBoatProceeds, MedicalPayments, SubstitutePayments, CropInsurance, AttorneyFees, FishPurchased, Section409ADeferrals, NonqualifiedDeferredCompensation
<Form1099INT>	1099-INT	InterestIncome, EarlySavingsWithdrawalPenalty, USBondInterest, FederalIncomeTaxWithheld, InvestmentExpenses, ForeignTaxPaid, TaxExemptInterest, PrivateActivityBondInterest, MarketDiscount, BondPremium
<Form1099DIV>	1099-DIV	OrdinaryDividends, QualifiedDividends, CapitalGainDistributions, UnrecapturedSection1250Gain, Section1202Gain, CollectiblesGain, NondividendDistributions, FederalIncomeTaxWithheld, ForeignTaxPaid
<Form1099R>	1099-R	GrossDistribution, TaxableAmount, CapitalGain, FederalIncomeTaxWithheld, EmployeeContributions, NetUnrealizedAppreciation, DistributionCodes
<Form1099K>	1099-K	GrossAmount, CardNotPresent, MonthlyAmounts (Jan-Dec), FederalIncomeTaxWithheld, NumberOfPaymentTransactions
<Form1099B>	1099-B	Proceeds, CostBasis, MarketDiscount, WashSaleLossDisallowed, FederalIncomeTaxWithheld, GainLossIndicator
<Form1099S>	1099-S	GrossProceeds, BuyerPartOfRealEstateTax
<Form1099C>	1099-C	AmountOfDebtDischarged, InterestIncluded, DebtDescription, IdentifiableEventCode
<Form1099SA>	1099-SA	GrossDistribution, Earnings, DistributionCode
<Form1098>	1098	MortgageInterest, PointsPaid, RefundOfOverpaidInterest, MortgageInsurancePremiums, OutstandingMortgagePrincipal
<FormW2G>	W-2G	GrossWinnings, FederalIncomeTaxWithheld, TypeOfWager, DateWon

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	Element like <PayerTIN> or <TaxYear> omitted	Include all required elements even if value is 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 schema validation passes, IRIS applies IRS business rules:

• TIN validation: EINs must start with valid prefixes (10-99, excluding certain ranges). SSNs must follow valid patterns. Invalid TINs are flagged, though the return may still be accepted with a "TIN mismatch" indicator.
• TCC authorization: Your TCC must be authorized for the form type you are filing. An A2A TCC authorized for 1099-NEC may not work for 1099-R if not specifically enabled.
• Duplicate detection: IRIS checks for duplicate submissions (same payer TIN + payee TIN + form type + tax year). Duplicates are rejected unless explicitly marked as corrections.
• Amount reasonableness: Extremely large amounts may trigger additional review or warnings.
• Date validation: Tax year must be valid and within the filing window. Postmarks outside the valid range are rejected.

Common Developer Mistakes

<!-- WRONG: Amount as integer (FIRE style) -->
<NonemployeeCompensation>5000000</NonemployeeCompensation>

<!-- CORRECT: Amount as decimal -->
<NonemployeeCompensation>50000.00</NonemployeeCompensation>

<!-- WRONG: TIN with hyphens -->
<PayerTIN>98-7654321</PayerTIN>

<!-- CORRECT: TIN as 9 digits, no formatting -->
<PayerTIN>987654321</PayerTIN>

<!-- WRONG: Empty element when field is required -->
<PayeeName></PayeeName>

<!-- CORRECT: Structured name with required sub-elements -->
<PayeeName>
  <FirstName>Jane</FirstName>
  <LastName>Doe</LastName>
</PayeeName>

<!-- WRONG: Unescaped special characters -->
<BusinessName>Smith & Jones LLC</BusinessName>
<!-- (the & above IS correct XML entity encoding) -->

<!-- WRONG: Literal ampersand -->
<BusinessName>Smith & Jones LLC</BusinessName>
<!-- This will cause an XML parse error -->

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:

• Test TCC: You can apply for a test-only TCC or use your production TCC in test mode. Check our IRIS testing and sandbox guide for details on the application process.
• Test endpoint: The sandbox uses a different base URL than production. All submissions to the test endpoint are discarded and never sent to IRS master files.
• Test TINs: Use IRS-designated test TINs (typically starting with 00 or 99) to avoid accidental production filing.
• Availability: The sandbox may have limited availability windows. The IRS typically publishes an availability schedule. Plan your testing around these windows.
• Response format: The sandbox returns the same XML response structure as production, including acknowledgment IDs, error details, and status codes.

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 referencing an original SubmissionId
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	OAuth 2.0 with client credentials	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)	Not required for portal-only users
Automation	Fully automated, no human interaction	Manual process, requires browser session
XML knowledge	Required — you build and submit XML directly	Not required — the portal generates XML behind the scenes
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 OAuth 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#

// Using XmlSerializer with classes generated from IRS XSD
// 1. Download IRS XSD files
// 2. Generate classes: xsd.exe IRISSchema.xsd /classes /namespace:IRS.IRIS
// 3. Populate and serialize

var submission = new IRISSubmission
{
    Manifest = new Manifest
    {
        SubmissionId = Guid.NewGuid().ToString(),
        TaxYear = "2025",
        Transmitter = new Transmitter { TIN = "123456789", TCC = "ABCDE" }
    },
    FormData = new FormData
    {
        Form1099NEC = new Form1099NEC
        {
            Payer = new Payer { PayerTIN = "987654321", ... },
            Payees = new List<Payee> { ... }
        }
    }
};

var serializer = new XmlSerializer(typeof(IRISSubmission));
using var writer = new StringWriter();
serializer.Serialize(writer, submission);
string xml = writer.ToString();

Python

import xml.etree.ElementTree as ET
from lxml import etree  # For XSD validation

# Build XML tree
root = ET.Element("IRISSubmission",
    xmlns="urn:us:gov:treasury:irs:iris")

manifest = ET.SubElement(root, "Manifest")
ET.SubElement(manifest, "SubmissionId").text = "unique-uuid"
ET.SubElement(manifest, "TaxYear").text = "2025"

transmitter = ET.SubElement(manifest, "Transmitter")
ET.SubElement(transmitter, "TIN").text = "123456789"
ET.SubElement(transmitter, "TCC").text = "ABCDE"

form_data = ET.SubElement(root, "FormData")
form_1099_nec = ET.SubElement(form_data, "Form1099NEC")
# ... build payer and payee elements

# Validate against XSD before submitting
schema = etree.XMLSchema(etree.parse("IRISSchema.xsd"))
doc = etree.fromstring(ET.tostring(root))
is_valid = schema.validate(doc)
if not is_valid:
    print(schema.error_log)

Java

// Using JAXB with classes generated from IRS XSD
// xjc -d src -p gov.irs.iris IRISSchema.xsd

JAXBContext context = JAXBContext.newInstance(IRISSubmission.class);
Marshaller marshaller = context.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);

IRISSubmission submission = new IRISSubmission();
submission.getManifest().setSubmissionId(UUID.randomUUID().toString());
submission.getManifest().setTaxYear("2025");
// ... populate payer and payee data

StringWriter writer = new StringWriter();
marshaller.marshal(submission, writer);
String xml = writer.toString();

// Validate against XSD
SchemaFactory factory = SchemaFactory.newInstance(
    XMLConstants.W3C_XML_SCHEMA_NS_URI);
Schema schema = factory.newSchema(new File("IRISSchema.xsd"));
Validator validator = schema.newValidator();
validator.validate(new StreamSource(new StringReader(xml)));

Regardless of language, the workflow is the same: generate a class model from the IRS XSD, populate it with your data, serialize to XML, validate against the schema, then submit via the A2A REST API.

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 same API — BoomTax generates the correction XML with the proper OriginalSubmissionId reference.
• 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 without any conversion — we parse the FIRE format and handle everything downstream.

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