# Nonprofit IRS 990 Monitor (`junipr/nonprofit-irs-990-monitor`) Actor

Monitor nonprofit IRS 990 public filings, filing dates, key fields, and change signals.

- **URL**: https://apify.com/junipr/nonprofit-irs-990-monitor.md
- **Developed by:** [junipr](https://apify.com/junipr) (community)
- **Categories:** Automation, News
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $6.50 / 1,000 record checkeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Nonprofit IRS 990 Monitor

### Store Positioning

**Store title:** Nonprofit IRS 990 Monitor

**Short description:** Monitor nonprofit IRS 990 public filings, filing dates, key fields, and change signals.

**SEO title:** Nonprofit IRS 990 Monitor — official public data extraction and monitoring

**SEO description:** Monitor nonprofit IRS 990 public filings, filing dates, key fields, and change signals. Use it to normalize official public data into clean Apify datasets with source-specific fields and report artifacts.

**Categories:** AUTOMATION, NEWS

**Keywords:** nonprofit, irs, 990, monitor, change monitor, public data, official/public-data actor

### Fixed-Inclusive PPE Pricing

This actor uses pay-per-event pricing. Event prices include Apify platform usage; users are not expected to pay a separate platform-usage pass-through charge for the configured pricing model.

- Tier: D1 — Official/public-data actor
- Primary event: `record-checked` at $0.00908 base
- Default max charge: $15.00
- Store discounts: FREE/BRONZE base, SILVER discounted, GOLD deepest approved discount

Event set:

- `actor-start`: base $0.02000, GOLD $0.01760. Nonprofit Irs 990 Monitor: charged when actor start is completed. The price includes Apify platform usage; no separate usage pass-through is intended.
- `record-checked`: base $0.00908, GOLD $0.00799. Nonprofit Irs 990 Monitor: charged when record checked is completed. The price includes Apify platform usage; no separate usage pass-through is intended.
- `event-detected`: base $0.01300, GOLD $0.01140. Nonprofit Irs 990 Monitor: charged when event detected is completed. The price includes Apify platform usage; no separate usage pass-through is intended.
- `report-generated`: base $0.05000, GOLD $0.04400. Nonprofit Irs 990 Monitor: charged when report generated is completed. The price includes Apify platform usage; no separate usage pass-through is intended.

### Public Task Concepts

- Compare IRS 990 financial totals for one EIN
- Monitor one nonprofit EIN from IRS 990 data
- Build an IRS 990 financial change digest
- Prioritize IRS 990 revenue, expense, and asset changes
- Export normalized IRS 990 filing rows

Normalize public IRS Form 990 filing data and identify changes for known nonprofit EINs.

### What This Actor Does

Nonprofit IRS 990 Monitor parses supplied IRS Tax Exempt Organization Search index CSV, individual filing XML, JSON rows, or structured records. It normalizes EIN, organization name, tax year, filing type, filing date, object ID, tax period, revenue, expenses, assets, and source-file evidence.

Filters can match exact normalized EINs or organization-name fragments. When a row also includes previous revenue, expense, or asset values, the actor emits explicit financial change signals and an `event-detected` billing event before output.

### What This Actor Does Not Do

- It does not access private tax records or nonpublic IRS systems.
- It does not provide tax, legal, accounting, investment, or compliance advice.
- It does not infer prior-period values when they are not supplied.
- It does not unpack IRS bulk ZIP archives; provide extracted CSV/XML content, structured rows, or a direct text response.
- It does not claim that a financial change is suspicious or improper.

### Best Use Cases

- normalize IRS 990 index or filing records for a known EIN
- compare supplied current and previous financial totals
- monitor filing identity, tax year, and submission date
- export source-linked nonprofit filing rows
- route material changes for analyst review

### Input Fields

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `targets` | array | one built-in filing record | Each target can contain `records`, `csvText`, XML/JSON `text`, or a direct text source URL. |
| `urls` | array | `[]` | Direct IRS text sources to fetch when `fetchUrls` is enabled. |
| `eins` | array | example EIN | Exact nine-digit EIN filters; punctuation is normalized. |
| `organizationNames` | array | `[]` | Case-insensitive organization-name fragments. |
| `fetchUrls` | boolean | `false` | Fetch and parse direct CSV, XML, or JSON text sources. |
| `fetchTimeoutMs` | integer | `12000` | Per-request timeout, capped at 30 seconds. |
| `maxTargets` | integer | `1` | Source-target cap. |
| `maxItems` | integer | `5` | Filing-row cap within normalized input. |
| `includeReport` | boolean | `true` | Writes JSON and Markdown report artifacts. |

### Example Input

```json
{
  "targets": [
    {
      "sourceId": "example-990",
      "sourceUrl": "https://apps.irs.gov/pub/epostcard/990/xml/2025/",
      "records": [
        {
          "EIN": "12-3456789",
          "TAXPAYER_NAME": "Example Youth Foundation",
          "TAX_YEAR": 2025,
          "RETURN_TYPE": "Form 990",
          "SUB_DATE": "2026-06-28",
          "OBJECT_ID": "202612345678900001",
          "TOTREVENUE": 1480000,
          "TOTFUNCEEXPNS": 1010000,
          "TOTASSETSEND": 2100000,
          "previousRevenue": 1200000,
          "previousExpenses": 900000,
          "previousAssets": 1850000
        }
      ]
    }
  ],
  "eins": ["123456789"],
  "maxTargets": 1,
  "maxItems": 5,
  "includeReport": true
}
```

### Output Fields

Each row contains `ein`, `organizationName`, `taxYear`, `filingType`, `filingDate`, `revenue`, `expenses`, `assets`, `objectId`, `taxPeriod`, `matchedBy`, `changeSignals`, `sourceFileUrl`, `sourceError`, and `eventDetected`, plus status, score, recommendation, timestamp, source identity, and pricing metadata.

An unmatched EIN or organization name produces an explicit no-match row. A fetch or parse failure produces a blocked row with `sourceError`; the actor does not substitute synthetic filing data.

### Supported Source Shapes

- IRS TEOS index CSV or pipe-delimited text with quoted-cell support
- individual Form 990 XML with or without namespace prefixes
- JSON arrays or objects containing `results`, `filings`, or `records`
- structured records using IRS headers or normalized field names

### Cost Control

- Start with one known EIN and one filing source.
- Pre-extract only the needed rows from bulk IRS files.
- Keep `maxTargets` and `maxItems` small for scheduled checks.
- Disable report artifacts when only dataset rows are needed.

### Public Task Examples

- compare IRS 990 financial totals for one EIN
- monitor one nonprofit EIN from public filing data
- build a financial change digest
- prioritize revenue, expense, and asset deltas
- export normalized filing rows with source evidence

### FAQ

#### Does this actor identify fraud or noncompliance?

No. It normalizes public filing evidence and computes supplied-period deltas. Qualified reviewers remain responsible for interpretation.

#### Why might a filing not match?

Verify the nine-digit EIN, organization spelling, tax year, and source file. IRS bulk datasets are released on schedules and may not contain a newly submitted filing immediately.

### Limitations

IRS field availability varies by filing type and tax year. XML structures outside the supported identity and financial tags may require preprocessing. Change signals require explicit previous values and should be checked against the source filing.

### Source And Safety Notes

The IRS distributes Form 990 series data through Tax Exempt Organization Search bulk indexes and filing XML. Use only public IRS data or records you are authorized to process; do not submit credentials or private taxpayer data.

### Changelog

- 2026-07-10: Added IRS CSV/XML/JSON parsing, EIN and name filtering, filing normalization, financial change signals, charge-limit regression coverage, and honest source-error rows.

# Actor input Schema

## `targets` (type: `array`):

IRS filing sources. Each target can contain structured records, TEOS index CSV text, filing XML or JSON text, and an optional source URL.

## `records` (type: `array`):

Optional structured rows for one target.

## `csvText` (type: `string`):

Optional CSV text for one target.

## `urls` (type: `array`):

Bounded official IRS TEOS index CSV or filing XML URLs to fetch and parse.

## `eins` (type: `array`):

Optional nine-digit nonprofit EINs to retain from parsed IRS rows.

## `organizationNames` (type: `array`):

Optional official organization-name fragments to retain.

## `fetchUrls` (type: `boolean`):

Fetch source URLs over HTTP. Default is false to avoid cloud usage and network variability.

## `fetchTimeoutMs` (type: `integer`):

Timeout for each bounded IRS public-data request.

## `maxItems` (type: `integer`):

Maximum normalized filing rows to emit across each source target.

## `includeReport` (type: `boolean`):

Write JSON summary, JSON results, and Markdown report artifacts to the key-value store.

## `maxTargets` (type: `integer`):

Maximum nonprofit filing targets to process.

## `maxTextBytes` (type: `integer`):

Maximum text bytes to analyze per target.

## `dryRun` (type: `boolean`):

Validate input and write a dry-run summary without PPE charges or dataset output.

## `debug` (type: `boolean`):

Enable debug logs.

## Actor input object example

```json
{
  "targets": [],
  "records": [],
  "csvText": "",
  "urls": [],
  "eins": [],
  "organizationNames": [],
  "fetchUrls": false,
  "fetchTimeoutMs": 10000,
  "maxItems": 5,
  "includeReport": true,
  "maxTargets": 1,
  "maxTextBytes": 500000,
  "dryRun": false,
  "debug": false
}
```

# Actor output Schema

## `results` (type: `string`):

Structured nonprofit filing rows.

## `summary` (type: `string`):

Run summary JSON when includeReport is enabled.

## `markdownReport` (type: `string`):

Markdown report when includeReport is enabled.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("junipr/nonprofit-irs-990-monitor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("junipr/nonprofit-irs-990-monitor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call junipr/nonprofit-irs-990-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=junipr/nonprofit-irs-990-monitor",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/sgPASGEGdGCFSHrbB/builds/M47s7LdYECDkSfzUo/openapi.json