IRS Guidance API: Revenue Rulings, Revenue Procedures, Notices, and Announcements

Short answer: an IRS guidance API returns the four instruments the Service publishes in the Internal Revenue Bulletin (Revenue Rulings, Revenue Procedures, Notices, and Announcements) as structured, citable records, so your software can read them the same way it reads a statute section. In Vaquill AI's corpus those are four separately filterable sources (irs_rev_proc, irs_rev_rul, irs_notice, irs_announcement) holding more than 1,400 documents combined, 2015 to present, all under corpusType=AGENCY_GUIDANCE on the cadence that board declares on GET /boards. The part most integrations get wrong isn't the fetch. It is the hierarchy: the Internal Revenue Code is the statute, the Treasury Regulations are the rules, and published guidance sits below both and tells you how the Service will administer them. Build the ordering into your data model or your answers will cite a Notice where they should have cited a regulation.

Reviewed and corrected on 12 October 2026. This is general information, not legal advice.

TL;DR

• Three layers, in order: USC Title 26 (the Code) beats 26 CFR (the Treasury Regulations), which beats IRS published guidance. Guidance never overrides a regulation, and a regulation never overrides the statute.
• The four instruments do different jobs. A Revenue Ruling applies the law to a stated set of facts. A Revenue Procedure sets out a procedure or a safe harbor. A Notice states a position or interim guidance ahead of regulations. An Announcement is administrative and usually short-lived.
• Weight, honestly: published guidance states the Service's own position. Taxpayers generally may rely on published Revenue Rulings, and Bulletin guidance counts as authority for the substantial-authority penalty test. It is not a regulation, and a court isn't bound by it.
• Corpus scope: more than 1,400 IRS documents across four filterable source codes, 2015 to present. Pre-2015 guidance isn't in the corpus, so a lookup for Rev. Proc. 87-56 or Notice 2014-21 won't find it here.
• One source is synthesized, not verbatim. administrative_guidance holds Vaquill-built summary items (SALT cap, Child Tax Credit, 401(k) limits). Treat it as a convenience layer, never as an agency publication you can quote.
• actId is stable and not guessable. Take it from a search or resolve response. Hand-built IDs 404.

This is one entry in our federal agency guidance series.

For related coverage, see Federal Agency Guidance API: 53 Sub-Regulatory Sources in One Endpoint, Banking and AML Guidance API: OCC, FDIC, Federal Reserve, and FinCEN in One Query, and US Tax Treaty API: Bilateral Treaties and Technical Explanations, Citable by Article.

Start with the hierarchy, because that is what breaks

Tax is one of the few areas where the sub-regulatory layer is thicker than the regulatory one. That is why so many tax products end up quoting a Notice as if it were law.

Congress writes the Internal Revenue Code, codified as USC Title 26. Treasury, through the IRS, issues the Treasury Regulations at 26 CFR, which go through notice and comment and carry the force of law. Below both, the IRS publishes guidance in the Internal Revenue Bulletin telling the world how it will administer the first two layers.

The practical rule for a retrieval system: never let a guidance hit outrank a regulation hit for the same question. If a user asks what the rule is, the answer starts at 26 CFR. Guidance answers a different question, which is how the Service will apply that rule and what it will accept on a return.

A short history of how much courts listen to the IRS

Treasury Regulations are the IRS writing rules. Everything below them is the IRS explaining itself. So how much should a judge care what it says? The Supreme Court has been answering that for a long time.

In 1944, in Skidmore v. Swift & Co., Justice Jackson wrote for the Court that the weight of an agency's judgment in a given case would "depend upon the thoroughness evident in its consideration, the validity of its reasoning, its consistency with earlier and later pronouncements, and all those factors which give it power to persuade, if lacking power to control." That is the quote as the Court repeated it in 2024 in Loper Bright Enterprises v. Raimondo. In between came Chevron (1984), under which courts sometimes had to defer to a reasonable agency reading of a statute even when they read it differently. Loper Bright, decided June 28, 2024, overruled Chevron. The Court also said judges may still look to the agency's reading of a statute for help, as they always have, citing Skidmore.

For a Notice or a Rev. Proc., that means the old standard is the live one. A court listens as hard as the document earns: careful reasoning, consistency over time, real expertise. It never has to obey.

The four instruments, precisely

Revenue Ruling

A Revenue Ruling states a set of facts, identifies an issue, and gives the Service's holding on how the law applies to those facts. It is the closest thing the IRS publishes to a mini opinion.

