# IRS API

> IRS workflow and API: charity status and tax form. Returns organizations, ein, city and state as JSON.

IRS data from irs.gov: charity status and tax form.

- Page: https://fous.com/workflows/irs
- Handle: `@irs`
- Category: [Government](https://fous.com/workflows/category/government)
- Source website: https://irs.gov
- Last verified: Sep 29, 2026
- Fous is not affiliated with IRS.

## Methods

### Check charity status

Operation `check_charity_status`, version 1. 1 credit per call.

Check an organization’s IRS listing for donation deductibility, automatic revocation, and recent Form 990 filings. Absence from Publication 78 alone does not prove donations are nondeductible. Form 990-N notices have no separate filing link; IRS detail pages may require selecting the organization from search first.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `city` | string | no |  | City, for example Washington. |
| `state` | string | no | `"Virginia"` | State name or two-letter code, for example District of Columbia or DC. |
| `max_results` | integer | no | `5` | Maximum number of organizations, for example 10. |
| `organization` | string | yes | `"53-0196605"` | Organization name or EIN, for example American Red Cross or 53-0196605. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "organization"
  ],
  "properties": {
    "city": {
      "type": "string",
      "description": "City, for example Washington."
    },
    "state": {
      "type": "string",
      "description": "State name or two-letter code, for example District of Columbia or DC.",
      "examples": [
        "Virginia"
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 10,
      "maximum": 50,
      "minimum": 1,
      "description": "Maximum number of organizations, for example 10.",
      "x-fous-developer": true,
      "examples": [
        5
      ]
    },
    "organization": {
      "type": "string",
      "description": "Organization name or EIN, for example American Red Cross or 53-0196605.",
      "examples": [
        "53-0196605",
        "American Red Cross",
        "nonexistent quasar charity xyzzzx"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "organization": "53-0196605"
    },
    {
      "state": "Virginia",
      "max_results": 5,
      "organization": "American Red Cross"
    },
    {
      "organization": "nonexistent quasar charity xyzzzx"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `organizations` | array |  |  |
| `organizations[].ein` | string | `"53-0196605"` |  |
| `organizations[].city` | string or null | `"Washington"` |  |
| `organizations[].state` | string or null | `"District of Columbia"` |  |
| `organizations[].country` | string or null | `"United States"` |  |
| `organizations[].legal_name` | string | `"American National Red Cross"` |  |
| `organizations[].irs_page_link` | string | `"https://apps.irs.gov/app/eos/details/"` |  |
| `organizations[].revocation_date` | string or null |  |  |
| `organizations[].deductibility_code` | string or null | `"PC"` |  |
| `organizations[].reinstatement_date` | string or null |  |  |
| `organizations[].deductibility_status` | string | `"Donations are tax-deductible - public charity"` |  |
| `organizations[].automatically_revoked` | boolean | `false` |  |
| `organizations[].doing_business_as_name` | string or null |  |  |
| `organizations[].most_recent_form_990_filings` | array |  |  |

**Example input**

```json
{
  "organization": "53-0196605"
}
```

**Example output**

```json
{
  "organizations": [
    {
      "ein": "53-0196605",
      "city": "Washington",
      "state": "District of Columbia",
      "country": "United States",
      "legal_name": "American National Red Cross",
      "irs_page_link": "https://apps.irs.gov/app/eos/details/",
      "revocation_date": null,
      "deductibility_code": "PC",
      "reinstatement_date": null,
      "deductibility_status": "Donations are tax-deductible - public charity",
      "automatically_revoked": false,
      "doing_business_as_name": null,
      "most_recent_form_990_filings": [
        {
          "link": "https://apps.irs.gov/pub/epostcard/cor/530196605_202506_990_2026072824433471.pdf",
          "tax_year": 2025,
          "form_type": "Form 990"
        },
        {
          "link": "https://apps.irs.gov/pub/epostcard/cor/530196605_202506_990T_2026050624154274.pdf",
          "tax_year": 2025,
          "form_type": "Form 990-T"
        },
        {
          "link": "https://apps.irs.gov/pub/epostcard/cor/530196605_202406_990_2025051223427881.pdf",
          "tax_year": 2024,
          "form_type": "Form 990"
        }
      ]
    }
  ]
}
```

### Get tax form

Operation `get_tax_form`, version 1. 1 credit per call.

Find current IRS forms, instructions, and publications by number or purpose, with revision and posting dates, PDF links, and available usage details. Results are limited to products in the current IRS directory.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `form` | string | yes | `"form to request a tax transcript"` | The form number or what it is for, such as W-9 or change of address. |
| `max_results` | integer | no | `2` | Maximum number of matching products to return, for example 5. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "form"
  ],
  "properties": {
    "form": {
      "type": "string",
      "description": "The form number or what it is for, such as W-9 or change of address.",
      "examples": [
        "form to request a tax transcript",
        "W-9",
        "Publication 17"
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 5,
      "maximum": 20,
      "minimum": 1,
      "description": "Maximum number of matching products to return, for example 5.",
      "x-fous-developer": true,
      "examples": [
        2
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "form": "form to request a tax transcript"
    },
    {
      "form": "W-9"
    },
    {
      "form": "Publication 17"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `forms` | array |  |  |
| `forms[].type` | string | `"form"` |  |
| `forms[].title` | string | `"Request for Transcript of Tax Return"` |  |
| `forms[].pdf_link` | string | `"https://www.irs.gov/pub/irs-pdf/f4506t.pdf"` |  |
| `forms[].explanation` | string or null | `"Use Form 4506-T to request any of the transcripts: tax return, tax account, wage and income, record of account and veri` |  |
| `forms[].form_number` | string | `"4506-T"` |  |
| `forms[].posted_date` | string or null | `"2025-05-19"` |  |
| `forms[].revision_date` | string or null | `"Apr 2025"` |  |
| `forms[].about_page_link` | string or null | `"https://www.irs.gov/forms-pubs/about-form-4506-t"` |  |
| `forms[].instructions_pdf_link` | string or null | `"https://www.irs.gov/pub/irs-pdf/iw9.pdf"` |  |

**Example input**

```json
{
  "form": "form to request a tax transcript"
}
```

**Example output**

```json
{
  "forms": [
    {
      "type": "form",
      "title": "Request for Transcript of Tax Return",
      "pdf_link": "https://www.irs.gov/pub/irs-pdf/f4506t.pdf",
      "explanation": "Use Form 4506-T to request any of the transcripts: tax return, tax account, wage and income, record of account and verification of non-filling.",
      "form_number": "4506-T",
      "posted_date": "2025-05-19",
      "revision_date": "Apr 2025",
      "about_page_link": "https://www.irs.gov/forms-pubs/about-form-4506-t",
      "instructions_pdf_link": null
    },
    {
      "type": "form",
      "title": "IVES Request for Transcript of Tax Return",
      "pdf_link": "https://www.irs.gov/pub/irs-pdf/f4506c.pdf",
      "explanation": "Use Form 4506-C, IVES Request for Transcript of Tax Return, to request tax return information through an authorized IVES participant.",
      "form_number": "4506-C",
      "posted_date": "2022-10-31",
      "revision_date": "Oct 2022",
      "about_page_link": null,
      "instructions_pdf_link": null
    },
    {
      "type": "form",
      "title": "Short Form Request for Individual Tax Return Transcript",
      "pdf_link": "https://www.irs.gov/pub/irs-pdf/f4506tez.pdf",
      "explanation": "Use Form 4506-T-EZ to request tax return information.",
      "form_number": "4506-T-EZ",
      "posted_date": "2025-09-11",
      "revision_date": "Mar 2025",
      "about_page_link": "https://www.irs.gov/forms-pubs/about-form-4506-t-ez",
      "instructions_pdf_link": null
    }
  ]
}
```

## Quick start

Call the API with a Fous API key (`FOUS_API_KEY`). To create one, turn on Developer mode in Fous Studio, then open Keys & connections → API keys (https://app.fous.com/keys).

```bash
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
: "${FOUS_API_KEY:?Set FOUS_API_KEY before running this example}"

curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 120 \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@irs",
  "visibility": "public",
  "operation": "check_charity_status",
  "version": 1,
  "input": {
    "organization": "53-0196605"
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
import json
import os
import urllib.error
import urllib.request

api_key = os.environ.get("FOUS_API_KEY")
if not api_key:
    raise RuntimeError("Set FOUS_API_KEY before running this example")

body = json.loads("{\n  \"api\": \"@irs\",\n  \"visibility\": \"public\",\n  \"operation\": \"check_charity_status\",\n  \"version\": 1,\n  \"input\": {\n    \"organization\": \"53-0196605\"\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=120) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
// First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
const apiKey = process.env.FOUS_API_KEY;
if (!apiKey) throw new Error("Set FOUS_API_KEY before running this example");

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(120_000),
  body: JSON.stringify({
  "api": "@irs",
  "visibility": "public",
  "operation": "check_charity_status",
  "version": 1,
  "input": {
    "organization": "53-0196605"
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

Or describe the data in plain language: send `{"api":"@irs","prompt":"Describe the data you need, with every detail"}` to the same URL. Fous fills in the input, runs the method that fits and returns only the fields you asked for; `data.route.calls[].request` is the exact call it made. Routing is free; the run costs the same.

## FAQ

### Is Fous affiliated with IRS?

No. Fous is not affiliated with IRS. This workflow reads the public irs.gov website and returns its data.

### How much does it cost?

Each run costs 1 credit. With pay-as-you-go, a credit costs 1¢; monthly plans cost less per credit.

### Do I need a IRS account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from irs.gov when you run it; repeating the same request within a day may return the saved result. Fous checks this workflow automatically; it last passed a check on Sep 29, 2026.

## Related

- [ProPublica Nonprofit Explorer API](https://fous.com/workflows/propublica-nonprofit-explorer.md): ProPublica Nonprofit Explorer searches U.S. tax-exempt organizations and shows available latest revenue, assets, filing-year finances, and top reported pay; reporting years and records vary.
- [Federal Register API](https://fous.com/workflows/federal-register.md): Search United States federal rules, proposed rules, notices, and presidential documents.
- [Annuaire des Entreprises API](https://fous.com/workflows/annuaire-des-entreprises.md): French government directory of public company registrations.
- [Grants.gov API](https://fous.com/workflows/grants-gov.md): U.S. federal grant opportunities and application information.
- [OSHA API](https://fous.com/workflows/osha.md): Public workplace safety inspection and enforcement records.
- [Better Business Bureau API](https://fous.com/workflows/better-business-bureau.md): Better Business Bureau provides business profiles, ratings, accreditation, reviews, alerts, and published complaints, with complaint details limited to those publicly displayed and newest first.
- [Companies House API](https://fous.com/workflows/companies-house.md): Companies House returns UK public-register company details, officers, people with significant control and recent filings; records may be incomplete, and ceased entries are optional.
- [NPI Registry API](https://fous.com/workflows/npi-registry.md): NPI Registry returns public US provider search results with contact and taxonomy details, plus individual 10-digit NPI records with registry dates; fields may be missing.
- [All Government workflows](https://fous.com/workflows/category/government)