ProPublica

Journalism in the Public Interest

Cancel

Nonprofit Explorer API

ProPublica provides an application programming interface (API) to the search engine and database that powers Nonprofit Explorer.

Requests

The Nonprofit Explorer API uses a RESTful style. See individual methods below for permitted requests.

Constructing a Request

The Nonprofit Explorer API only accepts GET requests. All requests begin with https://projects.propublica.org/nonprofits/api/v1

Response Formats

The Nonprofit Explorer API responses are available in the json format. Responses are also available as jsonp by passing in a callback parameter.

The format of the JSON/JSONP response may sometimes be modified with the output parameter. (See the /search.json endpoint parameters, below.)

Parameters

Parameters are optional. Parameters vary by method. See individual methods below for valid parameters. Parameters, if provided, must be URL-encoded ("percent encoded").

Caveats

The Nonprofit Explorer API is a work in progress and is subject to change. Please consult this documentation page for the latest API developments.

GET /search.json

Parameters

All parameters are optional

Parameter Description
q

A keyword search string. Searches using this parameter will search (in order) organization name, organization alternate name, city.

Advanced queries can be crafted using the following rules. Parameters must be URL encoded.

page The (zero-indexed) page number of the request. Default is 0.
output The output of Filing objects may be modified with this parameter. Examples of the various types of output may be viewed here. Must be one of the following values:
order If provided, sorts results according to the alphabetical or numerical value of the given field. If you do not provide order, then results will be sorted based on relevance.
Note: sort_order MUST be set if order is is set. Using order without sort_order will result in undefined sorting behavior.

Must be one of the following values:
sort_order Must be one of the following values:
state[id] If provided, only return results from the given state or US Territory. Must use the two-letter U.S. Postal Service abbreviation. Code "ZZ" is used for entities based outside the United States required to file a Form 990 in the U.S. (Brackets should be URL encoded, i.e. state%5Bid%5D=NY)
ntee[id] If provided, only return results from the given National Taxonomy of Exempt Entities (NTEE) Major Group. Must be an integer, 1-10 — see codes below. (Brackets should be URL encoded, i.e. ntee%5Bid%5D=7)
Value NTEE Category
1Arts, Culture & Humanities
2Education
3Environment and Animals
4Health
5Human Services
6International, Foreign Affairs
7Public, Societal Benefit
8Religion Related
9Mutual/Membership Benefit
10Unknown, Unclassified
c_code[id] If provided, return only organizations categorized under the given subsection of section 501(c) of the tax code, with one special case for section 4947(a)(1). Must be an integer — see codes below. (Brackets should be URL encoded, i.e. c_code%5Bid%5D=3 for 501(c)(3) )
Value Tax Section
2501(c)(2)
3501(c)(3)
4501(c)(4)
5501(c)(5)
6501(c)(6)
7501(c)(7)
8501(c)(8)
9501(c)(9)
10501(c)(10)
11501(c)(11)
12501(c)(12)
13501(c)(13)
14501(c)(14)
15501(c)(15)
16501(c)(16)
17501(c)(17)
18501(c)(18)
19501(c)(19)
21501(c)(21)
22501(c)(22)
23501(c)(23)
25501(c)(25)
26501(c)(26)
27501(c)(27)
28501(c)(28)
924947(a)(1)

/search.json Result

Field Description Example values
total_results Total number organizations which match the search. 615836
num_pages Number of pages in the result set. 1, 3857
cur_page Zero-indexed number of the current page. 0
per_page Number of results that the API is returning per page. 25
page_offset Number of results on previous pages, useful as a running counter for listing results. 125
order The field that the database is sorting results with. (See Parameters, under the /search.json section, above.) null, "subseccd", "raw_name"
sort_order Whether order is sorted in ascending or descending order. null, "asc", "desc"
search_query The search query, if any. (See Parameters, under the /search.json section, above.) null, "delta -delta"
selected_state The state filter, if any. (See Parameters, under the /search.json section, above.) null, "NY"
selected_ntee The NTEE (category) filter, if any. (See Parameters, under the /search.json section, above.) null, 1, 10
selected_code The subsection code (501(c)(___) or 4947(a)(1)) filter, if any. (See Parameters, under the /search.json section, above.) null, 3, 10, 92
data_source Plain text citation of data sources. "ProPublica Nonprofit Explorer API: http://projects.propublica.org/nonprofits/api/\nIRS Exempt Organizations Business Master File Extract (EO BMF): http://www.irs.gov/uac/SOI-Tax-Stats-Exempt-Organizations-Business-Master-File-Extract-(EO-BMF)\nIRS Annual Extract of Tax-Exempt Organization Financial Data: http://www.irs.gov/uac/SOI-Tax-Stats-Annual-Extract-of-Tax-Exempt-Organization-Financial-Data"
api_version Version of the Nonprofit Explorer API that generated the JSON. 1
filings A Javascript array containing Filing objects that match the search. Note that results are paginated.  