Rulings are published in the Bulletin and are meant to be relied on by taxpayers whose facts are substantially the same. Rev. Rul. 2019-24, on the treatment of cryptocurrency hard forks, is a clean example of the shape: facts, issue, holding, then the analysis that gets there.

What a ruling isn't: a rule of general application written through notice and comment. Under 26 C.F.R. 601.601(d)(2)(v)(d), revenue rulings published in the Bulletin do not have the force and effect of Treasury Regulations.

Revenue Procedure

A Revenue Procedure tells you how to do something, or draws a line you can stand behind. Annual inflation adjustments, method-change procedures, automatic consent lists, and safe harbors all arrive as Rev. Procs.

Rev. Proc. 2015-13 is the canonical example: the master procedure for accounting method changes, with the automatic and non-automatic tracks laid out. It is still the master procedure, as clarified and modified by later procedures, and the list of automatic changes it points to is reissued often (Rev. Proc. 2025-23, published in Internal Revenue Bulletin 2025-24 dated June 9, 2025, updated that list). A tax engine that doesn't carry the current Rev. Proc. for a method change will produce a filing that is substantively right and procedurally dead.

Rev. Procs. supersede each other constantly. Status handling is covered in the status and currency reference. That matters for a corpus design decision covered further down.

Notice

A Notice states a position or gives interim guidance ahead of regulations. It is a common vehicle when a statute takes effect before Treasury has written rules.

Notice 2020-32, on whether expenses paid with a forgiven PPP loan were deductible, is a good example of the pattern: a live question and a stated Service position. In that Notice the position was no deduction. Congress then overruled it by statute in the Consolidated Appropriations Act, 2021, signed December 27, 2020, which allows the deduction, according to the Congressional Research Service (IN11378). Notices get overtaken by regulations, by statute and by later guidance, and the older Notice stays on the books meaning something narrower than it did on day one, or nothing at all.

If you are building an answer engine, a Notice can be stale in a way that reads current.

Announcement

An Announcement is administrative and usually short-lived. Disaster-relief filing extensions, corrections to a prior document, procedural changes to a program, and notices of public hearings arrive this way.

Most Announcements have no long-run interpretive value. Keeping them in the corpus is still correct, because "what did the Service say about the filing deadline that year" is a real question, and answering it from memory is how a product invents facts.

How much weight to give it

Say this plainly in your product, because users assume more authority than exists.

Toward the Service, published guidance is its own stated position. The IRS applies its published positions, and under 26 C.F.R. 601.601(d)(2)(v)(e) taxpayers generally may rely on Revenue Rulings published in the Bulletin, provided the facts and circumstances are substantially the same. Guidance published in the Bulletin also counts as "authority" for the substantial-authority penalty test at 26 C.F.R. 1.6662-4(d)(3)(iii), which is a concrete reason a tax product needs this corpus alongside the Code itself.

Toward a court, it is persuasive at best. A court reviews the statute and the regulation. Sub-regulatory guidance generally doesn't go through notice and comment and gets weighed for its persuasiveness, not obeyed. Since Loper Bright Enterprises v. Raimondo (2024), the deference story for agency interpretations has gotten less generous, not more.

The one-line version worth putting in your own UI: published IRS guidance tells you what the Service will do, Treasury Regulations tell you what the rule is, and a court decides what the statute means. Show the citation for all three when all three exist.

A Hacker News commenter explaining Notice 2014-21 in October 2020 said it in fewer words: "IRS guidance aren't laws but they detail how the IRS is going to treat tax collection based on current law." (BitwiseFool, Hacker News, October 2020). The Notice itself backs that reading. It says it "describes how existing general tax principles apply to transactions using virtual currency," answers in FAQ form that virtual currency "is treated as property," and asks the public for comments on what it left out. You can read it at irs.gov.

The reliance side is in the Service's own procedural rules too. 26 C.F.R. 601.601(d)(2)(v)(e) says taxpayers "generally may rely upon Revenue Rulings published in the Bulletin," and the same paragraph cautions against reaching the same conclusion "unless the facts and circumstances are substantially the same."

A quick story: a Notice with penalties attached

Notices sound mild. Some aren't. In 2016 the IRS issued Notice 2016-66, which named certain micro-captive insurance arrangements as reportable transactions. As the Supreme Court described it, the Notice compels taxpayers and "material advisors" to describe the transaction, and failing to do so carries civil penalties of $50,000 for advisors, plus criminal exposure for willful violations. CIC Services, an advisor, sued before the first reporting date, arguing the IRS had issued the Notice without notice-and-comment procedures. On May 17, 2021 a unanimous Court held the suit could go forward, because a suit to set aside the Notice is not a suit to restrain the collection of a tax (CIC Services v. IRS).

