For developers

A free alternative to the Candid API

Plinth publishes a JSON grants API over 211,000 US grantmakers and 20.1 million grants, read from IRS Form 990, 990-EZ and 990-PF filings. It is free with a key at 50 calls a day for the grant graph, and it deliberately follows the parameter vocabulary of existing grant-data APIs, so porting a client is mostly mechanical. If you are replacing Charity Check rather than the Grants API, compliance screening and the organization profiles are on a paid key here, and the differences are set out below.

Where this comparison comes from. Everything on this page is taken from Candid’s published documentation and from the public IRS Form 990 e-file data that both services read. Where their documentation does not settle a question, we say so rather than guess, and figures attributed to Candid are cited to the page that states them.

It is not a drop-in replacement, and this page is specific about why. Candid figures below were read from Candid’s own developer portal and pricing pages on 12 August 2026.

Doing research? Use SQL instead

The migration guide below is accurate: most parameters map, and a client that pages through grant records will move across with small changes.

But if you are doing analysis rather than replacing an integration, don’t page through REST at all. POST /api/v1/sqlruns read-only SQL over the whole corpus: grants, funders, co-funder overlap, board interlocks and government awards, already joined. “Which funders back the same grantees as this one, and who funded them first” is one query there and dozens of paged calls otherwise. Candid has no equivalent.

Coverage and accuracy figures for the matching underneath are on the data-quality page.

What changes in a migration

One edit is unavoidable. Two more apply only if you use the parameters concerned; the second changes no syntax at all.

1 · The authentication header

Candid authenticates with Subscription-Key. We accept X-API-Key or an Authorization: Bearer token. Keys start plinth_sk_ and are secrets, keep them server-side. Amount filters need no change at all: min_amt and max_amt mean the same thing on both.

# before
curl -H 'Subscription-Key: $CANDID_KEY' \
  'https://api.candid.org/grants/v1/transactions?recip_id=13-1837418&id_type=ein'

# after
curl -H 'X-API-Key: $PLINTH_API_KEY' \
  'https://data.useplinth.com/api/v1/grants/transactions?recip_id=13-1837418'

2 · Two parameters share a name and not a meaning

These are the ones that survive a find-and-replace on the hostname and then quietly answer a different question. Both now refuse a Candid-shaped value rather than returning an empty page you would read as a real finding.

They are subject, where Candid’s is a PCS code and ours is NTEE, and location, which Candid reads as a GeoNames id and we read as a US state by default. The exact accepted values for both, and for the three other parameters that need a converted value (id_type, geo_id_type, sort_by), are in the parameter table below.

3 · 5 filters have no counterpart, and say so

We accept every one of them rather than rejecting the request, and name each in the response. A migrated query that silently drops population=children returns valid-looking output over every population; that is how a hostname change turns into wrong research. Add strict=1 and the same request is a 400 instead. Use it in your test suite so a lost filter fails loudly rather than at read time.

GET https://data.useplinth.com/api/v1/grants/summary?population=children&year=2023

{
  "code": 200,
  "summary": { ... },
  "x_plinth": {
    "unsupported": ["population"],
    "warnings": [{ "parameter": "population", "reason": "PCS population ... " }]
  }
}
# response header: X-Plinth-Unsupported: population

They are include_gov, population, transaction, last_updated and profile_levelseach with the reason it cannot be honored, and the nearest thing we do have, in the parameter table below.

Endpoint mapping

Candid endpoint names and parameters read from the Grants API reference and authentication docs, 2026-08-12.

Every Grants parameter, one by one

10 carry over unchanged, 6 need a converted value, 5 have no counterpart and are reported at runtime, and 9 exist here and not on Candid. This table is generated from the same file the API builds its filters and warnings from, so it cannot drift from the behavior, and the machine-readable form is at /api/v1/meta.

Essentials is a search API

