# Changelog of IRS 990 Nonprofit Officers and Compensation (`datagrit/irs-990-officer-compensation`) Actor

- **URL**: https://apify.com/datagrit/irs-990-officer-compensation/changelog.md
- **Full Actor documentation**: https://apify.com/datagrit/irs-990-officer-compensation.md

## Changelog

### 0.3

- Returns e-filed in 2024 are all readable again. The IRS 2024 index names three archives in lowercase (2024\_TEOS\_XML\_04a, 05a, 06a, about a third of that year's returns), while the IRS server only has them in uppercase; archive names are now requested in uppercase, with the index spelling as fallback. Example: EIN 26-1543883 with filing year 2024.
- Form 990-EZ: the five highest-paid employees (Part VI line 50, role `highest-compensated-employee`) and the five highest-paid independent contractors (line 51) are now rows, as on Form 990-PF. 0.2 stated wrongly that Form 990-EZ has no such table; most small organizations enter "None" there, so the rows appear only when the return lists someone.
- README: pricing per Apify plan, FAQ on how a name search matches.

### 0.2

- Form 990-PF: the five highest-paid employees (Part VII-A line 2, role `highest-compensated-employee`) and the five highest-paid contractors (Part VII-B) are now rows. The Gates Foundation return (tax year 2024, e-filed 2025) gives 25 officers plus 5 employees paid 1.19 to 2.4 M USD that 0.1 left out.
- Filing years before 2024 are rejected with a clear message: the IRS indexes for 2020-2023 have no XML\_BATCH\_ID column, so the archive of a return cannot be located. `filingYears` no longer has a prefill; the default (current and previous year) is computed in code.
- IRS requests: `Retry-After` is honoured for 429/5xx (index and archives), requests are paced (at most about 6 per second), a Range request answered with 200 is aborted before the body is read, the archive directory cache is LRU and filings are read grouped by archive, so a large name search no longer reloads 3.4 MB directories.
- No free results per run (pricing policy of 2026-09-30); the start fee replaces them. Cost now includes transfer (about 48 MB per run: both indexes, one archive directory, the filing): 0.4 USD per 1000 rows at the prefill run, price 5 USD per 1000.
- Status message says why a query returned nothing (no return in the index for the filing years, already listed under an earlier entry, filtered out). Empty EIN is `null`.
- Schedule J field descriptions state they are the filing organization's own amounts. Input descriptions corrected (index size 14-28 MB).
- Tests: 990-PF with line 2 and contractors (cut from the Gates return), Deflate64 stream with length symbol 285 and distance symbol 30, index header without XML\_BATCH\_ID, `Retry-After` parsing.

### 0.1

- Initial release: one row per officer, director, trustee, key employee and highest-paid employee from IRS e-filed Form 990, 990-EZ and 990-PF returns, looked up by EIN or organization name.
- Reads the IRS TEOS e-file index and the XML inside the yearly archives with HTTP range requests; amended returns supersede originals.
- Filters: filing years, tax years, form types, roles, minimum total compensation, independent contractors, latest tax year only.

Manual tests before release:

- Typical: EIN 53-0196605 (American Red Cross), default settings: 26 person rows in 33 s, base salary, bonus and deferred pay filled from Schedule J.
- Edge case: EIN 04-2702867 with form type 990EZ only: 1 return read, 8 rows, roles reported as officer-director-or-key-employee with null role flags.
- No results: an organization name that does not exist returns one free status row with `found: false` and 0 filings read.

Manual tests before 0.2 release (live, IRS sources):

- Typical: EIN 53-0196605, default settings (see the measured run in PRICING.json).
- Edge case: filing years \[2022] is rejected with the 2024 minimum message; Gates Foundation (990-PF) returns 25 officers, 5 highest-paid employees and, with contractors on, 5 contractors.
- No results: an organization name that does not exist returns one status row and the message names the filing years searched.