> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Nonprofit Status

> Look up whether a US organization is listed by the IRS as eligible for tax-deductible gifts, whether its exemption was revoked, and which annual returns it filed.

Returns organizations in the US Internal Revenue Service's Tax Exempt Organization Search matching an EIN or name: whether each is listed as eligible for tax-deductible contributions, any automatic revocation of its exemption and reinstatement, its Form 990-N filings, and its filed annual returns with links to the public copies. Figures from the returns are in those copies, not here.

## Authentication

Requires x402 payment in the `payment-signature` header.

## Request Body

**ein** `string`

The employer identification number, for example 53-0196605 or 530196605. An exact match that returns the full profile. An EIN is nine digits, with or without the dash.

**name** `string`

The organization's name, for example American Red Cross. A text match; returns a list to pick from. 2 to 100 characters.

**state** `string`

Two-letter state code to narrow a name search; only with `name`. A two-letter state code.

**limit** `integer`

Most organizations to return for a name; ignored with an EIN. From 1 to 25. Defaults to `10`.

<Snippet file="audit-context-params.mdx" />

<Snippet file="cached-record-params.mdx" />

## Response (200 OK)

Top-level envelope: `success` (boolean) and `data` (object). All fields below are nested under `data`.

**data.request\_id** `string`

Durable job ID for audit and lookup

**data.status** `string`

Job status: `completed`

**data.tool** `string`

Always `company_nonprofit_status`

**data.result** `object`

The answer, described under Result below

**data.evidence** `object`

Where the answer came from and when

**data.cached** `boolean`

`true` when the answer was served from OneShot's store of earlier lookups (or its own copy of a public dataset), `false` when the source was asked for this call

**data.fetched\_at** `string`

When the record was obtained from its source, as an ISO 8601 UTC time; equals `evidence.retrieved_at`

**data.evidence.source** `string`

The public body the data comes from. Always `US Internal Revenue Service`.

**data.evidence.source\_kind** `string`

`public` when the data comes from a public body, `commercial` otherwise

**data.evidence.retrieved\_at** `string`

When the lookup was made, as an ISO 8601 UTC time

**data.evidence.as\_of** `string | null`

When the source says the fact was last updated, or `null` when the source gives no date

## Result

Nested under `data.result`.

**data.result.total** `integer`

How many organizations matched; may be more than were returned.

**data.result.matches** `object[]`

Organizations matching a name, alphabetical; empty for an EIN.

**data.result.matches\[].ein** `string`

The employer identification number, nine digits.

**data.result.matches\[].name** `string | null`

Name. `null` when the source gives no value.

**data.result.matches\[].dba** `string | null`

A doing-business-as name, when the source lists one. `null` when the source gives no value.

**data.result.matches\[].city** `string | null`

City. `null` when the source gives no value.

**data.result.matches\[].state** `string | null`

Two-letter state code. `null` when the source gives no value.

**data.result.matches\[].country** `string | null`

Country. `null` when the source gives no value.

**data.result.matches\[].listed\_in** `string[]`

Which of the source's lists name the organization: `publication_78` (eligible for deductible gifts), `auto_revocation`, `determination_letters`, `form_990n` and `returns`.

**data.result.profile** `object | null`

The organization with the given EIN; null for a name, or when the EIN is in none of the source's lists.

**data.result.profile.ein** `string`

The employer identification number, nine digits.

**data.result.profile.name** `string | null`

Name. `null` when the source gives no value.

**data.result.profile.dba** `string | null`

A doing-business-as name, when the source lists one. `null` when the source gives no value.

**data.result.profile.city** `string | null`

City. `null` when the source gives no value.

**data.result.profile.state** `string | null`

Two-letter state code. `null` when the source gives no value.

**data.result.profile.country** `string | null`

Country. `null` when the source gives no value.

**data.result.profile.listed\_in** `string[]`

Which of the source's lists name the organization: `publication_78` (eligible for deductible gifts), `auto_revocation`, `determination_letters`, `form_990n` and `returns`.

**data.result.profile.publication\_78** `object | null`

Present when the organization is listed as eligible to receive tax-deductible contributions; null when it is not listed.

**data.result.profile.publication\_78.deductibility\_code** `string | null`

The source's deductibility code, for example PC for a public charity or PF for a private foundation. `null` when the source gives no value.

**data.result.profile.revocations** `object[]`

Automatic revocations of exemption for not filing, newest first; check `reinstated_on` before treating one as current.

**data.result.profile.revocations\[].revoked\_on** `string | null`

Date the exemption was automatically revoked, YYYY-MM-DD. `null` when the source gives no value.

**data.result.profile.revocations\[].posted\_on** `string | null`

Date the revocation was posted, YYYY-MM-DD. `null` when the source gives no value.

**data.result.profile.revocations\[].reinstated\_on** `string | null`

Date the exemption was reinstated, YYYY-MM-DD; null when it has not been.

**data.result.profile.revocations\[].exemption\_subsection** `string | null`

The subsection of section 501(c) the exemption was under, for example 03. `null` when the source gives no value.

**data.result.profile.form\_990n\_filings** `object[]`

The newest Form 990-N (e-Postcard) filings, at most 5, newest first.

