IRS Publication 5717: IRIS API Guide Explained

What Is Publication 5717?

IRS Publication 5717 is the official technical reference document for the IRIS A2A (Application-to-Application) API. It is the IRIS equivalent of what Publication 1220 was for FIRE — the definitive specification that developers need to build software that communicates directly with the IRS filing system.

Pub 5717 is published by the IRS and updated periodically as IRIS evolves. It covers everything from the XML schema definitions for each supported form type to the SOAP web service endpoints, authentication flows, error code catalogs, and testing environment procedures. It is a dense, technical document aimed squarely at software developers and system integrators — not at end users or tax preparers.

Who Needs to Read Publication 5717?

The short answer: only developers building direct IRIS integrations. This includes:

• Tax software developers building IRIS filing capabilities into their products
• Enterprise IT teams developing custom A2A integrations for their organization's filing pipeline (see our enterprise IT migration guide)
• Service bureau engineers building IRIS transmission capabilities into filing platforms
• ERP integration developers connecting payroll, AP, or HR systems to IRIS

If you are a tax preparer, CPA, payroll provider, or small business owner, you do not need to read Pub 5717. You can use the IRIS Taxpayer Portal, the CSV upload feature, or a filing provider like BoomTax to file without ever touching the A2A API.

Key Sections of Publication 5717

Pub 5717 is organized into several major sections. Here is what each covers and why it matters:

Authentication and Authorization

Before your application can submit data to IRIS, it must authenticate. Pub 5717 defines the authentication flow, which involves:

• e-Services account credentials — The organization must have a registered IRS e-Services account
• IRIS TCC (Transmitter Control Code) — A separate authorization that confirms the organization is approved to transmit through A2A. Obtaining an IRIS TCC takes 45+ days through the IRS suitability review process.
• Token-based authentication — The API uses token-based auth for session management, with token refresh requirements documented in the spec

Understanding the auth flow is critical, as authentication failures are one of the most common issues in new IRIS integrations. The TCC differences between FIRE and IRIS are significant and worth understanding.

XML Schema Definitions

This is the heart of Pub 5717. It defines the XML schemas for every form type supported by the IRIS A2A channel. Each schema specifies:

• Element hierarchy — The parent-child structure of the XML document
• Required vs optional elements — Which fields must be present for the submission to validate
• Data types and constraints — String lengths, numeric formats, enumerated values, and date formats
• Namespace definitions — The XML namespaces used for validation

The XML schemas are published as XSD (XML Schema Definition) files that your code can use for client-side validation before submitting to the IRS. For a higher-level overview of the XML format, see our IRIS XML format guide.

SOAP Web Service Operations

The IRIS A2A channel uses SOAP (Simple Object Access Protocol) web services, not REST APIs. This is a significant architectural choice that affects how developers build integrations. Pub 5717 defines the available SOAP operations, including:

• Submission operations — Sending one or more information returns to the IRS
• Status inquiry operations — Checking the processing status of a previous submission
• Correction operations — Submitting corrections to previously filed returns
• Acknowledgment retrieval — Retrieving IRS acknowledgments and acceptance/rejection details

Each operation has a defined WSDL (Web Services Description Language) document, request/response message formats, and fault handling specifications.

Error Codes and Validation

Pub 5717 includes a comprehensive catalog of error codes that the IRIS system can return. These range from schema validation failures (malformed XML, missing required elements) to business logic errors (invalid TIN format, duplicate submissions). Understanding these error codes is essential for building robust error handling into your integration.

IRIS provides more granular and immediate error feedback than FIRE did. While FIRE used batch processing with delayed error notification, IRIS validates submissions in near-real-time and returns specific error codes with actionable descriptions.

Testing Environment and Procedures

Pub 5717 documents the IRIS testing (sandbox) environment, including:

• How to access the test environment
• Test TINs and data sets for validation
• Expected responses for various test scenarios
• Requirements for production certification

All new A2A integrations must pass testing before they can submit to the production environment. The testing process validates that your software correctly generates XML, handles authentication, and processes responses.

Publication 5717 vs Publication 1220: What Changed

If your team is familiar with Publication 1220 (the FIRE specification), here is how Pub 5717 differs:

Aspect	Pub 1220 (FIRE)	Pub 5717 (IRIS A2A)
Data format	Fixed-width text (ASCII)	XML with published XSD schemas
Protocol	File upload via web portal	SOAP web services
Validation	Batch processing, delayed feedback	Near-real-time, per-submission
Error reporting	Generic error categories	Granular error codes with descriptions
Authentication	Username/password via FIRE web portal	Token-based API authentication
Testing	Separate test file upload process	Dedicated sandbox environment with test data
Document length	~300 pages	~400+ pages (more detailed)

For a broader comparison of the two systems (not just the specs), see our IRIS vs FIRE comparison.

Where to Get Publication 5717

Publication 5717 is available for free from the IRS:

• IRS.gov: Search for "Publication 5717" on irs.gov or check the IRIS A2A documentation page
• IRS IRIS Developer Resources: The A2A developer portal includes the publication alongside XSD files, WSDL documents, and sample code
• Updated annually: The IRS publishes revised versions of Pub 5717 as IRIS evolves and new form types are added. Always verify you have the current version.

BoomTax Implements Pub 5717 So You Don't Have To

Building a direct IRIS A2A integration is a serious engineering effort. It requires understanding SOAP services, implementing XML schema validation, handling token-based authentication, managing error codes, and passing IRS testing certification. For most organizations, this is months of developer time that could be spent on your core business.

BoomTax has already implemented the full Pub 5717 specification. When you file through BoomTax — whether through our web interface, bulk upload, or API — BoomTax handles the IRIS A2A communication, XML generation, authentication, error handling, and status tracking. You get a simple, modern interface on top of the complex IRS infrastructure.

For organizations evaluating whether to build a direct integration or use a provider, see BoomTax vs IRIS direct filing and our IRIS API integration guide.

Frequently Asked Questions

Next Steps

• IRIS API integration guide
• IRIS testing and sandbox guide
• IRIS error codes reference
• IRIS XML format guide
• FIRE-to-IRIS migration guide for enterprise IT
• BoomTax vs IRIS direct filing