IRS Form 990 Nonprofit Financials & Grantmaker Data Scraper

Extract IRS Form 990 annual financials, aggregate executive compensation, foundation grantmaking, professional fees, and balance sheet totals for US tax-exempt organizations, built only on official IRS bulk data.

Found a problem or need a field? Open an issue on the Issues tab; we respond quickly.

---

What It Does

This actor downloads and stream-parses three official IRS datasets, resolved fresh from the IRS download and index pages at the start of every run (no dated URLs are hardcoded):

• EO Business Master File (BMF) extracts: one CSV per state, updated monthly by the IRS. Provides organization identity, NTEE code, subsection, address, tax period, and summary revenue and assets.
• SOI annual extracts: Statistics of Income extracts of Form 990, 990-EZ, and 990-PF filings (the newest filing year that publishes a Form 990 extract). Provides summary-grade financials.
• Form 990 e-file XML dataset: the IRS year index CSVs plus the TEOS XML batch zips for the newest two filing years. Provides full parsed 990 line items for electronically filed returns.

Each organization appears once, taken from its most recent tax period with data. When a parsed 990 XML filing is the newest record, the row carries full line items and summaryFinancials: false. When an organization appears only in the BMF or SOI summary extracts, the row falls back to those summary fields and summaryFinancials: true, so buyers are never misled about precision. Organizations with neither parsed nor summary data are excluded, and the exclusion count is stated in the run status.

Executive compensation is aggregate only. Form 990 Part VII lists named officers; this actor sums those amounts into a single executiveCompensationTotalUsd total and never emits a named individual's compensation.

---

Who It's For

• Philanthropic advisors and grantseekers: find grantmaking foundations, review annual giving and asset holdings.
• Wealth managers and planned giving officers: screen nonprofit endowments and balance sheet strength.
• B2B vendors and corporate partnerships: target established nonprofits above a revenue threshold.
• Researchers and reporters: study nonprofit sector economics and executive compensation in aggregate.

---

Input Parameters

Parameter	Type	Default	Description
searchKeyword	string	""	Case-insensitive substring matched against the organization name. Empty matches all.
states	array	["NY", "CA", "TX", "IL", "MA"]	State codes whose BMF files are processed. Empty processes the four BMF regional files (all states).
nteeCategoryId	integer	4	NTEE major category: 1 Arts, 2 Education, 3 Environment and Animals, 4 Health, 5 Human Services, 6 International, 7 Public and Societal Benefit, 8 Religion, 9 Mutual Benefit, 10 Unknown. 0 means all categories. The id is matched against the first letter of the BMF NTEE code.
cCodeSubsection	integer	3	IRC 501(c) subsection. 0 means all subsections.
minTotalRevenueUsd	integer	1000000	Minimum revenue, checked against the revenue of the exact filing each row is taken from.
maxItems	integer	1000	Maximum organizations returned, highest revenue first.

Canary Input

{
  "searchKeyword": "",
  "states": ["MA"],
  "nteeCategoryId": 4,
  "cCodeSubsection": 3,
  "minTotalRevenueUsd": 1000000,
  "maxItems": 10
}

---

Output Fields

One row per organization:

Field	Type	Description
ein	string	IRS Employer Identification Number (9 digits).
organizationName	string	Legal organization name.
nteeCode	string / null	BMF NTEE code.
subsectionCode	string / null	IRC 501(c) subsection code.
city	string / null	City from the filing or BMF record.
state	string / null	Two-letter state abbreviation.
zipCode	string / null	ZIP code.
latestTaxPeriod	integer / null	Most recent tax period with data, YYYYMM.
totalRevenueUsd	number / null	Total revenue in USD.
totalExpensesUsd	number / null	Total expenses in USD (not published in the BMF, so null on BMF-only rows).
totalAssetsUsd	number / null	Total assets, end of year, in USD.
grantsAndContributionsPaidUsd	number / null	Grants and contributions paid, where the source form reports it (Form 990 and 990-PF; the 990-EZ and the BMF do not publish grants paid, so those rows carry null here).
executiveCompensationTotalUsd	number / null	Aggregate compensation of current officers, directors, and trustees. Aggregate only.
outsideIndependentContractorFeesUsd	number / null	Outside contractor and professional service fees (Form 990 Part IX lines 11a and 11d to 11g), summed.
accountingAndLegalFeesUsd	number / null	Accounting fees plus legal fees (Form 990 Part IX lines 11b and 11c), summed.
pdf990FilingUrl	string / null	Official IRS PDF of the filing on apps.irs.gov, resolved per delivered row. Null when the IRS TEOS route returns no matching filing.
summaryFinancials	boolean	true when financials come only from the BMF or SOI summary extracts.

Sample Output Row

