---
title: "Rank recipients by what they received"
method: GET
path: "/api/v1/grants/recipients"
tags: ["Grants"]
---

# Rank recipients by what they received

`GET /api/v1/grants/recipients`

## Request

- Base URL: `https://data.useplinth.com`
- URL: `https://data.useplinth.com/api/v1/grants/recipients`
- Auth: API key in header `X-API-Key`

Recipient organizations matching the filter, ranked by dollars received, with location and how many distinct funders backed them.

## Query parameters

- `funder_id` string, nullable
- `recip_id` string, nullable
- `id_type` 'ein', nullable
- `year` string, nullable
- `min_year` string, nullable
- `max_year` string, nullable
- `subject` string, nullable
- `location` string, nullable
- `geo_id_type` 'state' | 'zip' | 'city' | 'county_fips' | 'country', nullable
- `location_type` 'recipient' | 'funder' | 'area_served', nullable
- `country` string, nullable
- `query` string, nullable
- `support` string, nullable
- `funder_type` 'private_foundation' | 'public_charity' | 'daf_or_passthrough', nullable
- `exclude` string, nullable
- `exclude_daf` string, nullable
- `min_amt` string, nullable
- `max_amt` string, nullable
- `min_match_prob` string, nullable
- `ein_source` string, nullable
- `jurisdiction` string, nullable
- `strict` string, nullable
- `format` 'json' | 'xml', nullable
- `population` string, nullable
- `transaction` string, nullable
- `include_gov` string, nullable
- `last_updated` string, nullable
- `profile_levels` string, nullable
- `page` string, nullable
- `limit` string, nullable
- `sort_by` string, nullable
- `sort_order` 'asc' | 'desc', nullable
- `example` '1' | 'list'

## Response `200`

Recipients matching the filter, aggregated.

- RecipientsResponse
  - `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.
  - `hits` integer, required: Total matching rows, not the number returned.
  - `page` integer, required
  - `limit` integer, required
  - `results_count` integer, required: Rows in THIS response.
  - `total_pages` integer, required
  - `results` RecipientAggregate[], required
    - `recip_ein` string, nullable
    - `recip_name` string, nullable
    - `recip_city` string, nullable
    - `recip_state` string, nullable
    - `recip_zip` string, nullable
    - `recip_country` string, nullable
    - `total_amount` integer, nullable
    - `grant_count` integer, nullable
    - `funder_count` integer, nullable
    - `first_fiscal_year` integer, nullable
    - `last_fiscal_year` integer, nullable

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