The IRIS A2A (Application-to-Application) API is an asynchronous, two-call conversation. Your software first submits a transmission of IRIS XML and immediately receives a Receipt ID, which confirms the IRS has your file but says nothing about whether your returns passed. The verdict comes later, when your software polls a status endpoint and retrieves an acknowledgment reporting Accepted, Accepted with Errors, or Rejected. None of it works until you hold an A2A TCC, you have passed Assurance Testing, and your application can present valid IRS credentials. This guide walks the full round trip and every response you have to handle — and if your deadline won’t wait for a build cycle, a provider that already holds an A2A connection can transmit today.
In this story
What the IRIS A2A API Actually Is
A2A is the IRS’s machine-to-machine filing channel for IRIS — your software talks directly to IRS web services, with no person logging into a portal and no file uploaded by hand.
It exists for one reason, which is volume and automation. The IRIS Taxpayer Portal and its CSV upload are built for a person filing interactively, one screen at a time, whereas A2A is built for a system filing programmatically, on a schedule, against thousands or millions of records at once. Both channels file the same returns into the same IRIS system, so the difference is not the destination but who does the driving. With A2A your code constructs the IRIS XML, transmits it over an authenticated connection, and reads back the result without anyone watching the screen — and that is precisely what makes year-end batch filing, automated retries, and end-of-day reconciliation possible at scale.
The trade-off is that A2A is not a casual integration you can wire up in an afternoon. The IRS gates the channel behind a Transmitter Control Code and a mandatory testing phase, and the interface itself is asynchronous, which means you never receive your acceptance in the same call you used to submit. Understanding that round trip — and building your software to expect a delayed answer rather than an immediate one — is most of the work.
The A2A interface, its message structure, and the credential model are defined in Publication 5718 (IRIS A2A), while the Portal channel is documented in Publication 5717 and the required test scenarios live in the IRIS Assurance Testing package described in Publication 5719. You apply for the A2A role and its credentials through the IR Application for TCC inside IRS e-Services. Treat the published Pubs as the source of truth: the specifics below follow current IRS conventions and may change between schema versions, which is why this guide is verified against a stated schema release rather than written once and left alone.
What You Need Before You Write a Line of Code
A2A access is not self-serve, and three things have to be in place before your first real transmission. Each carries its own lead time, so the order in which you start them matters as much as the work itself.
An A2A Transmitter Control Code
You apply for a Transmitter Control Code through the IR Application for TCC in e-Services and choose the A2A transmission method specifically, rather than the Portal/Taxpayer method that the same application also offers. A legacy FIRE TCC does not carry over to IRIS, and the application is subject to the IRS suitability review, so you should budget roughly 45 business days before approval and start well ahead of any filing deadline. The full process is covered in our complete IRIS TCC application guide.
Software credentials your application can present
A2A authenticates your software, not a person clicking a screen, which is a fundamental shift from the portal model. Your application is issued the IRS credentials it presents on every call, and protecting, storing, and rotating those credentials is your responsibility — a leaked or expired secret is the difference between a working integration and a silent outage at the worst possible time.
A passing Assurance Testing run
Every A2A transmitter must clear the IRS Assurance Testing System against the published test scenarios before it is allowed to move to production. You cannot file live returns until ATS is passed, full stop, so this is not a step you can defer until after launch. We walk through the whole sandbox cycle in our IRIS ATS sandbox testing guide. Only once those three pieces are in place does the API conversation below begin.
Authentication: How Your Software Proves Who It Is
Before you can transmit anything, your software has to obtain an access token, and the way it does so is the part of A2A most teams underestimate. Per Pub 5718, IRIS uses an OAuth 2.0 flow with JWT-bearer and private-key-JWT client authentication, which means there is no username and password sitting in a config file. Instead your application signs short-lived JSON Web Tokens with a private key, presents them to the IRS token endpoint, and receives a bearer access token in return that it then attaches to its transmit and status calls.
Two timing details govern the whole flow. The signed JWT itself is only valid for a short window — on the order of fifteen minutes — and every signing must carry a unique jti claim so the IRS can reject replays, so you cannot sign one token at startup and reuse it all day. The access token you receive in exchange has its own, separate lifetime set by the IRS, and the right pattern is to cache that access token and reuse it across calls until it nears expiry, then sign a fresh JWT and exchange it for a new one. Refreshing a little before the token actually expires — rather than waiting for a call to fail — avoids a race where a long-running batch loses its credential mid-transmission.
The client-authentication mechanics — the JWT-bearer exchange, the private-key signing, the token lifetimes, and the unique-jti requirement — are specified in Publication 5718. The exact endpoints, claim set, and key-registration steps are detailed there and in the IRS e-Services API documentation; treat those as authoritative and verify them against the current release before you build, because credential mechanics are exactly the kind of detail the IRS revises between schema versions.
The Round Trip: Submit, Then Poll
The single most important thing to internalize about A2A is that it is asynchronous. You do not submit a transmission and receive “Accepted” in the response, no matter how clean your data is. What you receive is a Receipt ID, a token that means “we have your file,” and the actual verdict arrives later, on a separate call you make specifically to ask for it. Conceptually there are two services in the loop, and your integration has to treat them as two distinct moments rather than one request-and-reply.
The transmit call
Your software sends the IRIS XML — a transmission that wraps one or more submission blocks — to the IRS transmit endpoint, authenticated with the bearer token from the step above and carrying your TCC inside the manifest. If the message is structurally accepted for processing, the IRS responds synchronously with a Receipt ID. That Receipt ID is not acceptance of your returns; it is your claim check for retrieving the result later, so your software has to persist it the moment it comes back — it is the only handle you have on a transmission whose verdict has not yet been issued.
The status (acknowledgment) call
IRIS then processes the transmission in the background while your code waits. Your software polls a status endpoint using the Receipt ID until an acknowledgment is ready, and the acknowledgment is the real answer: it reports whether each submission was Accepted, Accepted with Errors, or Rejected, and when something failed it tells you which records broke and which business rules they broke. The verdict does not come to you — you have to go back and ask for it.
What a Transmission Looks Like
Every transmit call carries a manifest, which is the envelope that identifies who is filing and in what mode, wrapped around the form data itself. The manifest matters enormously because if you get it wrong nothing inside it is even read — the IRS rejects the whole transmission at the envelope and never reaches your payee records. The illustrative skeleton below shows the levels A2A cares about; the real element names and namespaces are defined in the IRIS schema distributed with Pub 5718, so treat the tags here as placeholders for the actual schema elements rather than literal names to code against.
Transmission <!-- the A2A envelope for one send -->
├─ IRTransmissionManifest <!-- identifies the transmitter + run -->
│ ├─ TransmitterControlCd <!-- your A2A Transmitter Control Code -->
│ └─ TestFileCd <!-- T = ATS test, P = production -->
└─ Submission (1..n) <!-- one per payer -->
├─ Payer <!-- name, EIN, address -->
└─ Form records (1..n) <!-- the payee returns -->The two fields that matter most at the envelope level are your TransmitterControlCd and the TestFileCd flag. The TestFileCd is the switch between worlds: a value of T routes the transmission into Assurance Testing, while P routes it to production, where it counts as a real filing. Leaving that flag on T after you go live means your “filings” never actually reach the IRS as returns, and flipping it to P before ATS is passed will simply be rejected. The XML below the manifest is the same self-describing format used everywhere in IRIS, so if you are building it from legacy files our IRIS XML format and schema guide covers the structure element by element.
Reading the Acknowledgment: Three Outcomes
When you poll the status endpoint and an acknowledgment is finally ready, every submission resolves to one of three states, and your integration has to branch on all three. The trap here is subtle but expensive: treating “not Rejected” as success is exactly how silent failures slip through, because a transmission can be accepted while individual records inside it quietly were not filed.
| Acknowledgment status | What it means | What your code must do |
|---|---|---|
| Accepted | Every record in the submission cleared both schema and business-rule validation. | Record the acceptance and the IRS identifiers; that submission is done. |
| Accepted with Errors | The submission was accepted, but specific records failed validation and were not filed. | Parse the per-record errors, fix those records, and file them as a new transmission — do not resend the whole batch blind. |
| Rejected | The whole submission, often the manifest itself, failed; nothing was filed. | Read the rejection reason, correct it — frequently a manifest, TCC, or TestFileCd problem — and resubmit the entire transmission. |
The hardest of the three to handle well is Accepted with Errors, precisely because part of your batch filed and part did not, which means you cannot reconcile at the transmission level — you have to reconcile at the record level. The acknowledgment identifies the failing records and the business rules they broke, and our guide to IRIS error codes and their fixes maps the common ones to their causes and remedies so you are not decoding them from scratch.
Polling Without Hammering the IRS
Because the result is not instant, your client has to wait — but it has to wait politely. The acknowledgment may not be ready the moment you ask for it, and a naive tight loop that re-requests every second both wastes your own resources and risks tripping IRS throttling. Two habits keep polling healthy, and both come down to patience and bookkeeping.
The first habit is to back off between checks. Wait a sensible interval before you poll again, and lengthen the gap if the acknowledgment still isn’t ready, rather than re-asking on a hair trigger; a poll cadence on the order of minutes rather than seconds is a reasonable default for batch filing, since IRIS processes the transmission in the background and the answer is not improved by asking more often. The second habit is to persist the Receipt ID and the transmission state. Store every Receipt ID against its transmission so that a crash, a restart, or a long delay never loses track of an outstanding acknowledgment, because the Receipt ID is the only way back to a result you have not yet retrieved.
For very large filings — hundreds of thousands of records spread across many submissions — the same submit-and-poll pattern still applies, but batching and throughput planning start to matter in their own right. Our high-volume bulk filing guide covers how to size batches and manage acknowledgments when the record counts get large.
Don’t want to build and maintain an A2A client?
e1099f provides a managed IRIS A2A connection — authentication, transmission, and acknowledgment polling all handled — without you standing up the integration yourself.
Common Rejection Reasons (and How to Avoid Them)
Most first-time A2A failures happen at the envelope, before the IRS ever looks at a single payee record. These are the recurring causes, and each one is cheap to prevent in advance but painfully expensive to debug after a deadline has already passed.
Cause: Transmitting with TestFileCd set to T after go-live, so nothing files for real, or set to P before ATS is passed, so the transmission is rejected outright. Fix: Make the test/production flag an explicit, environment-driven setting rather than a hardcoded default, and flip it to P only after your ATS run has been approved.
Cause: Expired, mistyped, or environment-mismatched software credentials, or calling production before the A2A role on your TCC is actually active. Fix: Confirm the credentials match the environment you are hitting, verify the A2A role on your TCC is approved, and rotate secrets on a schedule rather than letting a key silently expire underneath a running batch.
Cause: The TransmitterControlCd in the manifest does not match the authorized transmitter, or the manifest is missing a required field. Fix: Populate the manifest from your approved IR Application values; the rejection names the field that failed, and the published schema and Pub 5718 are authoritative on what each one must contain.
Cause: Branching only on Rejected, so partially-failed batches look filed when some of their records never were. Fix: Always parse the per-record results, re-file only the records that failed, and reconcile your counts — accepted, errored, and rejected — against exactly what you submitted.
Skip the A2A Build Entirely
You can stand up the full A2A client yourself — the TCC application, the ATS run, the OAuth credential handling, the submit-and-poll loop, and the three-way acknowledgment branching — and plenty of teams do. Or you can file through software that already holds the connection and has already cleared testing. Here is what choosing the second path removes from your plate.
Connection already live
An A2A TCC and a passed ATS run already in place — no 45-day wait and no sandbox cycle standing between you and your first filing.
Submit & poll handled
Token signing, transmission, Receipt ID tracking, and acknowledgment polling all run for you — no asynchronous loop to build or babysit.
Every outcome reconciled
Accepted, Accepted-with-Errors, and Rejected are each handled down to the record level, so nothing files silently and nothing fails silently.
The full A2A round trip — without writing or maintaining a single API call.
Frequently Asked Questions
What’s the difference between A2A and the IRIS Portal?
Do I need a special TCC for A2A?
How does A2A authentication work?
Why don’t I get “Accepted” right away when I submit?
What is the Receipt ID for?
What does “Accepted with Errors” mean?
Do I have to test before filing live through A2A?
What does the <code>TestFileCd</code> flag do?
T sends it to the test environment (ATS), and P sends it to production as a real filing. Mismanaging this flag is the single most common A2A integration mistake.How often should I poll for the acknowledgment?
Where is the official A2A specification?
Does e1099f require me to build any of this?
Not tax advice. This is general information about IRS procedures and the IRIS A2A interface; endpoints, element names, and credential mechanics follow IRS conventions and may change as the IRS updates IRIS. Publications 5717–5719 and the published schema are authoritative — verify current requirements, and consult a tax professional for your situation, before building against them.