Free IRIS developer guide
IRIS A2A, explained for developers
Application-to-Application (A2A) filing replaces FIRE's fixed-width files with XML sent over a REST API. Here's the whole path from TCC to acknowledgment, plus a UTID generator and an XML text cleaner.
The tools run entirely in your browser. Nothing you enter is sent to us or stored.
Short answer
IRIS Application-to-Application (A2A) is the IRS's XML-over-REST channel for software that e-files information returns, replacing FIRE's fixed-width files. You need an IRIS A2A TCC, an API Client ID (registered with a JWK of your public keys) and the yearly schema package; tax year 2025 uses schema version 2.0. Each transmission is UTF-8 XML without a byte order mark, up to 100 MB, identified by a UTID in the form UUID:IRIS:TCC::A. You authenticate with signed JWTs, pass ATS testing, then call the IRIS Help Desk (866-937-4130) to move your TCC to production.
- Transmission types: O original, C correction, R replacement
- ATS: no live TINs; TestCd T
- Person names allow only letters, digits and hyphens
- Keep the Receipt ID for status and corrections
Last reviewed against IRS Publication 5718 and Publication 5719.
UTID generator and checker
XML text cleaner Fix characters IRIS rejects before they go into a data field.
From zero to your first A2A transmission
- Get an IRIS A2A TCC. Apply through the IRIS Application for TCC with the A2A transmission method. Issuer and Transmitter TCCs start in Test (T) status; Software Developer TCCs stay in Test permanently. IRS page: IRIS Application for TCC
- Get an API Client ID. After the TCC, complete the API Client ID Application (irs.gov/iris → Get an API Client ID). You upload a JWK file with your public keys; the API Client ID authenticates your software. IRS page: Get an API Client ID
- Download the schema package and business rules. Request the yearly IRIS XML schemas and business rules from the IRIS schema page. Tax year 2025 is schema version 2.0, and VersionNum and VersionDt are now manifest elements. IRS page: IRIS schemas and business rules
- Build and validate your XML. Generate the transmission (manifest, submissions, forms), encode it as UTF-8 without a BOM, and check it with a validating parser before sending.
- Authenticate. Sign two JSON Web Tokens (a Client JWT and a User JWT) with your private keys and exchange them for an access token (OAuth JWT bearer grant).
- Test in ATS. Send test transmissions (TestCd "T", no live taxpayer data) to the ATS endpoints. Software developers send five submissions of two records each; transmitters send a communication test of one submission with two records. IRS page: IRIS Assurance Testing System
- Move to production. Once ATS returns Accepted, call the IRIS Help Desk (866-937-4130) with your Receipt ID to move your TCC to Production (P).
- Transmit and fetch acknowledgments. POST each transmission to the intake endpoint, keep the Receipt ID it returns, then request the status and acknowledgment until processing finishes.
How an IRIS XML file is built
Each payload has three levels (Pub 5718, section 3.2.2):
- Transmission (manifest): who's sending and with what software: UTID, TransmissionTypeCd (O original, C correction, R replacement), TestCd (T or P), tax year, TCC, Software ID, and the schema VersionNum and VersionDt. Don't mix O, C and R in one transmission.
- Submission (for example IRSubmission1Grp, used for all 1099 forms): one form type, one tax year and one issuer per submission, with transmittal (1096-style) totals. The record count in the header must match the records actually sent.
- Form detail (for example Form1099NECDetail): one recipient's return. Each record carries a RecordId, which IRIS later combines into the UniqueRecordId used for corrections.
Tag names are upper camel case, 30 characters or fewer. The schema package contains sample transmissions; build from those rather than from memory.
Identifiers you'll track
| Identifier | Who sets it | Format / use |
|---|---|---|
| UTID | You | UUID:IRIS:TCC::A |
| SubmissionId / RecordId | You | Unique within the transmission and the submission |
| Receipt ID | IRIS, on intake | Key for status requests. Keep it; you can recover it by UTID. |
| UniqueSubmissionId | Derived | ReceiptId|SubmissionId |
| UniqueRecordId | Derived | ReceiptId|SubmissionId|RecordId |
Build those last two with the IRIS corrections tool.
Characters to watch
- Encode as UTF-8 without a byte order mark; UTF-16 and UTF-32 aren't supported.
- A double dash (--) anywhere rejects the transmission.
- & ' < " must be escaped (& ' < "); > may be escaped.
- Person names allow only letters, digits and hyphens: O'Malley becomes OMalley.
Endpoints
| Operation | Environment | URL |
|---|---|---|
| Submit transmission (POST, multipart/form-data, file part "file", text/xml, max 100 MB) | Production | https://api.www4.irs.gov/IRIntakeAcceptanceA2A/1.0/irisa2a/v1/intake-acceptance |
| ATS (test) | https://api.alt.www4.irs.gov/IRIntakeAcceptanceA2A/1.0/irisa2a/v1/intake-acceptance | |
| Status / acknowledgment (POST, application/xml) | Production | https://api.www4.irs.gov/IRIntakeAcceptanceA2A/1.0/iris/transstatusorack |
| ATS (test) | https://api.alt.www4.irs.gov/IRIntakeAcceptanceA2A/1.0/iris/transstatusorack |
Both take an Authorization: Bearer access token. Copied from Publication 5718 (Rev. TY2025); check the current publication before you code against them.
What happens after you send
- IRIS checks the UTID is new for your TCC, stores the file and returns a Receipt ID, the UTID and a timestamp straight away.
- It then validates the schema, your TCC and Software ID, the transmission type and tax year, and each form's business rules.
- Request status by Receipt ID (or UTID): Processing, Accepted, Accepted with Errors, Partially Accepted, Rejected or Not Found. Errors come back in the acknowledgment with XPath locations.
- Fix accepted-with-error records with a correction (C) and rejected ones with a replacement (R). In ATS only, just resend as an original until you get Accepted.
ATS testing in brief
- ATS is open year round, checks schema and business rules, and doesn't process anything downstream.
- No live data: live issuer or recipient TINs are rejected.
- Test transmissions need TestCd "T", the EIN and name from your TCC application, a TCC matching the UTID, and a verifiable Software ID.
- Software developers: one transmission with five submissions of two records each (10 records), all Accepted.
- Transmitters: a communication test of one transmission, one submission, two records, Accepted. Then call the Help Desk with the Receipt ID to move to Production. A software developer who is also a transmitter doesn't need a separate communication test.
Related tools
- Step 1: the IRIS TCC application; step 2: the API Client ID guide.
- Passing the tests: IRIS ATS testing.
- Reading acknowledgments: IRIS error codes.
Sources
Questions
IRIS A2A questions
What is a UTID in IRIS?
The Unique Transmission Identifier you assign to every A2A transmission. It has five colon-separated parts: a UUID, the word IRIS, your TCC, an empty reserved field and the request type A, for example da20a4de-1357-11ed-861d-0242ac120002:IRIS:00000::A. IRIS rejects any UTID it has already received.
How large can an IRIS A2A transmission be?
Up to 100 MB. A transmission holds one or more submissions; each submission has a single form type and tax year and as many records as the size limit allows.
What do I need before I can send A2A transmissions?
An IRIS TCC for the A2A method, an API Client ID, software built to the current IRIS schemas, and a passed ATS test (a communication test for transmitters, or the software test for developers).
Can I put O'Malley in an IRIS person name field?
No. Person name elements only allow letters, digits and hyphens, so the apostrophe must be removed (OMalley). Business names allow more characters, but &, apostrophes, < and quotation marks must be escaped, and a double dash is never allowed.
Can I use live data in IRIS ATS?
No. ATS doesn't accept live taxpayer data for issuers or recipients and isn't a secure environment; test TINs that look real are rejected.
Do I need to build A2A software to e-file 1099s?
No. A2A is for high-volume filers and software providers. You can use the IRIS Taxpayer Portal, or file through an authorized e-file provider and skip the TCC, API credentials and testing entirely.
Skip the integration project
EFileForMe is an authorized e-file provider. Import your data or key it in, and we file with the IRS. No TCC of your own, no API keys, no ATS testing.