# 501api — Full API Reference (for AI agents)

A read-only JSON API over public-domain U.S. IRS data on ~1.97 million
501(c) tax-exempt organizations. This document is self-contained: it is
everything you need to build a working client. The equivalent
machine-readable OpenAPI 3 document is at https://api.501api.org/v1/openapi.

All data is derived from public-domain U.S. IRS sources and is provided
AS IS, without warranty of accuracy or completeness. Verify against official
IRS filings before relying on it. (This notice is echoed in every
`meta.warranty`.)

## Base URL
```
https://api.501api.org/v1
```
Both https://501api.org (the demo site) and https://api.501api.org (the API host)
serve the same application; use the API host for programmatic access.

## Authentication & rate limits
- No authentication is required. The API is anonymously readable.
- Anonymous: 120 requests / minute, per client IP.
- Optional `Authorization: Bearer <key>` raises the limit to 600/min per key
  (beta; request one at https://501api.org/#get-a-key).
- Over the limit returns HTTP 429 (see Errors).

### Browser (CORS) access
Direct calls from a web page are allowed only from approved origins (an
allowlist; ask to have yours added). Approved origins get
`Access-Control-Allow-Origin` echoed back; others are blocked by the browser.
Server-side clients are unaffected. Tip for typeahead: debounce input and use
`/orgs/suggest` to stay well under the rate limit.

## Response envelope
Every response is `{ "data": ..., "meta": {...} }`.
- `meta.api_version` — always "v1".
- `meta.warranty` — the AS-IS notice (always present).
- `meta.pagination` — present on list endpoints:
  `{ "page", "per_page", "total", "total_pages", "sort" }`.

## Data model notes
- `ein`: 9-digit string, leading zeros significant (e.g. "530196605").
- Monetary fields: whole U.S. dollars as integers, or `null` if the source
  doesn't report that line.
- `current_financials.source`: one of `"efile"`, `"soi"`, `"bmf"`. The API
  reconciles to the single best current figure per org with precedence
  **efile > soi > bmf**, latest tax period — so a figure is always labeled
  with where it came from.
- `subsection_code`: the 501(c) subsection as a 2-char string — `"03"` =
  501(c)(3) charities, `"04"` = social welfare, etc. Use `is_501c3=true` to
  scope to charities across subsections.
- `ntee_code`: National Taxonomy of Exempt Entities code; the `ntee` search
  filter matches by **prefix** (e.g. `A` = arts, `A23` = a specific leaf).
- `tax_period`: 6-char `YYYYMM` string of the fiscal-year end.

## Endpoints

### GET /orgs — search
Full-text search over name/dba/city plus structured filters, paginated.
A 9-digit `q` is treated as an exact EIN match as well.

Query parameters (all optional):
- `q` — full-text query (name / dba / city), or a 9-digit EIN.
- `state` — 2-letter USPS state (exact, e.g. `CA`).
- `ntee` — NTEE code prefix.
- `subsection` — 501(c) subsection code (exact, e.g. `03`).
- `is_501c3` — `true` / `false`.
- `revenue_min`, `revenue_max` — bounds on reconciled current revenue (whole dollars).
- `sort` — `revenue` | `assets` | `name`. Default: `revenue` when there is no
  `q`, otherwise `name`.
- `page` — 1-based (default 1). `per_page` — default 25, max 100.

Example:
```
curl "https://api.501api.org/v1/orgs?q=animals&per_page=1"
```
```json
{
  "data": [
    {
      "ein": "883804848",
      "name": "2ND CHANCE ANIMALS OF BP",
      "city": "HAUGHTON",
      "state": "LA",
      "is_501c3": true,
      "subsection_code": "03",
      "subsection_label": "Charitable, religious, educational, scientific, etc. — 501(c)(3)",
      "ntee_code": "D20",
      "ntee_label": null,
      "current_financials": {
        "source": "bmf",
        "tax_period": "202512",
        "total_revenue": 0,
        "total_expenses": null,
        "total_assets_eoy": 0,
        "total_liabilities_eoy": null,
        "net_assets_eoy": null
      }
    }
  ],
  "meta": {
    "api_version": "v1",
    "warranty": "Data is derived from public-domain U.S. IRS sources ... Verify against official IRS filings before relying on it.",
    "pagination": { "page": 1, "per_page": 1, "total": 1163, "total_pages": 1163, "sort": "name" }
  }
}
```

### GET /orgs/suggest — typeahead
Up to 8 `{ein, name}` prefix matches for a search box. Param: `q` (required).
Returns `[]` for a blank query.
```
curl "https://api.501api.org/v1/orgs/suggest?q=red+cro"
```

### GET /orgs/{ein} — profile
Full profile: identity, `classification` (subsection + labels, is_501c3),
`address`, `status` (deductibility, revocation), reconciled
`current_financials` (source-tagged), and `counts` of related records
(efile_filings, soi_filings, people, grants). 404 if the EIN is unknown.
```
curl "https://api.501api.org/v1/orgs/530196605"
```

### GET /orgs/{ein}/financials — financial history
Unified SOI + e-file time series, each row source-tagged, newest first.
Includes the paper-filed flag on SOI rows.

### GET /orgs/{ein}/filings — filings
`{ "efile": [...parsed returns...], "soi_years": [...distinct SOI years...] }`.

### GET /orgs/{ein}/people — officers
Part VII people (officers / directors / key employees). Public information.
(Schedule B donor data is never collected or served, by design.)

### GET /orgs/{ein}/grants — grants
Schedule I grants the organization made.

### GET /stats — corpus aggregates
Totals and the distribution of which source won each org's current figure.
```
curl "https://api.501api.org/v1/stats"
```
```json
{
  "data": {
    "total_orgs": 1974830,
    "c3_orgs": 1647596,
    "revoked_orgs": 159938,
    "by_source": { "efile": 25, "soi": 508014, "bmf": 1044894 }
  },
  "meta": { "api_version": "v1", "warranty": "..." }
}
```

## Errors
Standard HTTP status codes with a consistent body:
```json
{ "errors": { "detail": "Not Found" } }
```
- 404 — unknown EIN.
- 429 — `{ "errors": { "detail": "Rate limit exceeded. Try again later." } }`.

## See also
- OpenAPI 3 spec (JSON): https://api.501api.org/v1/openapi
- Interactive Swagger UI (browser): https://api.501api.org/v1/docs
- Human reference: https://501api.org/docs