The GuideStar APIs are RESTful. They are simple, predictable, and uses 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.

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.

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

6. What is the Premier API?

  • 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, or using any one of the filters provided—Geography, NTEE Codes, IRS Subsection, etc.

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.

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 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 next release of the GuideStar Next Gen APIs is scheduled for the end of January 2019. Essentials will have some additional filters and data fields. Premier will have expanded data including 990 EZ data which was not previously included.


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

Did this answer your question?