**data.result.profile.form\_990n\_filings\[].tax\_year** `integer | null`

Tax year. `null` when the source gives no value.

**data.result.profile.form\_990n\_filings\[].period\_start** `string | null`

YYYY-MM-DD. `null` when the source gives no value.

**data.result.profile.form\_990n\_filings\[].period\_end** `string | null`

YYYY-MM-DD. `null` when the source gives no value.

**data.result.profile.form\_990n\_filings\[].gross\_receipts\_under\_50k** `boolean`

True when the filer declared gross receipts normally under 50,000 dollars.

**data.result.profile.form\_990n\_filings\[].terminated** `boolean`

True when the filing says the organization has terminated.

**data.result.profile.returns** `object[]`

The newest filed returns with public copies, at most 10, newest first.

**data.result.profile.returns\[].tax\_period** `string | null`

The period the return covers, YYYY-MM (its last month). `null` when the source gives no value.

**data.result.profile.returns\[].form** `string | null`

The form filed: 990, 990EZ, 990PF or 990T. `null` when the source gives no value.

**data.result.profile.returns\[].filed\_electronically** `boolean`

Filed electronically.

**data.result.profile.returns\[].published\_on** `string | null`

Date the public copy was published, YYYY-MM-DD. `null` when the source gives no value.

**data.result.profile.returns\[].url** `string | null`

The public copy of the return on the source's site. `null` when the source gives no value.

```bash cURL theme={null}
curl -X POST https://win.oneshotagent.com/v1/tools/lookup/company-nonprofit-status \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64 x402 payment>" \
  -d '{
    "ein": "530196605"
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://win.oneshotagent.com/v1/tools/lookup/company-nonprofit-status", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "payment-signature": paymentProof,
  },
  body: JSON.stringify({
    "ein": "530196605"
  }),
});
```

```typescript SDK theme={null}
const result = await agent.tool('lookup/company-nonprofit-status', {
  ein: '530196605'
});
console.log(result.result);
console.log(result.evidence);
```

```json Response (200) theme={null}
{
  "success": true,
  "data": {
    "request_id": "uuid",
    "receipt_id": "rcpt_...",
    "status": "completed",
    "tool": "company_nonprofit_status",
    "result": {
      "total": 1,
      "matches": [],
      "profile": {
        "ein": "530196605",
        "name": "American National Red Cross",
        "dba": null,
        "city": "Washington",
        "state": "DC",
        "country": "US",
        "listed_in": [
          "publication_78",
          "returns"
        ],
        "publication_78": {
          "deductibility_code": "PC"
        },
        "revocations": [],
        "form_990n_filings": [],
        "returns": [
          {
            "tax_period": "2025-06",
            "form": "990",
            "filed_electronically": true,
            "published_on": "2026-08-28",
            "url": "https://apps.irs.gov/pub/epostcard/cor/530196605_202506_990_2026072824433471.pdf"
          },
          {
            "tax_period": "2025-06",
            "form": "990T",
            "filed_electronically": true,
            "published_on": "2026-07-08",
            "url": "https://apps.irs.gov/pub/epostcard/cor/530196605_202506_990T_2026050624154274.pdf"
          },
          {
            "tax_period": "2024-06",
            "form": "990",
            "filed_electronically": true,
            "published_on": "2026-02-25",
            "url": "https://apps.irs.gov/pub/epostcard/cor/530196605_202406_990_2025051223427881.pdf"
          }
        ]
      }
    },
    "evidence": {
      "source": "US Internal Revenue Service",
      "source_kind": "public",
      "retrieved_at": "2026-10-27T06:20:00.000Z",
      "calls": [
        {
          "retrieved_at": "2026-10-27T06:20:00.000Z"
        },
        {
          "retrieved_at": "2026-10-27T06:20:00.000Z"
        },
        {
          "retrieved_at": "2026-10-27T06:20:00.000Z"
        }
      ],
      "as_of": null
    }
  }
}
```

> [!NOTE]
>
> See [Pricing](https://docs.oneshotagent.com/pricing.md) for this tool's price. A wallet (x402) call receives it in the 402 quote before anything is charged; a call paid from prepaid credits is charged when the API accepts the request and answers `200`.

## Notes

* Give exactly one of `ein` and `name`; `state` narrows a name search only.
* An EIN returns `profile`, the organization's full record, with `total` 1; `profile` is null and `total` 0 when the EIN is in none of the source's lists. A name returns `matches`, a list of organizations to pick from, alphabetical, each with the EIN to call again with; `profile` is then null.
* Listed in `publication_78` means the organization is eligible to receive tax-deductible contributions. An organization absent from every list may still be exempt: churches need not apply, and the exempt organizations master file is not searched here.
* A row in `revocations` does not mean the organization is still revoked: it may have been reinstated, so check `reinstated_on`. `exemption_subsection` is the section 501(c) subsection the exemption was under, for example 03 for a 501(c)(3).
* `form_990n_filings` keeps the newest five filings and `returns` the newest ten, newest first; each return has the form, the period it covers and a link to its public copy. Officer names and addresses are never returned. Dates are YYYY-MM-DD; one the source writes in an unreadable form is null.
* Results return inline. The finished job stays available at `/v1/requests/{request_id}`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.