IRS IRIS API Integration Guide: A2A Filing Setup

What Is the IRIS A2A Channel?

IRIS offers three filing channels: the Taxpayer Portal (manual web entry), CSV Upload (template-based spreadsheet import), and A2A (Application-to-Application). The A2A channel is designed for software vendors, service bureaus, and large organizations that need to file programmatically — submitting thousands or millions of information returns through automated systems without manual intervention.

A2A replaces the file-upload mechanism that FIRE used. Under FIRE, you generated a Publication 1220-format text file and uploaded it through the FIRE web portal (or used a basic HTTP POST mechanism). A2A is a fundamentally different architecture: it is a SOAP-based web service that accepts XML documents, validates them in near-real-time, and returns structured responses indicating success or failure.

For a broader comparison of how IRIS works versus the legacy system, see our IRIS vs FIRE comparison.

SOAP Protocol Fundamentals

IRIS A2A uses the SOAP (Simple Object Access Protocol) standard, version 1.2, over HTTPS. If your organization has built SOAP integrations before (common in enterprise environments, healthcare, and government systems), the IRIS A2A protocol will feel familiar. If your experience is primarily with REST APIs, there is a learning curve.

Key SOAP concepts for IRIS A2A:

• WSDL (Web Services Description Language): The IRS publishes a WSDL file that formally describes the A2A service — available operations, expected request/response formats, and endpoint URLs. Your SOAP client library generates client stubs from this WSDL.
• Envelope structure: Every SOAP message is wrapped in an XML envelope containing a header (authentication tokens, routing info) and a body (the actual submission data or response).
• SOAP faults: Errors are returned as structured SOAP fault elements rather than HTTP error codes. This means a 200 HTTP response can still contain an error — you must parse the SOAP body to determine success or failure. See our IRIS error codes guide for details on interpreting these faults.

Authentication

IRIS A2A authentication involves multiple layers:

1. IRIS TCC and e-Services Credentials

You must have an approved IRIS Transmitter Control Code (TCC). This is separate from any FIRE TCC you may have held — see our TCC differences guide for details. Your TCC is linked to your IRS e-Services account, which requires ID.me identity verification.

2. Token-Based Session Management

A2A uses a token-based authentication flow:

1. Your application calls an authentication endpoint with your credentials.
2. The IRS returns a session token with a defined expiration window.
3. Include this token in the SOAP header of all subsequent requests.
4. When the token expires, re-authenticate to obtain a new one.

Implement proper token lifecycle management in your code. Do not authenticate on every request — this will trigger rate limiting. Cache the token and only refresh it when it expires or when you receive an authentication error.

3. TLS Requirements

All A2A communication must use TLS 1.2 or higher. The IRS may require specific cipher suites. Ensure your HTTP client library and runtime environment support current TLS standards. Older systems running outdated TLS stacks will fail to connect.

XML Schema Structure

IRIS submissions use XML formatted according to IRS-published XSD (XML Schema Definition) files. The IRS references these schemas in Publication 5717 and related technical documentation. Key aspects of the schema:

• Form-type-specific schemas: Each 1099 form type has its own schema definition with form-specific fields. 1099-NEC, 1099-MISC, 1099-INT, and other variants each have different required and optional elements.
• Envelope schema: A transmission envelope wraps the form data, containing transmitter identification, submission type (original, correction, void), and metadata.
• Strict validation: Unlike FIRE’s relatively lenient parsing of fixed-width text, IRIS XML must be schema-valid. Any structural deviation — missing elements, wrong order, invalid data types — triggers an immediate rejection.

For a deep dive into the XML format requirements, see our IRIS XML format guide.

Core API Operations

Submit

The submission operation sends your XML payload to the IRS. A successful submission returns a receipt ID (unique identifier for tracking) and an initial status. Note that a successful submission does not mean your returns are accepted — it means the IRS has received and queued them for processing. Business-rule validation (TIN checks, amount verification, duplicate detection) happens asynchronously.

