Organizations

Search organizations (Candid Essentials-shaped)

Nonprofit SEARCH, in the POST-with-a-body shape a Candid Essentials v4 client already builds: search_terms, from, size, filters, sort. This is the endpoint that corresponds to Candid's /essentials/v4 — GET /api/essentials/{ein} is the single-record lookup, and mapping a search API onto it is the migration mistake worth avoiding.

Use jurisdiction=ca for Canadian organizations; the default is us. Financial filters use the filing currency, identified in x_plinth.dataset; currencies are never combined. Filters cover geography, IRS classification and financial ranges, all read from the organization's own filing. Candid's PCS subject, profile-participation and demographic filters have no counterpart; send one and it comes back named in x_plinth.warnings rather than being dropped.

post/api/v1/essentials

Request

  • Base URL: https://data.useplinth.com
  • URL: https://data.useplinth.com/api/v1/essentials
  • Auth: API key in header X-API-Key

Query parameters

jurisdictionstring nullable
Example:us

Filing jurisdiction of the GRANT: us (default) | ca. Never mixed — amounts stay in the currency the filing was made in and are never converted, so every total is a single-jurisdiction total. x_plinth.dataset names the source, licence and currency behind the answer. Distinct from country, which is where the RECIPIENT sits.

Request body

search_termsstring nullable

Organization name or keyword.

frominteger nullable

0-based offset, as Candid.

sizeinteger nullable

Page size. Default 25, capped at 1000 (Candid's ceiling is 25).

modestring nullable

text (default) | semantic. semantic matches on mission meaning rather than name, where the embedding store is staged.

filtersobject nullable

See the Essentials filter matrix. Unknown keys are reported, not ignored.

strictboolean nullable

Reject the request if any filter could not be honored.

Example request

{
  "search_terms": "food bank"
}

Response

Organizations matching the search.

codeinteger
messagestring required
hitsinteger required
sizeinteger required
results_countinteger required
modestring nullable
resultsobject[] required
frominteger required

Zero-based offset of the first row returned.

Changes

No recorded changes to this operation across all 1 revision of this API.