Pulling IRS Transcripts

How IRS A2A / Auto-Login Works — The Plumbing

Before debugging errors, it helps to know what your transcript software is actually doing behind the scenes. The surface experience — click a button, get a PDF — hides several moving parts, and most errors are diagnosable faster if you know which part failed.

The two paths

Modern transcript access runs through one of two channels:

• A2A (Application-to-Application). The IRS's programmatic interface. Your software authenticates as a registered application using cryptographic keys, then requests transcripts on behalf of the taxpayer under your CAF authority. A2A is the high-throughput path and the one TRH uses by default.
• Auto-Login / TDS interactive. A browser-like session against the Transcript Delivery System. Your software logs into e-Services with your credentials, navigates TDS, and retrieves transcripts through the same interface a human would use. Slower, more fragile, but still present in many tools as a fallback.

What an A2A request actually looks like

1. Your software signs a request using your registered private key.
2. The request hits an IRS endpoint with your Client ID, User ID, Key ID, and a timestamped signature.
3. The IRS validates the signature, checks that the request aligns with a valid CAF authorization for the taxpayer and period, and responds.
4. The response is either the transcript payload or an error.

The prerequisites

• An e-Services account with Transcript Delivery System + A2A approval.
• A registered private key whose public half the IRS has on file.
• A valid CAF number with 2848 or 8821 authority for the taxpayer, form, and tax period in question.
• Client ID, User ID, Key ID configured in the software.
• Network connectivity to the IRS endpoints.

Most real-world errors are caused by one of these five prerequisites being wrong, expired, or out of sync.

See also: TRH Knowledge Base: IRS A2A authentication.

The Authentication Chain — Why One Bad Credential Breaks Everything

A2A authentication involves a chain of credentials. If any single link is wrong, nothing downstream works — and the error you see often describes the symptom, not the root cause. Understanding the chain lets you bisect quickly.

The chain, in order

1. Your e-Services identity. User ID, password, and current 2FA. If this is bad, you cannot log into e-Services at all.
2. A2A application registration. Your Client ID identifies your registered application. If the application registration has lapsed or been revoked, requests fail.
3. Private key. The file your software signs requests with. If the file is missing, corrupted, or the wrong key for the registered Client ID, signatures will not verify.
4. Key ID. The identifier the IRS uses to look up which public key to verify against. If your Key ID does not match what the IRS has on file for this Client ID, signatures fail.
5. CAF authority. Even with perfect authentication, a specific transcript pull also requires a posted 2848 or 8821 for the taxpayer, form, and year.
6. Taxpayer identity data. SSN/EIN, name control, address — must match IRS records.

How errors cascade

The IRS's error messages are not always specific. A bad private key and a bad Key ID can both surface as a generic signature-failure error. A revoked A2A application and an expired e-Services account can both present as "unauthorized." The general rule: if everything fails, the problem is at the top of the chain (e-Services or A2A registration). If only specific taxpayers fail, the problem is at the bottom (CAF or taxpayer data).

Bisecting a failure

A quick way to narrow down:

1. Can you log into e-Services in a browser? If no — top of chain.
2. Can you pull any transcript at all through your software? If no — still likely top of chain (auth or key).
3. Can you pull transcripts for one taxpayer but not another? Bottom of chain — CAF or taxpayer data.
4. Can you pull some periods for a taxpayer but not others? Authorization scope issue — the 2848 does not cover the period.

401 Unauthorized — Credential and Token Issues

HTTP 401 is the most common authentication failure. It means the IRS rejected the request before looking at what you asked for — your identity did not check out.

Likely causes, in order of frequency

• e-Services password expired. e-Services passwords expire on a schedule. An expired password will not authenticate even if the software is still caching the old value.
• Expired or rotated private key. If you rotated your key and did not register the new public half with the IRS, signatures will fail.
• Wrong Key ID configured in the software. You rotated keys but did not update the Key ID field in your software's configuration.
• Clock skew. Signed requests include timestamps. If your workstation's clock is off by more than a small tolerance, the IRS may reject signatures as stale or future-dated.
• 2FA required but not completed. Some e-Services interactions require fresh multi-factor authentication; a cached token may have expired.
• A2A application registration revoked or expired. Rare, but happens when application registrations lapse due to inactivity or administrative action.

