The GuideStar APIs are RESTful. They are simple, predictable, and use standard HTTP response codes to indicate statues and errors. We also use standard HTTP verbs, which are understood by all HTTP clients. All of our APIs' return responses are in JSON format.

For user’s requiring XML return data, there are numerous conversion utilities available on the web.

Candid announces the release of Version 2 of the Generation 2 APIs.

What’s new in Version 2?

  • Essentials APIThe Essentials (Search) API includes 3 new search filters that allow more fine-grained results, plus a link to an organization’s logo image for inclusion in applications that make use of the Essentials API to identify non-profits.
  • Foundation Code Filter – Allows limiting of results to specific types of non-profits, such as private operating foundations, Private nonoperating foundations, Churches, Schools, and Hospitals or medical research organizations.
  • BMF Status Filter – Limit results to organizations that are or are not listed on the most recent IRS Business Master File.
  • Pub78 Verified Filter – Limit results to organizations that are verified in IRS Publication 78.
  • Logo URL – an HTTP link to an image file that contains an organization’s logo.

Charity Check API

The CharityCheck API is unchanged and remains version 1. There is no CharityCheck V2 in this release of Candid APIs.

Premier API

  • Most Recent 5 Years of IRS 990 EZ Financials. - Previously, only Form 990 and Form PF 990 results were provided.
  • Most Recent 5 years of Financial Health Metrics. - Financial Health Metrics provide some analysis of the financial standing and trends for an organization.
  • Unrestricted Net Assets, Net fixed Assets, and Mortgages – These data have been added by customer request to the financial information provided in Premier for F990 returns and most current year financials.
  • Months of Cash metric added to most current year financials.
  • Salary and Employee Benefit Expense from 990EZ to most current year financials.
  • Platinum Evaluation Documents – Links to PDF documents that support an organization’s programs and the results of the programs, as they are listed in the Candid Profile Update Program data provided by the organization.
  • Expanded Organizational Demographics – expanded demographic information provided by the organization, where available.
  • Date the Organization Was Last Listed on the IRS BMF
  • Date the Organization Was First Listed on the IRS BMF 
  • Premier Pro PDF – A link to the PDF report for the organization.
  • Premier Financial Trend Analysis PDF – A link to a PDF document that shows the financial trends and health metrics for the organization.

Other Premier Changes:

  • "gs_premium_pdf" renamed to "gs_pro_pdf".
  • Removed "other_revenue" from F990 financials (duplicate field).
  • "net_assets_eoy" renamed to "net_assets_end_of_year" in F990 financials.
  • "net_assetss" renamed to "net_assets" in PF990 financials.

Some Helpful Links

We have a couple of helpful utilities on our Developer Portal that may make your development work easier.

The developer portal is at https://apiportal.guidestar.org/

There is a JSON query generator for use with the Essentials Search API here: https://apiportal.guidestar.org/search-request-json-helper

Also, the “Try It” function is available for all of the APIs from the “API Overview” menu choice, by clicking on the API name: https://apiportal.guidestar.org/products

For example, the “Try It” page for Essentials (Search) is at: https://apiportal.guidestar.org/docs/services/microservices.api.search/operations/59f8af13259f000a2cde9b2b/console

You can test out any JSON request body/search payload here to verify that it works with Essentials.

To test the Candid APIs, users will need a login to the developer portal at https://apiportal.guidestar.org. Request free trail access here:

https://learn.guidestar.org/products/api-free-trial-request

We are happy to work with you to optimize your API implementations and answer any technical questions. Just email apisupport@candid.org.

Frequently Asked Questions

1. What are the GuideStar Generation 2 APIs?

The GuideStar Generation 2 APIs offer 3 services to meet the data needs of customers. They are:

  • The Essentials APIEssentials is an Elastic Search-based API that provides a search function that duplicates the Search available on GuideStar.org
  • The CharityCheck APICharityCheck provides the latest data regarding the tax-exempt status of every nonprofit organization in the GuideStar database. There are three distinct services offered in the CharityCheck API set: CharityCheck, CharityCheck PDF, and CharityCheck Bulk.
  • The Premier API – The Premier API offers comprehensive data that corresponds to the data found on GuideStar.org, including Summary, Programs, Financials, and Operations data. A Premier Subscription includes the Essentials API and returns CharityCheck data within the Premier data return set.

2. Are the G2 APIs direct drop-in replacements for the original REST APIs? Will        our old implementation of your APIs still work?

  • No, the GuideStar Generation 2 APIs use a Microsoft Azure host and a new key-based authentication mechanism. The G2 Essentials Search is no longer based on Lucene, but uses the Elastic Search Engine and matches the architecture and results of the www.guidestar.org/search
  • The root URL for the G2 APIs is also new.

 3. How does the G2 API Search differ from the original REST Search API?

  • The GuideStar Generation 2 Essentials API (Elastic-based) is more structured than the Lucene-based G1 Search API. The primary goal is to ensure that Search API results match website search results.
  • While G1 allowed free-form, keyword, and field-specific searching, G2 also allows free-form searching, but utilizes a JSON search query construct that is submitted in the HTTP GET that makes up the request. 
  • The JSON query allows filters to be used in addition to free-form search terms. These include filters for geographic, NTEE, IRS Subsection, and other filters.
  • The 2019 Release of the Essentials search API includes new filters for Foundation Code, BMF Status, and Pub 78 Status.

 4. Can I search the Essentials API using the GuideStar Organization ID?

