Filtering and Sorting

Use the /charities endpoint to search IRS nonprofit records with query parameters for location, classification, financial ranges, pagination, field selection, and sorting.

Route scope

This page covers the standard charity list route.

These options apply to GET /charities. For radius-based search with origin_zip, lat, lng, radius, and distance_miles, use GET /nearby.

Basic filtered request

Filter nonprofits by state and NTEE code.

GET /charities?state=NC&ntee_code=D20&fields=ein,name,state,ntee_code&limit=25

Filters are applied before field selection. Sorting does not require the sorted field to be included in fields.

Filtering

Filters narrow the result set returned by the API.

Filters are passed as query parameters. Some filters accept multiple values and are marked as multi in the tables below.

GET /charities?state=NC&ntee_code=D20,W30&limit=25

Metadata-validated filters

These filters are validated against CharityQuery metadata definitions.

Values are checked against the same code definitions exposed by the metadata endpoints.
Many IRS codes contain leading zeros. Treat code values as strings.
Invalid values return a 400 validation error.

key	type	multi	validation	metadataRoute	example	description
ntee_code	string	Yes	metadata	/metadata/ntee-codes	'B80'	Filters by exact NTEE code. IRS provided values are all 3 strings. 1 letter and 2 numbers
ntee_group	string	Yes	metadata	/metadata/ntee-groups	'B'	Filters by NTEE general group.
account_paid	string	Yes	metadata	/metadata/account-paid-code	'01'	Filters by IRS account paid codes as a proxy for month number starting at 01 (January) and ending at 12 (December).
pf_filing_req_code	string	No	metadata	/metadata/pf-required-codes	'0'	Filters by IRS PF Filing Required codes.
filing_req_code	string	Yes	metadata	/metadata/filing-required-codes	'07'	Filters by IRS Filing Required codes.
organization	string	Yes	metadata	/metadata/organization-codes	'2'	Filters by IRS Organization codes.
status	string	Yes	metadata	/metadata/status-codes	'02'	Filters by IRS Status codes.
affiliation	string	Yes	metadata	/metadata/affiliation-codes	'6'	Filters by IRS Affiliation codes.
deductibility	string	Yes	metadata	/metadata/deductibility-codes	'1'	Filters by IRS deductibility codes.
foundation	string	Yes	metadata	/metadata/foundation-codes	'1'	Filters by IRS foundation codes.
geocode_status	number	Yes	metadata	/metadata/geocode-status-codes	12	Filters by CharityQuery geocode status code.

Subsection and classification

These two filters must be provided together.

subsection and classification must be used together.
The paired combination gives a more precise IRS classification than either value alone.
Use /metadata/subsection-classification to get valid paired combinations when building UI filters.

GET /charities?subsection=03&classification=2000

key	type	multi	validation	metadataRoute	example	description
subsection	string	No	metadata	/metadata/subsection-classification-codes	'03'	Filters by IRS subsection code.
classification	string	No	metadata	/metadata/subsection-classification-codes	'1000'	Filters by IRS classification code.

Direct match filters

These filters match against stored nonprofit data.

Values are treated as strings. Fields such as zip and group may contain leading zeros.
Direct match filters are best for known values such as zip, city, state, group, ruling, and tax_period.
Text fields like name, ico, and street are less reliable unless you know the stored value.

key	type	multi	validation	example	description
name	string	No	direct	Marine Corps League	Filters by charity name.
ico	string	No	direct	Bob Ross	Filters by ICO (In Care Of).
street	string	No	direct	123 Mlk Blv	Filters by street.
city	string	Yes	direct	Raleigh	Filters by city.
state	string	Yes	direct	NC or nc	Filters by state abbreviation.
zip	string	Yes	direct	28387	Filters by ZIP code. First 5 digits only
group	string	No	direct	0955	Filters by group exemption number.
ruling	string	No	direct	199601	Filters by ruling date code (YYYYMM).
activity	string	No	direct	059	Filters by IRS activity code. This was depricated in favor of the NTEE Code
tax_period	string	No	direct	202312	Filters by tax period code, usually formatted as YYYYMM.

Financial range filters

Search nonprofits by asset, income, and revenue amounts.

Range filters let you set minimum and maximum values. You can use one side of a range or combine both.

GET /charities?state=NC&income_amount_gte=1000&income_amount_lte=10000&limit=25

key	type	multi	validation	description	example
asset_amount_gte	number	No	numeric	Minimum asset amount.	100000
asset_amount_lte	number	No	numeric	Maximum asset amount.	500000
income_amount_gte	number	No	numeric	Minimum income amount.	1000
income_amount_lte	number	No	numeric	Maximum income amount.	10000
revenue_amount_gte	number	No	numeric	Minimum revenue amount.	1000
revenue_amount_lte	number	No	numeric	Maximum revenue amount.	10000

Pagination

Control how many results are returned and move through result pages.

GET /charities?state=NC&limit=25&page=2

Result limits may vary by endpoint and API tier.

key	type	multi	example	default	description
limit	number	No	100	25	Sets the max number of returned items. Defaults to 25. Maximum depends on the endpoint and your API tier.
page	number	No	26	1	Sets the page.

Sorting

Use sort parameters to control result order.

The /charities endpoint supports sorting by public sortable fields. Use sortBy to choose the field and sortDir to choose ascending or descending order.

GET /charities?state=NC&sortBy=name&sortDir=asc&limit=25

For distance-based sorting, use /nearby and sort by distance_miles.

key	type	multi	validation	example	description
sortBy	string	No	enum	name	Sorts results by a supported public field. Enum in Fields section
sortDir	string	No	enum	asc	Sort direction. ENUM: asc or desc

Example: find animal-related nonprofits in North Carolina

Combine filters, sorting, field selection, and pagination.

GET /charities?state=NC&ntee_group=D&fields=ein,name,city,state,ntee_group&sortBy=name&sortDir=asc&limit=25