IRS Private Foundation 990-PF Filings Export

Export financial and grant fields from official IRS private foundation 990-PF filings. Select one IRS XML publication year and ZIP batch; optionally restrict output to nine-digit EINs. Each dataset row is one filing with assets, net investment income, grants paid, selected grant details, officer details, and the source archive. The archive is downloaded once per run and XML is parsed locally.

Who is it for?

• Foundation researchers comparing filing-level asset and grant figures across repeated exports.
• Grantmaking analysts inspecting disclosed grant purposes and amounts for foundations in a selected IRS archive batch.
• Data engineers loading IRS filing fields into a spreadsheet or warehouse for longitudinal analysis.

This is a filing export, not an organization identity/status search. For IRS tax-exempt organization master-file identification and status, use IRS Tax Exempt Organization Search.

Why use the IRS XML archives?

The source is the IRS's published XML, rather than a third-party summary. Every row carries a stable IRS object ID and an archive URL for provenance. The dataset is structured JSON, so you can join filings by EIN and tax period, import the rows into a spreadsheet, and compare values over time. The IRS publication year can differ from the filing's tax period; both are recorded.

What data is exported?

Field	Meaning
objectId, ein	IRS filing object ID and foundation EIN.
foundationName, taxPeriod, publicationYear	Filing header name, tax period end, archive publication year.
totalAssetsEndOfYear, netInvestmentIncome, grantsPaid	Monetary fields in USD when present in XML; otherwise null.
grants[]	Available grant purpose, recipient and amount. Recipient may be null.
officers[]	Available officer name, title and compensation.
sourceArchive, sourceXml	Official ZIP URL and member identifier (#..._public.xml is an archive-member reference, not an independently downloadable URL).

The Actor does not export every field of Form 990-PF, all attached schedules, or an Excel workbook. The dataset is available through Apify as JSON/CSV/Excel; nested arrays may require flattening in a spreadsheet workflow.

Get started

1. Find an IRS XML batch archive for the year you want to analyze.
2. Enter the archive's three-character batch code (for example, 01A) and publication year.
3. Optionally enter up to 100 EINs (nine digits without hyphens) to filter within that batch.
4. Set maxItems between 1 and 100; run the Actor and inspect the default dataset. Repeat for another batch or publication year when needed.

A selected batch is downloaded in full even for maxItems: 1; choosing an EIN absent from that batch yields no rows. This Actor does not find which batch contains an arbitrary EIN. The IRS CSV index does not map EINs to ZIP batches.

Choosing a batch for repeatable comparisons

Archive names follow YEAR_TEOS_XML_BATCH.zip, for example 2023_TEOS_XML_01A.zip. The Actor constructs the official IRS URL from the two input fields; do not supply a third-party download URL. To compare a foundation across releases, export the relevant known batches separately, then key rows by objectId and review taxPeriod. Re-running a fixed batch may reflect an IRS replacement of the underlying archive, so store a snapshot if reproducibility matters.

Input

{"publicationYear":2023,"batch":"01A","eins":["363781852"],"maxItems":1}

Parameter	Default	Notes
publicationYear	2023	IRS archive publication year, 2017–2025; not tax year.
batch	01A	Exact two-digit, one-uppercase-letter ZIP code from the selected year. Nonexistent archives fail with an HTTP error.
eins	omitted	Up to 100 nine-digit strings; omit to export from the selected archive without EIN filtering.
maxItems	5	Stop after 1–100 qualifying 990-PF filing rows. Multiple filings can share an EIN.

Output example

A real filing from the IRS 2023 01A XML batch (values are illustrative of that filing, not a guarantee of current archive availability):

{
  "objectId": "202300109349100000",
  "ein": "363781852",
  "publicationYear": 2023,
  "taxPeriod": "2022-06-30",
  "foundationName": "JOSEPH C BELDEN FOUNDATION",
  "totalAssetsEndOfYear": 1214045,
  "netInvestmentIncome": 102063,
  "grantsPaid": 46162,
  "grants": [{"recipient": null, "purpose": "COLLEGE TUITION AND BOOKS", "amount": 46162}],
  "officers": [{"name": "SEE SCHEDULE ATTACHED", "title": "SEE SCHEDULE ATTACHED", "compensation": 0}],
  "sourceArchive": "https://apps.irs.gov/pub/epostcard/990/xml/2023/2023_TEOS_XML_01A.zip",
  "sourceXml": "https://apps.irs.gov/pub/epostcard/990/xml/2023/2023_TEOS_XML_01A.zip#202300109349100000_public.xml"
}

The grants and officers arrays are embedded in the filing row; there is no extra fee for individual grant or officer entries.

Missing XML fields are represented as null or empty arrays, not guessed values.

How much does it cost to export foundation filings?

The Actor charges $0.005 for one start event per run and one item event for each exported filing. The BRONZE item price is $0.00512; FREE is $0.005888, SILVER $0.0039936, and GOLD/PLATINUM/DIAMOND $0.003072 each. At BRONZE, one filing costs $0.01012, five cost $0.03060, and 25 cost $0.133 (start plus items); these are billed-event estimates, not a promise about refunds, fraud, disputes, taxes, corrections or chargebacks. An EIN with no match still incurs the start charge because the archive is downloaded. The discount tier is determined by your qualifying monthly Apify Store spend, not this run's item count or your subscription plan; check the live Pricing tab before a large run. Limiting output does not avoid the ZIP download. No separate event is charged for individual grants or officers.

Spreadsheet and integration workflows

• Download the default dataset as CSV or Excel for a one-time foundation-filing review; flatten grants[] separately when you need one row per grant.
• Schedule a run for the same known batch as a reproducible export, or run a series of known batches and deduplicate by objectId in your own warehouse.
• Join rows by EIN and taxPeriod for cross-year work. A publication-year change alone does not indicate the foundation's fiscal year changed.

This Actor does not monitor IRS updates or discover new batches automatically. To compare revisions, store the prior export outside the Actor and compare object IDs in your pipeline.

API usage

Use your own Apify token; do not paste it into public tasks. For asynchronous runs:

curl -X POST 'https://api.apify.com/v2/acts/automation-lab~irs-private-foundation-990pf/runs?token=YOUR_APIFY_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"publicationYear":2023,"batch":"01A","eins":["363781852"],"maxItems":1}'

With JavaScript:

import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/irs-private-foundation-990pf').call({
  publicationYear: 2023, batch: '01A', eins: ['363781852'], maxItems: 1,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

With Python:

from apify_client import ApifyClient
import os
client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/irs-private-foundation-990pf').call(
    run_input={'publicationYear': 2023, 'batch': '01A', 'eins': ['363781852'], 'maxItems': 1})