Organization Method

GET /organizations/:ein.json

The Organization endpoint does not accept any query parameters, only the :ein value in the URL.

/organizations/:ein.json Result

Field Description Example values
organization Organization object containing profile data for the nonprofit with the given Employment Identification Number (EIN).  
data_source Plain text citation of data sources. "ProPublica Nonprofit Explorer API: http://projects.propublica.org/nonprofits/api/\nIRS Exempt Organizations Business Master File Extract (EO BMF): http://www.irs.gov/uac/SOI-Tax-Stats-Exempt-Organizations-Business-Master-File-Extract-(EO-BMF)\nIRS Annual Extract of Tax-Exempt Organization Financial Data: http://www.irs.gov/uac/SOI-Tax-Stats-Annual-Extract-of-Tax-Exempt-Organization-Financial-Data"
api_version Version of the Nonprofit Explorer API that generated the JSON. 1
filings_with_data A Javascript array containing Filing objects. These represent Form 990 filings by the organization, from various fiscal years.  
filings_without_data As above, but the Filing objects returned only contain the following fields: tax_prd, tax_prd_yr, pdf_url, formtype. These records represent raw filing documents available at Public.Resource.Org, but lacking extracted numerical data.  

Filing Object

The following fields exist in all Filing objects. An additional 40-120 rows of data are returned depending on which form type (Form 990, Form 990-EZ, Form 990-PF) is associated with the Filing.

An organization EIN may contain records for several years of filings processed by the IRS. Therefore, Filing objects are unique combinations of ein and tax_prd.

Field Description Example values
ein The employer identification number (EIN) for the organization associated with this tax filing. (Note: This value represents an integer value, so EIN values with leading zeroes will have the leading zeroes trimmed.) 142007220
tax_prd The tax period (month that the organization’s fiscal year ended) for the given Filing data. Integer in YYYYMM format. 201206
tax_prd_yr As above, but only the year portion. 2012
formtype Which Form 990 type this filing used. 0 (Form 990), 1 (Form 990_EZ), 2 (Form 990-PF)
updated Date that this filing data was updated in Nonprofit Explorer. Data is extracted from the IRS Annual Extract of Tax-Exempt Organization Financial Data. "2013-04-11T16:18:36Z"
organization An Organization object, representing the entity that filed this Form 990 with the IRS. Contains profile data such as name, EIN, address, nonprofit subsection category, etc. (Note: Only returned when using the Search endpoint. May not be returned if using a custom output option, see below.)  

If using output=flat, the "organization" field will not be returned. Instead, the keys listed under "Organization Object" (below) will be included as part of the Filing's data.

If using output=noorg, the "organization" field will not be returned. This metadata can be retrieved by using the Organization endpoint (see above).

Example uses of the various output options can be viewed here.

Filing Object: Basic financial data

The following fields are convenience aliases to common data points. (For example, total revenue (book value) is listed under one of "totrevnue", "totrevenue", or "totrcptperbks", depending on which form type is in question.)

Field Description Example values
totrevenue Total revenue -129347, 0, 1035696
totfuncexpns Total expenses ("Total functional expenses" for Form 990) -40281, 0, 983566
totassetsend Total assets, end of year 743704
totliabend Total liabilities, end of year 168361
pct_compnsatncurrofcr Percent of expenses marked as "Compensation of current officers, directors, etc" 0.023585

Filing Object: More financial data (formtype dependent)

An additional 40-120 rows are included on the Filing object. The exact fields depend on the form type (Form 990, Form 990EZ, Form 990PF), of the Filing object being returned. These rows contain all available data for the Filing in being returned.

Please consult the IRS' description of available fields if you need to work with these values; our API uses the "element name" described in that document.