{
  "ein": "046103770",
  "organizationName": "EXAMPLE HEALTH FOUNDATION INC",
  "nteeCode": "E21",
  "subsectionCode": "3",
  "city": "Boston",
  "state": "MA",
  "zipCode": "02118",
  "latestTaxPeriod": 202412,
  "totalRevenueUsd": 12500000.0,
  "totalExpensesUsd": 11200000.0,
  "totalAssetsUsd": 85000000.0,
  "grantsAndContributionsPaidUsd": 6500000.0,
  "executiveCompensationTotalUsd": 450000.0,
  "outsideIndependentContractorFeesUsd": 120000.0,
  "accountingAndLegalFeesUsd": 45000.0,
  "pdf990FilingUrl": null,
  "summaryFinancials": false
}

The sample row above is synthetic and illustrates the schema only.

---

How Pricing Works

Pay per result. You only pay for rows returned. Set maxTotalChargeUsd in your run options to cap a run's cost; a run stopped by that cap reports PARTIAL with the count delivered.

---

Data Sources & Terms

All records come from IRS public-domain bulk data at irs.gov and apps.irs.gov: the EO BMF extracts (monthly), the SOI annual extracts (annual), and the Form 990 e-file XML dataset (posted monthly by filing year). No third-party nonprofit database or API is used. This tool is independently developed and is not affiliated with or endorsed by the Internal Revenue Service.

Limits & Troubleshooting

• Run time and size: the actor downloads the BMF files for the requested states (about 1 to 20 MB each), the SOI extracts (about 80 MB total), the two newest 990 index files (about 17 MB each), and only the XML batch files (about 70 to 105 MB each) that contain filings for organizations that pass your filters, newest filing year first, stopping once every delivered organization has parsed XML data or the batches run out. Wide filter sets with a large maxItems can take tens of minutes and several GB of downloads.
• Zero matches: a healthy source with no matching organizations ends as Complete: 0 organizations matched your filters, with the scanned counts stated. Broaden the keyword, lower minTotalRevenueUsd, or add states.
• PARTIAL runs: a truncated or missing file in the resolved set, a corrupt XML filing, or unrecognized amount formats produce a PARTIAL status naming the file or the count. A PARTIAL caused only by your maxItems or charge cap carries no Issues line; a PARTIAL with a source cause does.
• Stale data: BMF posting dates are monthly, SOI extracts are annual, and 990 XML batches are posted monthly; latestTaxPeriod on each row tells you exactly how current that organization is.
• 990-EZ and BMF field gaps: grants paid and total expenses are not published for every form type; affected fields are null on those rows rather than estimated.

Changelog

• v0.1.3 (2026-11-02): Fix round from the Red Team final GO review of v0.1.2. Professional fundraising fees reported under the current-schema Part IX line 11e group element FeesForServicesProfFundraising are now parsed into outsideIndependentContractorFeesUsd (that tag was missing from the contractor fees group map, so the field was understated, and sometimes null, on current-schema filings that report the fee only under that spelling). The TEOS PDF lookup now prefers a Form 990 item when TEOS lists both a 990 and a 990T for the same tax period, instead of returning whichever period match is listed first; when no item matches the tax period the URL is still null. TEST_NOTES.md now documents verification for this round, and the shipped fixture suite (tests/test_fixtures.py) was added with fixtures proving both fixes.
• v0.1.2 (2026-11-02): Fix round from Red Team review of v0.1.1. Executive compensation is no longer double counted on filings that use the nested Part VII schema (wrapper plus per-officer groups); each officer compensation element is counted exactly once, and the single-tag aggregate is still preferred when present. The minimum revenue filter is no longer applied at the BMF stage: it is checked only against the revenue of the filing each row is taken from, after enrichment, and those drops are counted in the status. Validation-skipped rows now end the run as PARTIAL naming the skip count, so Complete means all matched rows were emitted. The PDF filing URL is null when no TEOS item matches the row tax period (the first-item fallback is removed). Added default run options with a 50 USD charge cap and set the source build tag to audit. Status counts inside one message now use one matched count consistently, and a truncated PARTIAL reason list states the total number of reasons.
• v0.1.1 (2026-11-01): Rebuilt on official IRS bulk data only (BMF, SOI extracts, 990 e-file XML resolved from IRS pages at run start). The v0.1 build's third-party nonprofit API integration was withdrawn because that source's terms bar paid resale use. Also fixed in this round: accounting and legal fees are now summed instead of taking one or the other; organization identity is read from the ReturnHeader Filer block only, never from the preparer firm block; Part IX fee groups and the current-year grants tag are parsed in the current XML schema's group form; zero matches now end Complete instead of failing; the missing .actor schemas were restored; retries follow the 6-try standard with Retry-After honored.
• v0.1 (2026-11-01): Initial release. Withdrawn the same day; see v0.1.1.