A sibling story reached the end of its road in 2023. Chief Judge Sutton opened the Sixth Circuit's opinion in Mann Construction with: "When the Internal Revenue Service levied tax penalties against Mann Construction and its owners under one of its regulations, technically a Notice, the taxpayers replied that the IRS violated the Administrative Procedure Act." The court had already held, in a 2022 opinion (Mann Construction, Inc. v. United States, 27 F.4th 1138), that Notice 2007-83, which labeled certain employee-benefit plans with cash-value life insurance as listed transactions, was a legislative rule that lacked an exemption from notice and comment. The IRS refunded the penalties ($10,000, $8,642 and $7,794 across three taxpayers) and, in Announcement 2022-28, agreed not to apply the Notice to the taxpayers or anyone else within the Sixth Circuit. On November 20, 2023 the court vacated a district court's nationwide invalidation of the Notice as moot (Mann Construction v. United States).

The lesson for a tax product is small and practical. A Notice can be contested, narrowed by a court, and then walked back by a later Announcement, and none of that changes its citation. If your system stores a Notice without a status, it will keep serving it with a straight face.

A quick story: the law started before the guidance

Congress changed the tax treatment of research and software development costs (section 174) for tax years beginning after December 31, 2021. For those years developers' pay had to be capitalized and amortized instead of deducted at once. Then everyone waited for the IRS to say what counted.

The paper trail shows how a rule gets assembled one instrument at a time. According to Notice 2023-63, Rev. Proc. 2023-8 was issued December 12, 2022, to give automatic consent for the accounting method change. Seventeen days later, on December 29, Rev. Proc. 2023-11 modified and superseded it, and that change was later folded into section 7.02 of Rev. Proc. 2023-24. Notice 2023-63 itself then announced forthcoming proposed regulations, gave interim guidance in the meantime, and said in section 10 that taxpayers may rely on that interim guidance before the proposed regulations are published (Notice 2023-63).

Engineers felt the delay. In a June 2025 thread about which software work gets capitalized, one commenter explained that "the guidance was released in 2023 under notice 2023-63" (gortok, Hacker News, June 2025). Nearly two years of statute with no detailed interim guidance, and then the detail arrived in a Notice that promised regulations. That's the normal rhythm of tax: the Code moves first, Notices and Rev. Procs. fill in, and regulations come last.

Then the Code moved again. Pub. L. 119-21, signed July 4, 2025, added section 174A, which allows a deduction for domestic research or experimental expenditures, and treats software development as research or experimental expenditures, for amounts paid or incurred in tax years beginning after December 31, 2024, with an election letting eligible small businesses apply it back to tax years beginning after December 31, 2021 (26 U.S.C. 174A, effective-date note). Guidance written for the 2022 to 2024 rules, Notice 2023-63 included, therefore needs a status check before anyone applies it to a current year. Notice 2023-63 was itself clarified and modified by Notice 2024-12, and Rev. Proc. 2025-28 sets procedures for the elections under section 70302(f) of the 2025 act.

What the corpus actually holds

The four IRS sources live inside corpusType=AGENCY_GUIDANCE, which spans 53 named federal sources and more than 96,000 documents. Each source is filterable on its own with source=, and every corpus token is listed in the corpus types reference.

That is the general rule for any legal corpus. A window you can read in the response is a window you can design around; a corpus that quietly returns nothing for a document that plainly exists is the one that hurts you.

The synthesized source, labeled as such

There is a separate source code, administrative_guidance, holding Vaquill-synthesized items such as the SALT cap, the Child Tax Credit, and 401(k) contribution limits. These are convenience records built to answer a common question directly.

They are not verbatim agency publications. Do not quote them as the IRS's words, don't put them behind a "source: IRS" label, and don't let them satisfy a citation requirement.

If your product surfaces them, badge them differently from the four irs_* sources. The whole value of a primary-law dependency is that a reader can click through to the publisher's own copy, and a synthesized item has no such copy to click through to.

Worked example: chaining Code to regulation to guidance

Here is the actual shape of a three-hop tax lookup. Base URL is https://api.vaquill.ai/api/v1, auth is Authorization: Bearer vq_key_..., and search is 4 credits per call. The requests below use the request shape in the API's OpenAPI document, and you can try them in the API playground. On 12 October 2026 they returned 26 U.S.C. § 446, 26 C.F.R. § 1.446-1 and Rev. Proc. 2023-11 as their top hits.

Hop 1: the statute. Find the Code section first, so everything downstream is anchored to it.