Please remember that a search that doesn’t include a formtype will return Filings of all form types, so fields from Filing to Filing will be a mixed bag.

Example: You can look at the API result for q=propublica for a small (one result) example of what this looks like in practice.

Organization Object

Field Description Example values
ein The employer identification number (EIN) for the organization associated with this tax filing. (Note: This value represents an integer value, so EIN values with leading zeroes will have the leading zeroes trimmed.) 142007220
strein Version of the EIN in the "XX-XXXXXXX" format, containing leading zeroes if applicable. 14-2007220, 01-0191203
name Organization name, as provided by the IRS "PRO PUBLICA"
sub_name Secondary name, as provided by the IRS. This is generally used to provide an alias or a "subtitle" to an organization name. For sub-entities of national organizations, this may also be used to provide an identifier for the chapter. "", "LOCAL 342"
address "", "55 BROADWAY"
city "", "NEW YORK"
state "", "NY"
zipcode "", "10006-3008"
subseccd The subsection code (501(c)(___) or 4947(a)(1)) for this organization. For code values, see Parameters, under the /search.json section, above. 3, 92
ntee_code National Taxonomy of Exempt Entities (NTEE) category for this organization. See IRS documentation for possible values. "A20"
guidestar_url A link to the GuideStar profile for this organization. "http://www.guidestar.org​/organizations​/14-2007220/.aspx"
nccs_url A link to the National Center for Charitable Statistics profile for this organization. "http://nccsweb.urban.org​/communityplatform​/nccs/organization/profile​/id/142007220/"
updated Date that the Organization profile (name fields, address data, subsection code) was updated in Nonprofit Explorer. Data comes from the IRS Business Master File. "2013-04-11T15:41:23Z"

An additional 20 rows are included on the Organization object. These are further categorization and status codes within the IRS Exempt Organizations Business Master File Extract (EO BMF) that Nonprofit Explorer utilizes. A list of fields and possible values is available in the EO-BMF documentation.

Legal

Usage constitues agreement to our Data Terms of Use.

Questions? Comments?

Contact Mike Tigas: mike.tigas@propublica.org

Changelog

  • July 9, 2014. Added output=flat and output=noorg output formats. Documented page pagination option (now zero-indexed), and added "num_pages" to output. pdf_url removed - public.resource.org has removed public access to these files because of a dispute involving unredacted social security numbers.
  • June 11, 2014. Database update. More pdf_file links are now available.
  • April 30, 2014. Database update. New filing records based on newly-released raw filing data from the IRS ("Exempt Organization Returns Filed in Calendar Year 2013").
  • December 13, 2013. Database update. More pdf_file links now available.
  • September 26, 2013. Initial API release.

About This Data

Nonprofit Explorer includes nonprofit tax return data released by the IRS starting in April 2013 for tax returns processed by the IRS during 2012 and 2013. This generally consists of filings for the 2011 and 2012 fiscal years, but may include older records. The IRS data release includes only a subset of what can be found in the full Form 990s. Wherever possible, we've linked to PDFs of the full 990 for each organization, some going back ten years, collected at public.resource.org.

Which Organizations Are Here?

Every organization that has been recognized as tax exempt by the IRS has to file Form 990 every year, unless they make less than $200,000 in revenue and have less than $500,000 in assets, in which case they have to file form 990-EZ. Organizations making less than $50,000 don’t have to file either form but do have to let the IRS they’re still in business via an "e-Postcard."

Nonprofit Explorer has organizations claiming tax exemption in each of the 27 subsections of the 501(c) section of the tax code, and which have filed a Form 990, Form 990EZ or Form 990PF. Taxable trusts and private foundations that are required to file a form 990PF are also included.

Types of Nonprofits

There are 27 nonprofit designations based on the numbered subsections of section 501(c) of the tax code. See the list »

How to Research Tax-Exempt Organizations

We've created a guide for investigating nonprofits for those just getting started as well as for seasoned pros.

API

The data powering this website is available programmatically, via an API. Read the API documentation »

Download the Data

For those interested in acquiring the original data from the source, here’s where our data comes from:

  • IRS Raw filing data. Includes EINs and summary financials as structured data.
  • IRS Organization profiles. Includes organization names, addresses, etc. You can merge this with the raw filing data using EIN numbers.
  • Public.Resource.Org Bulk Form 990 PDFs. PDFs of Form 990s going back to 2000.