---
title: "Resolve an organization name to an EIN and canonical URL"
method: GET
path: "/api/v1/search"
tags: ["Resolve"]
---

# Resolve an organization name to an EIN and canonical URL

`GET /api/v1/search`

## Request

- Base URL: `https://data.useplinth.com`
- URL: `https://data.useplinth.com/api/v1/search`
- Auth: none required

Entity resolution — the step that precedes every other call when you have a name rather than an EIN. Searches every US grantmaking foundation and funded nonprofit, or the Canadian charities register under `jurisdiction=ca`. **No API key required and not metered.**

`q` also accepts an EIN (`131684331` or `13-1684331`), which resolves against the index directly rather than as text. A parameter this endpoint does not accept comes back named in `x_plinth.warnings`, and `strict=1` turns that into a 400 — the same contract as the grant endpoints. Omitting `q` is a 400 rather than an empty result set, because an empty result set is indistinguishable from a genuine miss.

## Query parameters

- `q` string, required
- `jurisdiction` 'us' | 'ca'
- `state` string
- `limit` integer
- `min` integer
- `max` integer
- `strict` string
- `example` string

## Response `200`

Matching organizations, best first.

- object
  - `mode` string: The matching mode actually served. Always `text` today: the vector index is unpopulated, so semantic matching is not offered and the `mode` REQUEST parameter is deliberately not part of this contract. Sending one is not an error — it comes back named in `x_plinth.warnings`. Present on EVERY response, including errors and the too-short-query case.
  - `results` object[]
    - `ein` string
    - `name` string
    - `type` string: Human-readable kind: Grantmaking foundation or Nonprofit.
    - `kind` 'foundation' | 'nonprofit'
    - `state` string, nullable: Two-letter postal code as filed: a US state, or a province or territory when `country` is `CA`.
    - `location` string, nullable: The SAME value as `state`, under the name the first consumers of this endpoint used. Kept because it is in live clients; prefer `state` in new code.
    - `cause` string, nullable: NTEE major-group label. Null wherever the BMF carries no NTEE code, which is common — parse permissively.
    - `slug` string, nullable: URL slug for the organization's page. Null for organizations without a curated page.
    - `href` string, nullable: Site-relative path to that page. `url` is the same target, absolute; prefer it outside this domain.
    - `country` 'US' | 'CA': The register the row came from. Present on every row, so no result is currency-ambiguous.
    - `currency` 'USD' | 'CAD': The currency `revenue` is in — the filing's own. Nothing in this dataset is converted, so figures from the two registers are never comparable and never additive.
    - `revenue` integer, nullable: Total revenue from the latest filing held, in the currency named by `currency`. Here to disambiguate similarly-named organizations, and it gently weights the ranking; not a financial figure to cite — use /essentials or /premier for that.
    - `score` number, nullable: Match strength; results are already ordered by it. Null on an exact-EIN lookup, which has no relevance score.
    - `url` string, uri: Absolute canonical URL of the organization's page — stable, and citable.
  - `x_plinth` object: Present only when something needs saying: `warnings[]` names any parameter this endpoint does not accept or could not honour, and `unsupported[]` lists the fatal ones. Same shape as the grant endpoints.
    - `warnings` object[]
      - `parameter` string
      - `severity` 'unsupported' | 'caveat'
      - `reason` string
    - `unsupported` string[]

## Other responses

- `400`: `q` is missing, `jurisdiction` is neither `us` nor `ca` (or contradicts the namespace of an organization key in `q`), or `strict=1` was sent alongside a parameter this endpoint does not accept. The body names which.
- `503`: The index timed out twice (a cold cache). Transient — `Retry-After` says when to come back.

---

[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)