POST /us/statutes/search
{
  "query": "change in method of accounting consent of the Secretary",
  "corpusType": "USC",
  "titleNumber": 26,
  "limit": 5
}

Hop 2: the regulation. Same title number, different corpus. This is the layer that carries the force of law.

POST /us/statutes/search
{
  "query": "change in method of accounting procedures for obtaining consent",
  "corpusType": "CFR",
  "titleNumber": 26,
  "limit": 10
}

Hop 3: the guidance. Now ask what the Service will actually accept, restricted to the two instruments that carry procedures.

POST /us/statutes/search
{
  "query": "automatic consent accounting method change procedures",
  "corpusType": "AGENCY_GUIDANCE",
  "source": ["irs_rev_proc", "irs_notice"],
  "matchType": "all",
  "limit": 10
}

Three calls, twelve credits, and an answer that can show the statute, the rule, and the administration in one response. Rev. Proc. 2023-11, the top guidance hit, is also a reminder to check status: it is the procedure that Notice 2023-63 says was folded into Rev. Proc. 2023-24. Every hit carries the official source URL for the publisher's own copy, so a reviewer can verify without leaving the workflow.

Take the actId from the response and use it for the follow-up fetch. IDs are stable and not guessable (real examples from other corpora look like USC_T42_C21_S1983), so a hand-built identifier usually 404s, a shape the section identifier reference explains. When all you hold is a citation string, use citation resolution.

GET /us/statutes/section/{actId}
GET /us/statutes/section/{actId}/body

Filters that behave the way a tax integration needs

Unknown filter values are rejected with 422 rather than silently matching nothing. If you typo irs_revrul, you get an error, and the error message lists every valid source code. That means the API documents its own vocabulary, and a bad filter can never masquerade as an empty corpus.

A request that fails validation is not charged. A 422 costs nothing, so validating against the live API during development is free.

Paging is cut from one ranking. Results never repeat or go missing between pages, and page 4 costs the same as page 1. limit maxes at 50 and offset at 70.

yearFrom and yearTo filter on the last amendment year the publisher credits, not on our rebuild date. Useful caveat: about a fifth of sections across the whole corpus carry no amendment credit at all, because some publishers print none, and those drop out as soon as you set either bound. publishedFrom and publishedTo apply to Federal Register documents only, so for IRS guidance narrow with source and read the year in the citation.

What is not in the IRS slice

Being specific about the edges is more useful than a coverage boast.

The four instruments above are the IRS's published guidance of general application. Two further IRS corpora landed in September 2026 and are worth naming separately, because they answer a different question.

Written determinations are served under source=irs_written_determination: private letter rulings, chief counsel advice, technical advice memoranda and the determination letters issued to tax-exempt organizations. 35,485 written determinations are served. The Internal Revenue Manual is served under source=irs_irm.

Read a written determination for what it is. Under 26 U.S.C. 6110(k)(3) it binds the one taxpayer who asked and may not be cited as precedent by anyone else. That is the statute, not our caveat, and every one of these documents carries actStatus: "non_precedential". The Internal Revenue Manual is agency procedure rather than law. Both are here because knowing how the IRS reasons is useful even when the document binds nobody but its addressee.

Adjacent tax material that is in the corpus:

• corpusType=USC, 60,494 sections at the Office of the Law Revision Counsel's current release point, on a weekly check cadence (read lastRetrievedAt on GET /boards against that cadence to see how recently it was pulled). Each section carries its own currentThrough date. Title 26 lives here.
• corpusType=CFR, 222,311 sections, refreshed daily. Title 26 lives here.
• corpusType=FEDERAL_REGISTER, more than 196,000 agency rule documents (final and proposed) from 1994 to present. This is where a proposed Treasury reg shows up before it lands in the CFR, and querying those rule documents is its own exercise.
• corpusType=US_TAX_TREATY, more than 1,600 sections covering US bilateral tax treaties, Treasury Technical Explanations and the Senate's treaty records.
• corpusType=SESSION_LAW, more than 425,000 sections of Statutes at Large, 1789 to 2026. These carry actStatus: "enacted" and goodLawStatus: "unknown" on purpose, because law as enacted is a historical record, not a statement of current law.

Freshness and change detection

Ask GET /boards (it costs nothing) and every watchable source comes back with two fields worth reading together: cadence and lastRetrievedAt. The IRS Bulletin documents sit on the agency guidance board, and the Internal Revenue Manual on the agency manuals board. That is the pipeline's own honesty, not a marketing page.