for filing in client.dataset(run['defaultDatasetId']).iterate_items():
    print(filing['ein'], filing['grantsPaid'])

MCP

Connect the Actor as an Apify tool in Claude Code:

claude mcp add --transport http apify \
  'https://mcp.apify.com?tools=automation-lab/irs-private-foundation-990pf'

For Claude Desktop, Cursor, and VS Code with an HTTP MCP server configuration:

{"mcpServers":{"apify":{"type":"http","url":"https://mcp.apify.com?tools=automation-lab/irs-private-foundation-990pf"}}}

Example prompts: “Export one 990-PF filing from IRS 2023 ZIP batch 01A and show its assets and grants.” “Export EIN 452590105 from the same archive and list its grant purposes.” Inspect the returned dataset. MCP authentication and tool availability depend on your Apify account/client setup.

Limits and reliability

An IRS batch may be over 100 MB. Allow sufficient disk and runtime, even for a one-row output. Requests use bounded retries on network, 429 and 5xx failures; a missing ZIP (404) or malformed input fails rather than silently returning an empty result. The archive is deleted from temporary storage at the end of a run. Apify retains input, output dataset and run logs under your account's storage settings; delete runs/datasets according to your retention policy. EIN input is sent only to the Apify runtime and used locally to filter the downloaded IRS archive; no AI model or paid third-party API receives it. The Actor stops after the configured number of accepted filing rows; ordering follows the ZIP contents and is not a ranked search.

Only selected, recognizable XML element names are normalized. IRS form revisions or supplemental schedules may contain data not extracted here. IRS published data can be corrected or republished. Validate critical figures against the original return and source publication before making financial or eligibility decisions.

Legality and responsible use

The source is public IRS tax-exempt organization filing XML. A filing may contain names and other personal data. Use it for legitimate research, respect applicable privacy obligations and IRS publication terms, and do not infer grant eligibility or legal compliance from a single data point. This is not legal or tax advice.

Troubleshooting and FAQ

Why did I get zero rows? Check whether the selected batch actually contains the EIN and whether its return type is 990PF. The Actor does not search other batches. Try omitting eins to inspect the first matching 990-PF rows in that batch.

Why did a run fail with HTTP 404? Verify the exact published archive year and batch code in the IRS directory. Not every syntactically valid code exists for every year.

Why is the tax period older than the publication year? IRS publication year is when that ZIP was released, not the filing period. Use taxPeriod for fiscal-year analysis.

Are grant recipients always populated? No. A filing may use different IRS XML structures or attachments; missing recipient fields remain null. The totals are not computed by summing parsed grant entries.

Where do I report a problem? Open an issue on the Actor's Apify Store page and include the publication year, batch code, and run ID; avoid sharing sensitive input in a public issue.

Related Actor

IRS Tax Exempt Organization Search is for master-file organization discovery/status. Use this Actor instead when you already know a ZIP batch and need 990-PF filing-level financials and disclosed grants.