---
title: "IRS status and sanctions screen for one organization"
method: GET
path: "/api/v1/screening/{ein}"
tags: ["Organizations"]
---

# IRS status and sanctions screen for one organization

`GET /api/v1/screening/{ein}`

## Request

- Base URL: `https://data.useplinth.com`
- URL: `https://data.useplinth.com/api/v1/screening/{ein}`
- Auth: API key in header `X-API-Key`

Exemption subsection, deductibility, foundation type, NTEE and IRS auto-revocation status, plus name screens against the OFAC sanctions lists (SDN and Consolidated, primary and alias names), the Internal Revenue Bulletin's §170 deletion announcements, and California registration (AG Registry + FTB). Every screen reports whether it RAN: a source that is unavailable comes back `not screened`, never `clear`.

`compliance.reliance` carries the Rev. Proc. 2018-32 §8.01 elements — the checklist the IRS publishes for relying on EO BMF data from a third party — element by element, with the EO BMF Extract revision date and whether it is the current one. `?format=pdf` returns the same screen as a one-page retainable report for the grant file (paid keys; §8.01(2) puts the retention obligation on the grantor).

The name screens are triage signals, not determinations.

## Path parameters

- `ein` string, required

## Query parameters

- `format` 'json' | 'xml', nullable
- `compat` string, nullable
- `example` '1' | 'candid' | 'not_found' | 'taster' | 'list'

## Response `200`

A compliance screen for one organization.

- ComplianceResponse: A Charity Check-shaped screen. On an unpaid key the verdicts are present and the evidence fields are blanked — `x_plinth.withheld` names every one, so a client can tell a blank from a no.
  - `code` integer
  - `message` string, required
  - `x_plinth` XPlinth: Non-Candid metadata. Safe to ignore for compatibility; `unsupported` is the one to assert on.
    - `warnings` ResponseWarning[], nullable
      - `parameter` string, required
      - `severity` string, required: `caveat` informs; anything else means a filter did NOT apply.
      - `reason` string, required
    - `unsupported` string[], nullable: Parameters that did not apply. Non-empty means the answer is not the question asked.
    - `dataset` DatasetStamp: Provenance of the slice that answered. `version` is the sync signal — poll it, re-pull when it moves.
      - `source` string, nullable
      - `refresh` string, nullable
      - `polled` string, nullable: How often we LOOK for a new IRS release, as distinct from how often the IRS publishes one.
      - `reporting_lag` string, nullable: Why a figure is dated to a fiscal year rather than to today.
      - `basis` string, nullable: Grants PAID versus grants approved — the reconciliation that catches people comparing a total here to a funder's own published giving figure. Read it before filing a discrepancy.
      - `version` string, nullable: Opaque build stamp of the data slice. Changes only when the data does.
      - `generated_at` string, nullable: ISO 8601 timestamp the slice was built.
      - `license` string, nullable: Licence the source data is published under, where it carries one. Absent for public-domain sources.
      - `attribution` string, nullable: Attribution the source licence obliges you to reproduce. Present it verbatim wherever you show figures from this jurisdiction.
      - `currency` string, nullable: Currency of every amount in the response, when it is not US dollars. Amounts are never converted — they are the filing's own figures.
    - `datasets` DatasetStamp[], nullable: Every corpus this response could have drawn on, each with its own licence terms. /sql only: you write the query, so which corpus answered is not knowable per response — honour every licence listed.
      - `source` string, nullable
      - `refresh` string, nullable
      - `polled` string, nullable: How often we LOOK for a new IRS release, as distinct from how often the IRS publishes one.
      - `reporting_lag` string, nullable: Why a figure is dated to a fiscal year rather than to today.
      - `basis` string, nullable: Grants PAID versus grants approved — the reconciliation that catches people comparing a total here to a funder's own published giving figure. Read it before filing a discrepancy.
      - `version` string, nullable: Opaque build stamp of the data slice. Changes only when the data does.
      - `generated_at` string, nullable: ISO 8601 timestamp the slice was built.
      - `license` string, nullable: Licence the source data is published under, where it carries one. Absent for public-domain sources.
      - `attribution` string, nullable: Attribution the source licence obliges you to reproduce. Present it verbatim wherever you show figures from this jurisdiction.
      - `currency` string, nullable: Currency of every amount in the response, when it is not US dollars. Amounts are never converted — they are the filing's own figures.
    - `excluded` object, nullable: Per-class cost of `?exclude=`, keyed by class name, plus `overlapping` — true when classes were counted independently and therefore sum to more than the whole. /grants/summary only.
    - `unidentified` Unidentified: Grants held OUT of a recipient ranking because their recipient is not an organization.
      - `grants` integer, nullable
      - `dollars` integer, nullable
      - `note` string, nullable
      - `unavailable` string, nullable: Present only when the size could not be computed. The ranking above is unaffected.
  - `ein` string, required
  - `compliance` object, required: The screen itself: BMF status, Pub 78, revocation, sanctions, NTEE, financials.
  - `report_date` string, nullable
  - `report_id` string, nullable: Identifies this screen by its contents — a digest of the record, its sources and `report_date`. Re-deriving it from a retained response reproduces the same value; an altered one does not. Not a signature: anyone can recompute it, so it evidences drift rather than authenticity.
  - `sources` object, nullable: When each IRS/Treasury source behind this screen was last pulled.

## Other responses

- `401`: No API key, or a key we do not recognize.
- `402`: The call allowance is spent, the account is inactive, or the endpoint needs a paid plan — the message says which, and names the period it resets on (daily on free and non-profit plans, monthly on Pro).
- `422`: Validation Error

---

[API](https://skmtc.dev/useplinth/apis/plinth-grants-api.md) · [All operations](https://skmtc.dev/useplinth/apis/plinth-grants-api/llms.txt) · [OpenAPI document](https://skmtc.dev/useplinth/apis/plinth-grants-api/revisions/15273cd72ecf?raw)