The GuideStar Organization ID (organization_id in API returns data) is an internal identifier employed in the GuideStar databases. It allows GuideStar to differentiate organizations that may share the same EIN, as occurs when parent organizations have subordinate organizations that share a Federal EIN. This value is subject to change. Although a change to an organization ID is rare, it can occur and so this value should not be stored as an identifier in external systems. Therefore, organization ID is not allowed as a search term in the Essentials API.

5. What are the best terms to use to search using the Essentials API?

The Essentials API requires, at a minimum, a “search term” supplied in JSON format. For example, an organization’s Federal Employer Identification Number (EIN) can be used, as in

search_terms {“54-1774039”}

A free form term can also suffice as a very simple JSON search payload for Essentials

search_terms {“cancer”}

For other search criteria, use the filters provided to limit result sets as in the example here: https://apiportal.guidestar.org/api-static-documentation-v1 and, for Essentials Version 2 users, here:  https://apiportal.guidestar.org/api-static-documentation-v2

6. What is the Premier API?

  • The Premier API delivers a large result that includes the data that can be found using the GuideStar.org website at https://www.guidestar.org.
  • The Premier API is called using the Organization ID, an internal GuideStar identifier, or the organization’s Federal Employer Identification Number (EIN). The Organization ID and /or the EIN is returned by the Essentials API as the result of a call to that API. Search by organization name, EIN, or using one of the filters provided in the Essentials search. 
  • Take the organization_id or the ein returned in the search results and use this to invoke the Premier API and receive comprehensive and complete data about any nonprofit that is in the GuideStar database.

7. Where can I find coding examples that show how to use the GuideStar APIs?

The GuideStar API Developer Portal https://apiportal.guidestar.org provides documentation for the APIs. Additionally, there are dynamic pages where you can try the APIs without writing any code at 

Some basic code examples are here: https://github.com/GuideStar/Profile_API_Example

To sign up for free trial licenses for the GuideStar APIs, visit https://learn.guidestar.org/products/api-free-trial-request

8. How is the Premier API queried?

The Premier API takes as a parameter the Organization ID or the EIN of the organization you are researching. The Organization ID is a GuideStar specific identifier that is found using the Essentials API. Essentials can be searched using a free text search term, the organization’s EIN, a search term (free text) with or without using one of the filters provided in the Essentials search.

9. What are the limits to the number of calls that can be made to the APIs?

GuideStar offers a Free Trial API that allows up to 250 API calls per month. These are available for a period of 60 days, and can be extended if necessary. The Free Trial includes the Essentials, CharityCheck and CharityCheck PDF, and Premier APIs

The licensed APIs allow these limits for Tier 1 subscriptions:

  • GuideStar Essentials API: up to 10,000 calls annually
  • GuideStar CharityCheck API: up to 20,000 calls annually
  • GuideStar Premier API (includes Essentials and Charity Check data): up to 50,000 calls annually.

Higher subscription Tiers offer more calls per annum.

10. What are the “throttling limits” for GuideStar APIs?

GuideStar “throttles” API calls to protect all API users so that no single API client can dominate the available bandwidth for calls and thus reduce access for other API customers. The Free Trial APIs are throttled to a low rate of 10 calls allowed per minute. Licensed API calls are throttled at a higher rate of 120 per minute. Throttling is not the same as a quota, which is applied as a limit to the number of calls that may be made monthly or annually.

If an application that incorporates a GuideStar Gen II API receives an HTTP 429 error, then the call rate is being exceeded. Applications developers may need to insert a sleep statement in the code. A 100 millisecond delay is a good starting point to slow down the rate of API calls. The optimal rate that works should be found experimentally by varying the pause duration. But the maximum pause will not need to exceed 500 milliseconds.

11. What is the guaranteed uptime?

GuideStar partners with Microsoft Azure to guarantee 99.9 percent uptime.

12. How do I access the API Free Trial?

The original Sandbox APIs have been replaced by a Free Trial product that offers limited access to the current GuideStar APIs. The Free Trial Sandbox allows up to 250 calls per month for a two month period for any of the APIs. These Free Trial products require registration and the assignment of an API key. Sign up for the Free Trial Sandbox APIs here: https://learn.guidestar.org/products/api-free-trial-request

13. What is the difference between the 3 CharityCheck API options?

The CharityCheck API has 3 variants. 

  • The basic CharityCheck API takes an organization’s EIN as a parameter and returns tax exempt status information about that organization.
  • The CharityCheck PDF API returns a binary data stream that can be stored and rendered as a PDF document.
  • The CharityCheck Bulk API takes as input a JSON structure that lists up to 25 comma-separated organization EINs. It returns a list of CharityCheck reports, one for each EIN specified. Here is a sample JSON for input to the CharityCheck Bulk API:  {"eins": ["54-1774039" "13-1644147" "43-0718808"] }

14. When will the next update to the GuideStar Next Generation APIs be                     released?  

The Release 2 of the GuideStar Next Gen APIs has been released. The next version, version 3 will be released at the end of January 2020. No details are available for the version 3 release. If you have suggestions for ways that we can make our APIs better please contact us and we will consider making the changes in the next release.

If you have any questions about APIs, please email us at apisupport@candid.org.

Did this answer your question?