Candid’s POST /essentials/v4 searches across organizations. Mapping it onto GET /api/essentials/{ein}, a single-record fetch, would turn a search into a lookup, so we serve POST /api/essentials in the same body shape: search_terms, from, size, filters, sort. The filter vocabulary inside is ours, because Candid’s is built on PCS and on profile data we do not hold.

curl -X POST -H 'X-API-Key: $PLINTH_API_KEY' \
  -H 'content-type: application/json' \
  'https://data.useplinth.com/api/essentials' -d '{
    "search_terms": "food bank",
    "size": 25,
    "filters": { "state": "MA", "min_revenue": 1000000, "pub78_verified": true },
    "sort": { "field": "total_revenue", "order": "desc" }
  }'

Support strategy, without the PCS license

Candid’s PCS supportfacet answers “what is the funder paying for?”: unrestricted operating money versus a restricted project. That is a genuinely useful prospecting signal and we cannot license the classification, so we derive it from the grant’s own purpose text as filed. It is approximate by construction: it finds grants that say so, and misses those that fund the same way without saying it. Every response using it repeats that caveat.

What is not equivalent

Enrichment beyond the filings. Candid states Premier carries 760+ additional fields, much of it collected directly from nonprofits through profile claiming and Seals of Transparency. That data does not exist in IRS filings, so we do not have it at any price.

Products with no counterpart. News, Taxonomy, Demographics, Nonprofit Eligibility and Open RFP Opportunities. Candid’s Demographics and Taxonomy APIs are listed at no fee, so “free API” is not by itself a reason to switch.

Corpus size. Candid states 29 million grants and 304,000 funder profiles, against our 20.1 million grant rows and 211,000 funders. Of ours, 15.2 million are linked to a specific recipient organization; the rest are real grants whose recipient name we would not stake an EIN on, so they carry no classification and drop out of any recipient-keyed filter. We publish that split, and the measured precision behind it, on /data-quality. If coverage is the binding constraint, Candid has more.

Why the two numbers differ. They are not counting the same thing. Candid’s data-sources page (2026-08-15) lists funders who report to Candid directly, organization websites, news and press releases, funder-network partnerships, and UK grantmaking published to the 360Giving standard. Ours is one source: US e-filed Form 990, 990-EZ and 990-PF, FY2017–2023. That is the whole trade. Their number reaches money ours cannot see: grants a funder announced but has not yet filed, non-US giving, funders who volunteer data and every row of ours resolves to a named filing you can open and check, with no row resting on a press release. Neither is the better number in the abstract; they answer different questions, and the one you want depends on whether you need reach or receipts.

What we checked, and what we found. Candid released Essentials and Premier v4 on 25 March 2026. We have since worked through their published v4 field reference line by line, and the mapping above reflects it. One divergence was material enough to build for: Candid types several booleans as the strings "True" and "False". We return real JSON booleans by default, and emit Candid’s rendering on request. Add ?compat=legacy_stringsto a compliance call and an existing parser keeps working. The one caveat left: Candid’s published specification index lists Essentials and Premier at v1.0 rather than v4, so the v4 shapes are read from its live reference rather than a versioned spec document. Check response fields against your own usage before you cut over.

The path is versioned. Candid has /grants/v1/transactions; ours is /api/v1/grants/transactions. Inside v1we add and do not take away — new fields can appear, so parse permissively, but nothing is removed, renamed or redefined under a client that is already running. The unversioned /api/grants/…still resolves and will keep resolving; pin to /api/v1 for anything you deploy.

Our specification is published, and generated. /openapi.jsonis OpenAPI 3.1 built from the service’s own route signatures rather than maintained by hand, so it cannot describe an endpoint the service does not have (it is edge-cached, so a redeploy takes a few minutes to show) — point a client generator, an HTTP client or an agent straight at it. /llms.txt indexes the documentation for the same purpose, and /.well-known/apis.json carries the machine-readable description. Every parameter we accept, and every one we deliberately do not, is in there.

What you get that Candid has no counterpart for