GET /us/statutes/coverage is also free. It reports what we hold, not how recently it was refreshed, which is what GET /boards is for. The coverage guide lists the window for each source, and that is what stops a pre-2015 null result being read as an absence of guidance. Where a publisher states its own currency, it rides on each section as currentThrough. The full field list covers the rest.

Watches let you subscribe to a board and receive changes, with a per-section diff on a captured change. For a tax product, a watch that fires a webhook when a new Rev. Proc. lands is more valuable than any amount of retrieval polish.

sourceUrl points to the government publisher's own copy. Where we hold no official link it is null, and a third-party compiler is never substituted. The collection layer is published at github.com/Vaquill-AI/open-us-law, so the parsers behind these documents are inspectable.

FAQ

Is there an official IRS API for Revenue Rulings and Notices?

The IRS publishes the Internal Revenue Bulletin weekly and each guidance document on irs.gov, for example as a PDF in its irs-drop folder (Notice 2023-63 is at irs.gov/pub/irs-drop/n-23-63.pdf). Turning those documents into structured, citable records, with a mapping from citation to document, is the work an API does for you.

Does a Revenue Ruling have the same authority as a Treasury Regulation?

No. Treasury Regulations at 26 CFR go through notice and comment and carry the force of law. Revenue Rulings are the Service's published interpretations, which taxpayers with the same facts generally may rely on, but 26 C.F.R. 601.601(d)(2)(v)(d) says plainly that they don't have the force and effect of Treasury Regulations.

What is the difference between a Revenue Ruling and a Revenue Procedure?

A Revenue Ruling applies the law to a stated set of facts and gives the Service's holding. A Revenue Procedure tells you how to do something, such as a method-change procedure, an election, or a safe harbor. If the question is "is this taxable," you want a Ruling; if it is "how do I file for this," you want a Procedure.

Can I rely on an IRS Notice in a filing position?

Guidance published in the Internal Revenue Bulletin counts as authority for the substantial-authority penalty analysis under 26 C.F.R. 1.6662-4(d)(3)(iii), and that includes Notices. That is a penalty-protection question, not a merits question. A court isn't bound by the Notice and can read the statute differently.

How far back does this IRS guidance corpus go?

The four IRS sources cover 2015 to present, holding more than 1,400 documents combined. Pre-2015 guidance isn't in the corpus, so older documents that are still cited daily, such as Rev. Proc. 87-56, won't resolve. Plan for that gap explicitly instead of treating an empty result as an absence of law.

Can I query the Internal Revenue Code and the Treasury Regulations from the same API?

Yes. USC Title 26 sits in corpusType=USC (60,494 sections at the current Office of the Law Revision Counsel release point) and 26 CFR sits in corpusType=CFR (222,311 sections, refreshed daily). Both accept titleNumber: 26, so a three-hop statute to regulation to guidance chain is three calls against one surface.

Are private letter rulings included?

Yes, since September 2026. Private letter rulings, chief counsel advice and technical advice memoranda are served under source=irs_written_determination, and the Internal Revenue Manual under source=irs_irm. 35,485 written determinations are served. A written determination is directed at one taxpayer and may not be cited as precedent by anyone else under 26 U.S.C. 6110(k)(3), so treat it as evidence of the agency's reasoning rather than as authority.

Can I ask what a Revenue Procedure said on a past date?

Partly. A Rev. Proc. resolves to its current text, and asOf=YYYY-MM-DD on the section body call returns an earlier text rebuilt from changes we observed, flagged with isBounded when it rests on when capture began. Treat it as a reconstruction rather than a stored edition, and confirm anything you will cite against the IRS's own copy. You also get amendment history, a lastAmendedYear per section, a yearFrom/yearTo currency filter, change events per refresh, and per-section diffs on watched boards.

What is the administrative_guidance source and can I quote it?

It holds Vaquill-synthesized items such as the SALT cap, the Child Tax Credit, and 401(k) limits, written to answer a common question directly. It isn't a verbatim agency publication and has no publisher copy to link through to. Use it for orientation, badge it clearly in your UI, and cite the underlying Code, regulation, or IRB document instead.

How do I get a stable identifier for a guidance document?

Take the actId from a search or resolve response and store that. Identifiers are stable but not guessable, so constructing one from a citation string will usually 404. Once you hold an actId, GET /us/statutes/section/{actId} and /section/{actId}/body are the retrieval calls.

Priyansh Khodiyar

Co-Founder & CTO

Priyansh leads engineering and AI at Vaquill AI: the pipelines that pull statutes, regulations and court rules from every US jurisdiction's official publisher, and the REST API, MCP server and open dataset that serve them.