Status Check

After submission, poll the status endpoint using your receipt ID to track processing progress. Status values include received, processing, accepted, accepted with errors (partial acceptance), and rejected. Implement a polling strategy with exponential backoff — do not hammer the status endpoint every second.

Retrieve Acknowledgments

Once processing is complete, retrieve the acknowledgment document. This XML response contains form-by-form results: which returns were accepted, which were rejected, and specific error codes for each rejection. Parse this response programmatically to identify returns that need correction and resubmission.

Corrections and Voids

To file corrections or void previously accepted returns, submit a new XML document with the appropriate submission type flag. Corrections require referencing the original filing’s receipt or record ID. The correction workflow in IRIS is more structured than FIRE’s, requiring explicit original-to-correction linkage.

Rate Limits and Best Practices

• Batch sizing: The IRS recommends grouping returns into batches rather than submitting one-at-a-time. Each SOAP request can contain multiple payee records. Optimal batch size depends on your form types and volume; start with batches of 100–500 records and adjust based on performance.
• Rate limiting: The IRS enforces rate limits on all A2A operations. Exceeding the limit results in throttling responses (not hard blocks). Implement retry logic with backoff when you receive throttling indicators.
• Peak period awareness: Filing volume spikes around January 31 and March 31 deadlines. Submit early in the filing season to avoid peak congestion. The IRS A2A infrastructure handles concurrent load, but response times increase during peak periods.
• Idempotency: Design your system to handle retries safely. If a submission times out and you are unsure whether the IRS received it, use the status check endpoint before resubmitting to avoid creating duplicates.

Error Handling

Robust error handling is critical for any A2A integration. Errors fall into several categories:

• Transport errors: Network timeouts, TLS failures, connection refused. Retry with backoff.
• SOAP faults: Structural issues with your SOAP message. Fix your message construction.
• Schema validation errors: Your XML does not conform to the XSD. Fix your XML generation logic.
• Business rule errors: Data issues (invalid TIN, amount errors, duplicates). Fix the underlying data and resubmit.
• Authentication errors: Expired token, invalid credentials, unauthorized TCC. Re-authenticate or verify your TCC status.

For a comprehensive breakdown of each error type and resolution steps, see our IRIS error codes guide.

Comparison with FIRE’s Upload Process

Aspect	FIRE	IRIS A2A
Protocol	HTTP file upload (web form)	SOAP 1.2 over HTTPS
Data format	Fixed-width text (Pub 1220)	XML (IRS XSD schemas)
Validation	Batch, 24–48 hour delay	Near-real-time, multi-stage
Error detail	Terse numeric codes	Structured, field-level messages
Authentication	Username/password + TCC	Token-based with TLS + TCC
Corrections	Re-upload full corrected file	Structured correction with original reference
Testing	Simple test file upload	Full AATS certification required

BoomTax API: A Simpler Alternative

Building a direct IRIS A2A integration is a significant engineering investment. You need SOAP expertise, XML schema management, AATS certification, ongoing maintenance as the IRS updates its schemas, and dedicated error-handling logic. For many organizations, this level of complexity is not justified.

The BoomTax API offers a modern REST alternative. Instead of SOAP, you use standard REST calls with JSON payloads. Instead of managing IRS XML schemas, you submit structured data and BoomTax generates the XML. Instead of handling IRIS authentication and TCC management, you use a simple API key. BoomTax submits through IRIS on your behalf and returns standardized status and error responses.

If your goal is to automate information return filing without the overhead of a direct IRS integration, the BoomTax API is the faster path. If you have an existing FIRE automation pipeline, you can also upload your FIRE-format files through BoomTax and skip the API integration entirely.

Frequently Asked Questions

Next Steps

• IRIS testing sandbox (AATS) guide
• IRIS XML format guide
• IRIS error codes and troubleshooting
• How to get an IRIS TCC
• IRIS bulk filing for high-volume transmitters
• Skip SOAP — use the BoomTax REST API