A SQL endpoint. /api/v1/sql runs analytical queries directly against the corpus, so questions that would take many paged REST calls become one query.

Plain-English querying. /api/v1/analyze takes a question, writes and runs the query, and returns a sourced answer with the SQL it used. Also available in the browser at /analyze.

Pages of 1,000, not 25. Candid caps its Grants endpoints at 25 results a call. Ours go to 1,000, and every response carries results_count and total_pagesso a pager does not have to derive them. Bulk compliance takes 100 EINs against Candid’s 25, and costs one call, not one per organization.

Both directions of the funding graph on the organization record. /api/premier answers who an organization funds and who funds it, with the top funders named — a Premier profile describes the organization, not the money reaching it.

Filters built on our own classification work — donor-advised and pass-through funders separable from institutional money (funder_type), the three classes of flow that distort any total separable in one parameter (exclude=daf,individuals,related_party — pass-through money, grants to people rather than organizations, and transfers inside one economic entity, together 50.9%of corpus dollars), cross-border giving by country from the 990 foreign-address block, and support strategy from the filing’s own wording.

Layers computed across the whole corpus — co-funder overlap strength, portfolio clustering, board interlocks from Form 990 Part VII, and federal plus nine-state government funding joined to the same organizations.

What the compliance endpoint does

The full write-up of how the screen works, including the two kinds of join and the rule that a missing source reports not screened rather than clear, is on /screening. What follows is the Candid-shaped mapping.

GET /api/screening/{ein} returns one JSON record covering seven reference files from four agencies. POST /api/screening/bulk runs identical logic over up to 100 EINs for one call from your allowance. Both are on a paid key; every key gets a metered taste of the single screen with the evidence fields blanked and named.

Federal status, decoded

From the IRS Business Master File and Publication 78, returned as descriptions rather than raw codes: exemption subsection, foundation classification with its 509(a)paragraph and PC/PF/POF/SO bucket, deductibility, exempt status, ruling date, filing requirement, legal form, affiliation, NTEE, and the BMF’s own financial summary. Group subordinates are resolved to their central organization. The auto-revocation list is reported with its revocation, posting and reinstatement dates, so a reinstated organization does not read as revoked.

Where the BMF shows an active 501(c)(3) and Pub 78 does not list the EIN, that is returned as irs_bmf_pub78_conflict— a needs-review flag with the reason, not a boolean that picks a side. The two files refresh on different schedules and do diverge.

Four screens beyond status

OFAC, all four files. SDN and Consolidated, primary and AKA/FKA/NKA names. Screening SDN primary names alone is a false-negative machine — OFAC lists most entities under several names, and the Consolidated list is separate again. Each response names which of the four it reached.

Internal Revenue Bulletin. The §170 deletion announcements, read from the bulletins. covers_throughnames the newest bulletin read, so a clear result carries a date. A listing is a diligence flag, not a determination — the IRS generally does not disallow contributions made on or before the announcement date — and the response says so.

California, both halves. The Attorney General’s Registry of Charitable Trusts (may it solicit; is its reporting current) and the Franchise Tax Board’s revoked list (has California revoked its exemption, whatever the IRS says). The halves are tracked separately, so one being unavailable reports partially screened rather than a clean result.

Auto-revocation as above, screened by EIN rather than by name.

The reliance elements

compliance.relianceanswers the IRS’s own checklist for relying on third-party EO BMF data — Rev. Proc. 2018-32 §8.01 — element by element, with the evidence for each:

§8.01(1)(a) name, EIN, §509(a) status including supporting-organization type, and whether contributions are deductible. §8.01(1)(b) the EO BMF Extract’s revision date — thepublisher’s date, which is a different fact from when we downloaded it — plus whether that is the current extract, established by asking the IRS host rather than assumed. §8.01(1)(c) the date and time the record was provided. Where an element cannot be evidenced it reports absent, never a substitute value.