Diagnostic order

1. Open e-Services in a browser and log in. If that fails too, it is a password or 2FA issue — fix it there.
2. Check the clock on your workstation. If it is more than a minute or two off, fix it and retry.
3. Re-confirm the Client ID, User ID, and Key ID in your software config match what you registered with the IRS.
4. Try a test request against a taxpayer you know you have authority for. If it fails identically, the issue is up-chain (auth), not per-taxpayer.
5. If you recently rotated the private key, roll back or re-register.

403 Forbidden — IRS Blocking, and What to Do

403 is different from 401. 401 says "we do not know who you are." 403 says "we know who you are and we will not let you do this." The authentication succeeded; the authorization failed.

Common 403 causes

• No CAF authority for this taxpayer or period. You are authenticated, but no 2848 / 8821 covers the specific taxpayer, form, or year you requested.
• Account locked for ID-theft review. The taxpayer's account is frozen pending an ID-theft resolution (see Chapter 9).
• IRS-side IP block. Rare, but possible if a workstation or network has tripped abuse heuristics.
• A2A application in a restricted state. Administrative hold on the registered application.
• Business transcript requested with individual-only authority (or vice versa).

Diagnostic steps

1. Try a different taxpayer. If the second one works, the first is a CAF-scope or ID-theft issue specific to that client.
2. Try a different tax period or form for the same taxpayer. If the other period works, your 2848 scope does not cover the period you asked for.
3. If nothing works and 401 is not the error, suspect an application-registration issue or an IP block.
4. Check e-Services in a browser for any messages from the IRS about the account.

429 Rate Limited — Pacing, Daily Limits, Pause Strategies

The IRS A2A interface applies rate limits. Requests beyond the threshold return 429 Too Many Requests. The published details change over time, but the operational reality is that you need to pace bulk work.

What typically triggers 429

• Bulk operations that submit hundreds of requests in rapid succession.
• Aggressive retry loops on transient errors.
• Multiple tools making A2A calls concurrently under the same application registration.
• End-of-quarter or peak-day traffic spikes where IRS-side capacity tightens.

How good transcript software handles it

• Spreads bulk requests over a sustained rate rather than bursting.
• Honors 429 responses with exponential backoff.
• Pauses and resumes gracefully rather than failing an entire batch.
• Surfaces a clear "rate limited — pausing for N seconds" message so the user is not guessing.

What to do when you see 429

1. Pause. Do not retry immediately.
2. If your software has a resumable batch feature, let it handle the wait.
3. If you are running multiple tools simultaneously, consolidate to one.
4. For very large batches, consider splitting across multiple days.

CAF Not Valid / CAF Mismatch — The #1 Error

"CAF not valid," "CAF mismatch," and "no authorization on file" are three wordings of the same family of error. You are authenticated, but the IRS does not find a CAF authorization that covers this request. This category accounts for the largest share of day-to-day transcript-pull failures.

The usual suspects

• Propagating 2848. The form is filed and possibly even posted in the CAF database, but has not yet propagated to the TDS / A2A systems. Wait a day or two; retry.
• Scope mismatch. The 2848 covers Form 1040 but you asked for a 941. Or it covers 2021 but you asked for 2020. Each pull is scoped to a specific form and period.
• Superseded 2848. The taxpayer signed a new 2848 naming a different rep, and that form did not retain your authority.
• Revoked authorization. Taxpayer revoked, or an administrative event stripped authority. Check the Account Transcript for TC 961 where possible.
• Rep record drift. Your rep information changed (address, name) and the stored form references stale info. Usually manifests on specific filings made before the update.
• Name control mismatch on the taxpayer. Marriage/divorce name changes that were never reflected at SSA/IRS.

Diagnostic order

1. Pull your CAF list. Does this taxpayer, this form, and this period appear?
2. If it appears in the CAF list but the pull still fails, it is a propagation or system-specific visibility issue — give it a day and retry, then escalate.
3. If it does not appear in the CAF list, the authorization is not in effect. Review the last 2848: was it filed, was it processed, was it superseded?
4. If the 2848 was filed but is not in the CAF list, it was either rejected or is still in processing. Check for any notice from the CAF unit.

