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 1,469 documents combined, 2015 to present, refreshed weekly, all under corpusType=AGENCY_GUIDANCE. The part most integrations get wrong is not 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.

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 binds the Service's own administration and taxpayers rely on it, including for penalty protection. It is not a regulation, and a court is not bound by it.
• Corpus scope: 1,469 IRS documents across four filterable source codes, 2015 to present, weekly refresh. Pre-2015 guidance is not in the corpus, so a lookup for Rev. Proc. 87-56 or Notice 2014-21 will not 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: 34 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.

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 is not: a rule of general application written through notice and comment. Under 26 C.F.R. 601.601(d)(2), 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. A tax engine that does not 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 the instrument the IRS reaches for when a statute takes effect faster than Treasury can write rules, which is most of the time after a large tax act.

Notice 2020-32, on whether expenses paid with a forgiven PPP loan were deductible, is a good example of the pattern: a live question, a stated Service position, and a promise that formal guidance may follow. Notices frequently get overtaken by proposed or final regulations, and the older Notice stays on the books meaning something narrower than it did on day one.

If you are building an answer engine, a Notice is the instrument most likely to 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 binding on its own administration. The IRS applies its published positions, and a taxpayer whose facts match can rely on them. 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 did not 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.

What the corpus actually holds

The four IRS sources live inside corpusType=AGENCY_GUIDANCE, which spans 34 named federal sources and 21,906 sections total. 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, do not put them behind a "source: IRS" label, and do not 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. Each call below runs as written in the API playground.

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. 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.

Failed calls are 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. For guidance work, prefer publishedFrom and publishedTo.

What is not in the IRS slice

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

The four instruments above are what the corpus carries from the IRS. Private letter rulings, technical advice memoranda, chief counsel advice, and the Internal Revenue Manual are not among the 34 named sources. PLRs and TAMs are taxpayer-specific and cannot be cited as precedent by anyone else, which is a defensible reason to leave them out, but you should know they are absent rather than discover it.

Adjacent tax material that is in the corpus:

• corpusType=USC, 60,170 sections, the 2024 edition current through 2025-01-06, checked weekly for a new edition. Title 26 lives here.
• corpusType=CFR, 219,114 sections, refreshed daily. Title 26 lives here.
• corpusType=FEDERAL_REGISTER, 202,526 agency rule documents (final and proposed) from 1994 to present, refreshed weekly. 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, 119 sections covering US bilateral tax treaties plus Treasury Technical Explanations.
• corpusType=SESSION_LAW, 110,287 sections of Statutes at Large (5,256 laws, 113th through 119th Congresses). 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

The IRS sources refresh weekly. Ask GET /boards (it costs nothing) and every watchable source comes back with three fields worth reading together: cadence, lastRetrievedAt, and retrievalStatus. That is the pipeline's own honesty, not a marketing page.

GET /us/statutes/coverage is also free, and for the IRS sources the field to read first is currency, because it states the coverage window in the publisher's own words rather than as a date somebody normalized. That is what stops a pre-2015 null result being read as an absence of guidance. 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 weekly IRB sweep that fires a webhook when a new Rev. Proc. lands is more valuable than any amount of retrieval polish.

The sourcing rule is the government publisher's own copy, and a commercial aggregator is never used as a source or as a fallback. 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 and individual guidance documents on irs.gov, but it does not run a per-citation JSON API that hands you a Revenue Ruling as structured data. Getting there means scraping, parsing, and maintaining a mapping from citation to document. That gap is why third-party guidance APIs exist.

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 published interpretations that bind the Service's administration and can be relied on by taxpayers with the same facts, but 26 C.F.R. 601.601(d)(2) says plainly that they do not 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 is not 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 1,469 documents combined and refreshing weekly. Pre-2015 guidance is not in the corpus, so older documents that are still cited daily, such as Rev. Proc. 87-56, will not 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,170 sections, 2024 edition current through 2025-01-06) and 26 CFR sits in corpusType=CFR (219,114 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?

No. Private letter rulings, technical advice memoranda, chief counsel advice, and the Internal Revenue Manual are not among the 34 named federal guidance sources in the corpus. PLRs are directed at one taxpayer and cannot be cited as precedent by anyone else, which is part of the reason.

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

Not today. A Rev. Proc. resolves to a single current text and nothing older, because no as_of=DATE parameter exists. You do get amendment history, a lastAmendedYear per section, a yearFrom/yearTo currency filter, change events per refresh, and per-section diffs on watched boards, so a point-in-time reconstruction has to come from somewhere else.

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 is not 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, from the matter workbench to drafting, document comparison, document matrix, and citation-verified research.