# 501api — Public U.S. nonprofit (501(c)) data API

> Read-only JSON API over public-domain U.S. IRS data on ~1.97 million
> tax-exempt organizations: the EO BMF registry, the SOI financial extract,
> and a parsed e-file Form 990 slice. Every financial figure is tagged with
> the source it came from (precedence: efile > soi > bmf). Free and
> anonymous to try — 120 requests/min per IP, no key required. All data is
> provided AS IS, without warranty of accuracy — verify against official IRS
> filings before relying on it.

- Base URL: https://api.501api.org/v1
- Site: https://501api.org
- Full Markdown reference: https://api.501api.org/llms-full.txt
- OpenAPI 3 spec (for codegen / clients): https://api.501api.org/v1/openapi

## Conventions
- Every response is JSON `{ "data": ..., "meta": {...} }`. `meta` always has
  `api_version` and `warranty`; list endpoints add `meta.pagination`
  (`page, per_page, total, total_pages, sort`).
- EINs are 9-digit strings; leading zeros are significant (e.g. "530196605").
- Monetary amounts are whole U.S. dollars (integers), or null when the
  source does not report that line.
- Auth: none required (anonymous, 120 req/min per IP). An optional
  `Authorization: Bearer <key>` raises the limit to 600/min (beta — request
  a key at https://501api.org/#get-a-key).
- Errors: standard HTTP status + `{ "errors": { "detail": "..." } }`
  (404 unknown EIN, 429 rate limited).

## Quickstart
```
curl "https://api.501api.org/v1/orgs?q=red+cross"
curl "https://api.501api.org/v1/orgs/530196605"
curl "https://api.501api.org/v1/orgs?state=CA&is_501c3=true&sort=revenue"
```

## Endpoints
- `GET /v1/orgs` — Search organizations (full-text + filters, paginated). — params: q, state, ntee, subsection, is_501c3, revenue_min, revenue_max, sort, page, per_page
- `GET /v1/orgs/suggest` — Typeahead: up to 8 {ein, name} prefix matches. — params: q
- `GET /v1/orgs/{ein}` — Full org profile (identity, classification, address, reconciled current financials, related-record counts).
- `GET /v1/orgs/{ein}/financials` — Financial time series (SOI + e-file rows), each source-tagged, newest first.
- `GET /v1/orgs/{ein}/filings` — Filings: parsed e-file returns + the distinct SOI years.
- `GET /v1/orgs/{ein}/people` — Part VII people (officers / directors / key employees — public).
- `GET /v1/orgs/{ein}/grants` — Schedule I grants the org made.
- `GET /v1/stats` — Corpus aggregates: totals + which source won each org's current figure.

## More docs
- Full reference (Markdown): https://api.501api.org/llms-full.txt
- OpenAPI 3 spec (JSON): https://api.501api.org/v1/openapi
- Human reference: https://501api.org/docs
- Interactive (Swagger UI, browser): https://api.501api.org/v1/docs