See also: Volume 2 (CAF Provisioning), Chapters 4 and 5.

Information Mismatch — SSN, Name, DOB, Filing Status

A taxpayer's identity data must align with IRS records. Mismatches produce a specific family of errors: "Information mismatch," "Taxpayer identity not verified," and in Auto-Login flows the generic "we could not verify your information" message.

Common mismatch sources

• Name control. The first four letters of the primary last name (or first four significant characters of a business name) must match what the IRS has. Hyphenated names, suffixes, apostrophes, and recent legal name changes all cause trouble.
• SSN typo. Transposed digits in intake. Verify against the Social Security card or a prior tax return, not the client's memory.
• Filing status. Some verification flows ask for filing status from a recent return. MFJ vs MFS vs HoH matter.
• Date of birth. Check Social Security card, not driver's license (which can sometimes carry a different recorded DOB due to historical corrections).
• Address. The address the IRS has on file may differ from the client's current address if they moved without filing a Form 8822 or updating through a return.
• Prior-year AGI. Used in some verification flows. Must match the return as processed, which may differ from the return as filed if there was a math-error adjustment.

Fixing mismatches

• Name-control: verify against the name on file at SSA; if SSA is current but IRS is not, a name change at IRS typically happens via the next return or a specific correction process.
• DOB: if the SSA record is wrong, the client must correct it at SSA first; IRS propagates from SSA.
• Address: filing Form 8822 (individual) or 8822-B (business) is the standard fix. The next transcript pull after the change posts should succeed.
• SSN typo: no fix needed other than correcting the typo on your end.
• Prior-year AGI: pull the Return Transcript or Record of Account to confirm the processed AGI — that is what verification flows require.

Taxpayer Not Found — When the IRS Has No Record

"Taxpayer not found" is distinct from "information mismatch." The IRS is telling you it has no record matching your search — either for the TIN, for the form, or for the tax period.

Top causes

• Return never filed for that period. Common for unfiled-year clients. The IMF or BMF has no record of that tax period yet.
• Wrong tax period. Fiscal-year entities with a June or September year-end. Asking for YYYY12 on an entity that files YYYY06 returns "not found."
• Wrong form number. Requesting a 941 transcript for an entity that only files 940 annually.
• Wrong TIN. Typo, or a sole proprietorship where you used the EIN when the activity was actually on the 1040 Schedule C under the SSN.
• Entity not yet registered. A brand-new EIN that has not yet filed any return.
• Recently deceased taxpayer. The account may be flagged or moved to estate handling.

What to check

1. Verify the TIN.
2. Verify the form number expected for this taxpayer.
3. Verify the tax period — especially fiscal-year end dates.
4. For unfiled years, switch to Wage & Income — the third-party data is usually there even when no return was filed.
5. For entities, confirm the entity has filed at least one return of the type you are requesting.

ID Theft Indicator / Fraud Review — Flags That Block Pulls

ID-theft markers and fraud reviews are a specific class of transcript-pull failures. The authentication is fine, the CAF is fine, the taxpayer exists — but the account is locked pending investigation.

The markers you will see

• TC 971 AC 121 — ID-theft case opened on the account.
• TC 976 — duplicate return, often paired with ID-theft.
• Account-level freeze indicator — visible on the transcript header or via PPS.
• IP PIN requirements — a taxpayer with an IP PIN may still be accessible via transcripts, but e-file of new returns requires the PIN.

What the client needs to do

• File Form 14039 if not already filed.
• Obtain an IP PIN for future years.
• Work with the IRS Identity Theft Victim Assistance function; allow the resolution timeline, which has historically been lengthy.

What the practitioner does in the meantime

• Maintain your 2848 — you need current authority when access opens back up.
• Document everything — the timeline, the notices, communications with the taxpayer.
• Coordinate with the IRS Identity Protection Specialized Unit (IPSU) as appropriate.
• Set client expectations realistically. ID-theft resolution is not a one-call fix.

See also: Volume 1 (Reading Transcripts), Chapter 4.

Business vs Individual — Different Authentication Paths

BMF (business) and IMF (individual) transcripts live in different IRS subsystems with slightly different rules. Most errors that only happen on business pulls come from this split.

