An IRIS transmission is XML nested three levels deep — a Transmission wraps one or more Submission blocks, and each submission carries the individual form records. Before it is accepted, that document has to clear two independent checks: the XML schema, which asks whether the file is well-formed and every value matches its declared type, and the IRS business rules, which ask whether the values make sense together. Clear both and IRIS returns a Receipt ID in seconds; miss either and you get a rejection that points at exactly one of those two layers. This guide walks the structure, the core elements, and the failures that trip filers on their first send.
In this story
What IRIS XML Actually Is
Where FIRE accepted a position-based text file built to the Publication 1220 record layout, IRIS accepts self-describing XML, which means every value lives inside a named element and carries its own meaning rather than depending on a column number for context.
That single change is the reason IRIS can validate a return the moment it arrives. A flat file is just a run of bytes until something reads the layout and decides what each position means, but an XML document describes its own structure, so the IRS can check it against a published schema instantly. The format you see depends on how you file. If you transmit through the A2A application-to-application API, you build and send this XML directly, which is why developers need to understand it in detail. If you use the Taxpayer Portal or a CSV upload instead, the IRS assembles the same XML for you behind the scenes from the data you enter. Either way, XML is the canonical format underneath every IRIS submission.
The schema, the element definitions, and the required test scenarios are spread across three IRS publications. Publication 5717 documents the Taxpayer Portal, Publication 5718 documents the A2A interface that ships the schema package, and Publication 5719 defines the Assurance Testing scenarios you must pass before production. The element names used throughout this guide follow the IRS schema conventions; when anything here and the published schema disagree, the schema is authoritative.
The Document Hierarchy
Every IRIS transmission nests the same three levels, and understanding that nesting is the fastest way to read any sample file. At the top is the Transmission, the envelope for a single send that carries the manifest and your Transmitter Control Code. Inside it sit one or more Submission blocks, one per payer — the entity that actually made the payments. Each submission then holds the form records, one per payee, with that payee’s name, TIN, amounts, and any state data attached.
Transmission <!-- one per send; carries the manifest + your TCC -->
└─ Submission <!-- one per payer (the entity that paid) -->
├─ Payer <!-- name, EIN, address -->
└─ Form1099NEC (1..n) <!-- one per payee record -->
├─ Payee <!-- name, TIN, address -->
└─ amounts + state dataThe transmission level is also where the manifest values live, including your TCC and the test-or-production indicator that tells IRIS whether this is a live filing. Those manifest fields are checked first, and they matter more than anything inside them: if the manifest is wrong, nothing nested below it is even read, and the whole transmission is rejected before a single form record is evaluated.
From Flat File to XML: The Name Split
The clearest way to feel what changed is to put a FIRE record beside its IRIS equivalent. In the old Publication 1220 layout, a payee’s name was one fixed-width blob sitting at a known character position, and the system inferred where the first name ended and the last name began. In IRIS that single blob splits into discrete, typed elements — PersonFirstNm and PersonLastNm — each carrying its meaning explicitly. That split is exactly the transformation a converter has to perform on every individual record, and it is the most common place a hand-rolled migration goes wrong.
<!-- FIRE: one fixed-width name field at a known position -->
A2026123456789MARIA RODRIGUEZ
<!-- IRIS: the same name split into typed, named elements -->
<Form1099NEC>
<PayeeNm>
<PersonFirstNm>MARIA</PersonFirstNm>
<PersonLastNm>RODRIGUEZ</PersonLastNm>
</PayeeNm>
<NonemployeeCompensationAmt>1500.00</NonemployeeCompensationAmt>
</Form1099NEC>Core Elements & Data Types
A small set of element groups carries most of the payload on every form, so it pays to learn these first. They are the ones you will touch on nearly every record, and the names below follow IRS schema conventions; treat the published schema as the final word on exact spelling and order.
| Element (representative) | Type / format | What it carries and why it matters |
|---|---|---|
PayerNm / PayeeNm | Person or business name group | Person names split into PersonFirstNm and PersonLastNm; a business instead uses a business-name line. This grouping is what replaces FIRE’s single fixed-width name field. |
TINTypeCd + TIN | 9 digits, no hyphens | The type code distinguishes an EIN from an SSN or ITIN, and the TIN itself is nine bare digits. A formatting slip here fails at the schema layer before any business rule even runs. |
USAddressGrp | Structured address group | Street, city, StateAbbreviationCd, and ZIP each live in their own element rather than in one free-text line, so the parts can be validated individually. |
NonemployeeCompensationAmt | Numeric amount | Each reportable box maps to one named amount element, and the schema defines the numeric type and precision the value must match. |
StateAbbreviationCd / StateTaxWithheldAmt | USPS code + numeric | These are the combined federal/state fields, and they are the most common source of validation failures — the detail the section below is about. |
Two Layers of Validation: Schema vs Business Rules
IRIS checks your XML twice, and the two checks fail for completely different reasons, so knowing which layer rejected you is half the work of fixing it. The first layer is structural and the second is logical, and a code that looks alarming at one layer is meaningless at the other.
Layer 1 — Schema (structure and types)
The schema layer asks the mechanical questions: is the document well-formed, are all the required elements present and in the order the schema expects, and does every value match its declared type? A missing closing tag, a TIN that still has hyphens in it, or a stray letter inside an amount field all fail here — and they fail before the IRS ever considers what the numbers actually mean. Because these checks are purely structural, you can run them yourself against the published XSD on your own machine, which is the cheapest rejection you will ever prevent.
Layer 2 — Business rules
Once the shape is valid, the IRS applies its catalog of business rules, which are cross-field checks with stable rule identifiers. These test the things a schema cannot see: that a combined federal/state block is internally consistent, that totals reconcile, and that a payee’s name-and-TIN pairing is plausible. Only when a return clears both the schema layer and the business-rule layer does IRIS return a Receipt ID confirming the submission was accepted for processing.
Stressed about hand-building this XML?
e1099f maps your existing FIRE-format files straight to validated IRIS XML — every element, every state field, generated and pre-checked against both layers for you.
State Withholding Elements: Where Most Submissions Break
In FIRE, combined federal/state data lived in character positions inside the B record, which made it easy to get silently wrong and only discover the mistake months later in a state notice. IRIS replaces that with a structured group built from a StateAbbreviationCd, the state withholding amount, and the payer’s state account elements, all of which are validated together as a set. Because the parts are typed and cross-checked at submission, a malformed state code can no longer slip through unnoticed — the trade-off is that an inconsistent state block is also the failure filers hit most often, which is why it leads the rejection list below.
Common Schema & Rule Errors (and How to Avoid Them)
Three failures account for the bulk of first-time rejections, and each maps cleanly to one of the two validation layers, so the layer tag on each card tells you where to look before you read another word.
Cause: a StateAbbreviationCd that isn’t a valid USPS code, or state withholding reported without the matching state block, so the combined federal/state group fails the cross-field check that reads it as a set. Fix: use only valid two-letter state codes and always emit the full CF/SF group together, because the rule validates the whole block at once rather than field by field.
Cause: a required child element — a TIN, a name element, or another mandatory node — is absent or empty, so the document fails the structural check before its values are ever evaluated. Fix: validate against the published XSD locally before you send; the schema names the exact element that is missing and the parent it belongs under, which usually points you straight at the fix.
Cause: a TIN that still contains hyphens, or an amount carrying a currency symbol, comma, or letter, none of which match the type the schema declares for that element. Fix: strip the formatting before you build the XML — TINs are nine bare digits and amounts are plain numbers typed exactly as the schema specifies.
Validate Before You File
Almost every rejection above is preventable with two inexpensive habits that you run before a single byte reaches the IRS. The first is local schema validation, and the second is the IRS’s own test environment, and together they cover both validation layers.
- Validate against the XSD locally. Running your XML through the published schema on your own machine catches every schema-layer error instantly and at no cost, so structural mistakes never become a wasted round-trip to the IRS.
- Run the ATS scenarios. A2A transmitters must pass the IRS Assurance Testing System defined in Publication 5719 before they are cleared for production, and those scenarios exercise the business-rule layer with both known-good and known-bad cases so you see how real rejections behave first.
Never Hand-Write IRIS XML
You can build, validate, and test all of this yourself, and now you have the map to do it. The other option is to skip the schema work entirely and let a service generate schema-valid, rule-checked IRIS XML from the files you already produce.
FIRE files in, XML out
Upload the Publication 1220 flat files you already produce, and every field is mapped to the right IRIS element — including the first-name and last-name split.
Both layers pre-checked
The schema layer and the business-rule layer are validated before submission, so what comes back is a Receipt ID rather than a rejection to decode.
CF/SF handled
State elements are emitted and cross-checked automatically, with none of the character-position guesswork that made the old B record so easy to break.
Valid IRIS XML for every form type — without ever opening a schema file.
Frequently Asked Questions
Do I have to send XML if I use the Portal?
Where is the official IRIS schema?
What is the difference between a schema error and a business-rule error?
How are payee names handled?
PersonFirstNm and PersonLastNm, while businesses use a business-name element. This split is the most common transformation when converting from FIRE’s single fixed-width name field.How should TINs and amounts be formatted?
Can I validate my XML before submitting?
Why does my state data keep getting rejected?
What does a Receipt ID mean?
What happens if the transmission manifest is wrong?
Does e1099f require me to understand any of this?
Not tax advice. This is general information about IRS procedures. Element names and formats here follow IRS schema conventions and may change as the IRS updates IRIS; the published schema and Publications 5717–5719 are authoritative. Verify current requirements before building against them, and consult a tax professional for your situation.