It is scoped to the BMF, explicitly. §8 governs foundation status and deductibility and says nothing about sanctions, the IRB or state registration; those screens are diligence, and no revenue procedure makes them a safe harbor.

It also computes the cases where reliance does not apply at all, which a clean-looking BMF row will not tell you: §6.02, an organization not yet listed in either file, and §6.03, a subordinate covered by a group exemption letter — regardless of how it appears in the EO BMF Extract.

Where the IRS files disagree

They do disagree. An organization can sit on the Auto-Revocation List and be listed on Publication 78 with an active BMF status at the same time, because those files move on different schedules and a reinstatement reaches them at different moments. A screen that returns a single verdict has to guess, and both guesses are wrong: call it revoked and you tell a grantmaker not to fund an organization the IRS has re-recognized; call it clear and you miss a live revocation.

So the report names the governing rule instead. That pattern is Rev. Proc. 2018-32 §4.06, which turns on which came later, and the report prints the dates the comparison needs — revocation date, Auto-Revocation posting date, EO BMF ruling date — and says which of §4.06’s two limbs it could evaluate and which it could not.

And it says what to do next, specifically. The fact that settles §4.06 is the effective date on the determination letter, which lives in IRS Tax Exempt Organization Search and in no bulk extract — so no product screening the bulk files, ours or anyone’s, can establish it. Rather than leave that as “check TEOS”, the report carries numbered steps: which database, which date to read, what to compare it to, what to do when the letter predates 2014, and that the result should be filed alongside the report.

The report

?format=pdfreturns the same record as a one-page dated document to file with the grant record: the §8.01(1) elements, every screen with whether it ran, the revision date of each source file, and the limitations that apply to that organization. It is rendered from the response object itself, so the document and the API cannot disagree. §8.01(2) puts retention on you — we keep no copy.

Each one carries three things a retained document needs. An identifier, a digest of the record, its sources and the moment it was provided: re-derive it from the response you kept and it reproduces; alter the response and it does not. A format version, because what a report asserts changes as the reasoning improves, and a holder of last quarter’s copy is entitled to know whether today’s would say something different. And an Ed25519 signature where a signing key is configured — the identifier evidences drift, the signature answers whether it came from us.

POST /api/screening/verify checks a retained report and is keyless and unmetered: confirming a document already in a grant file should not spend a screen, and the auditor doing the checking is the person least likely to hold a key. It reports whether the identifier matches, whether the signature is valid, and whether the format is current — and an unverifiable signature comes back null rather than false, because “we could not check” and “it is forged” are different answers. This is a detached signature over the report data, not an X.509/PAdES PDF signature, so no signature panel appears in a PDF reader; the report says so on its face.

Freshness

Every source with a publisher timestamp is polled every fifteen minutes: a header request each, pulling the file only when its revision actually moves. The Internal Revenue Bulletin and the California AG Registry publish nothing to poll against, so they run daily and the response says so per source rather than quoting one figure for all seven.

Every response carries, per source, the publisher’s revision date, the date we pulled it, and whether it is the current one. What no third party closes is the gap between a sanctions designation taking effect and OFAC republishing its files — for a screen at the moment of disbursement, Treasury’s live search is the source of record.

The rule underneath all of it

A screen whose source is unavailable reports not screened, never clear. Seven files from four agencies on four schedules means one will be down some month, and a caller who reads an unavailable source as a clean result disburses money on a check that never ran. Every screen reports whether it ran, separately from what it found.

What the endpoint does not do is stated in x_plinth.not_available on every response: sanctioned individuals are not screened, only entities; every name-keyed screen matches the organization’s primary IRS name, so another trading name can be missed and a common name can collide; state registration covers California; and none of it is a determination. Plinth is not a law firm.

Get a key

Free, no card, about a minute: generate an API key. Full reference at /developers. If you are weighing the platforms rather than the APIs, Plinth vs Candid covers the product comparison, and the comparison hub covers the rest of the market.