Where BMF differs

• TIN format. EIN (XX-XXXXXXX) vs SSN (XXX-XX-XXXX). Your software must route correctly based on the TIN kind.
• Name control. First four significant characters of the business name. Rules for "The," ampersands, and punctuation differ from individual name-control rules.
• Form coverage. 941, 940, 944, 1120, 1120-S, 1065. A 2848 must specifically cover each form you want to pull.
• Fiscal years. Tax periods are YYYYMM where MM is the fiscal year-end month.
• Responsible-party changes. For BMF, the IRS cares who the responsible party is; changes filed on Form 8822-B affect who can act on behalf of the entity.

Errors that frequently trip BMF pulls

• Requesting YYYY12 for an entity with a fiscal year-end other than December.
• Missing a sub-form (e.g., the 2848 covers 1120 but not 941).
• Business name control mismatches after an entity name change.
• Sole proprietorships where the taxpayer reports on Schedule C under their SSN, but the practitioner requests an EIN-based BMF transcript that does not exist.

Diagnostic tips

• Confirm the entity's fiscal year-end before pulling.
• List every form on the 2848 — do not rely on "all business forms" language.
• For a sole prop, start with the IMF transcript under the SSN, not the EIN.

See also: Volume 1, Chapter 8 (BMF vs IMF).

Network, Transport, and Session Errors

Not every error is IRS-side. The connection between your workstation and the IRS can fail in its own distinctive ways.

Symptoms

• Generic "connection reset," "timeout," or "cannot reach host."
• TLS / SSL handshake failures.
• Intermittent failures that clear after a network hiccup.
• Proxy or firewall blocks (common in large firms).

Causes and fixes

• Corporate firewall / proxy. Some firms route all outbound traffic through a proxy that may intercept or break TLS connections to IRS endpoints. Solution: whitelist the relevant IRS hosts or route transcript-software traffic around the proxy.
• Outdated OS or TLS stack. Very old Windows installs may not negotiate modern TLS cipher suites. Solution: update Windows and any TLS-related components.
• Workstation clock skew. Beyond signing issues, significant clock skew also breaks certificate validation.
• Transient ISP / routing issues. A2A endpoints are not immune to general internet trouble. Test by opening e-Services in a browser; if the browser cannot load it either, the network is the problem.
• IRS-side scheduled maintenance. The IRS publishes maintenance windows for e-Services and A2A. Pulls during these windows will fail with connection or 5xx errors.

Diagnostic sequence

1. Can you browse to e-Services at all?
2. Can your software ping the IRS endpoints (if it has a test-connection feature)?
3. Is there a known IRS maintenance window active?
4. Is anti-virus, VPN, or firewall software unusually active?
5. Try again in 15 minutes before escalating — many network issues are transient.

When to Give Up and Call PPS — The Escalation Checklist

Most errors resolve without picking up the phone. When they do not, PPS or a Revenue Officer / examiner call is the next step. The goal is to make the call productive.

Stop trying and pick up the phone when:

• A 2848 is posted on your CAF list but TDS / A2A consistently cannot see it after 10+ business days.
• You have verified every authentication and identity data point and pulls still fail.
• An Account Transcript shows a hold (TC 570 or TC 520) you cannot explain and the transcript is not giving you a paired release or reason.
• A client reports a notice you cannot locate on the transcript.
• You suspect an ID-theft or fraud hold and the taxpayer needs it cleared.
• An adjustment posted that you cannot source to any notice or action.

What to have in front of you before calling

1. A current 2848 on file covering the taxpayer and period.
2. Your CAF number, PTIN, and credential info.
3. The Account Transcript for the year at issue, printed or on-screen.
4. The exact error message your software returned (wording matters).
5. Any notice numbers in play.
6. A written one-or-two-sentence question.

How to describe the problem on the call

• Lead with your identity and authority (CAF, 2848 reference).
• Describe what you expected and what actually happened.
• Say what you have already verified — "I confirmed the 2848 is on my CAF list, I verified the name control, I checked the period" — so the rep does not repeat your work.
• Ask for a clear resolution or next step, and capture their name and ID for the log.

See also: Volume 2, Chapter 10 (When to call PPS).