Frequently Asked Questions
The GuideStar APIs are RESTful. They are simple, predictable, and use standard HTTP response codes to indicate status and errors. We also use standard HTTP verbs, which are understood by all HTTP clients. All of our APIs return responses in JSON format.
For users requiring XML return data, there are numerous conversion utilities available on the web.
What are the GuideStar Next Generation APIs?
The GuideStar Next Generation APIs offer 3 services to meet the data needs of customers. They are:
Are the Next Generation APIs direct drop-in replacements for the original REST APIs? Will our old implementation of your APIs still work?
No, the GuideStar Next Generation APIs use a Microsoft Azure host and a new key-based authentication mechanism. The 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 Next Generation APIs is also new.
How does the Next Generation API Search using Essentials differ from the original REST Search API?
The GuideStar Essentials API (Elastic-based) is more structured than the Lucene-based Search API. A primary goal is to ensure that Search API results match the search results that are found on the GuideStar.org website.
While the last generation of APIs allowed free-form, keyword, and field-specific searching, the Next Generation of APIs 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.
Can I search the Essentials API using the GuideStar Organization ID?
The GuideStar Organization ID (organization_id in API return 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.
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
A free form term can also suffice as a very simple JSON search payload for Essentials
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
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. The Organization ID 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 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.
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 https://apiportal.guidestar.org/products.
Click on the name of API you wish to try.
A simple C# console application code example is here: https://github.com/GuideStar/Profile_API_Example
The GuideStar Community is a place where further information can be found, and where you can post questions to the user community and to GuideStar support engineers.
To sign up for free trial licenses, visit GuideStar APIs.
How is the Premier API queried?
The Premier API takes as a parameter the Organization ID 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.
What are the limits to the number of calls that can be made to the APIs?
GuideStar offer a Free Trial versions of each Next Generation API that allow up to 500 API calls per 60-day period. The maximum rate for these calls is 10 per minute. These are available for a period of 60 days but can be extended for longer period. Contact a sales representative for an extension. The Free Trial APIs include the Essentials, CharityCheck and CharityCheck PDF, and Premier APIs
The licensed APIs START at the following limits:
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 at a rate of 10 calls allowed per minute. Licensed API calls are throttled at a higher rate of 120 calls 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.
What is the guaranteed uptime?
GuideStar partners with Microsoft Azure to guarantee 99.9% uptime.
How do I access the API Sandbox?
The original Sandbox APIs have been replaced by a Free Trial product that offers limited access to the current GuideStar APIs. The Free Trial 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 APIs. Click the "Free Trial" button at the bottom of the page.
What is the difference between the 3 CharityCheck API options?
The CharityCheck API has 3 variants.
Why are Logo URLs available in the Search API but not in the Essentials API?
The next generation search, powered by the Essentials API, gives the user a search experience which aligns with the https://www.guidestar.org Pro search experience. The GuideStar Mainsite does not require a display of the logos in the search results page so the data field was never part of an index we currently use. We recognize that losing Logo URL was one of the compromises we had to make to better align our technologies, search capabilities, and results in the next generation APIs.
Why do I have both a Primary and a Secondary Key?
It is not a scenario often encountered, but if a primary API key for a subscription became compromised, or needed to be retired, the secondary key provides the opportunity to smoothly transition to a new key. Without the secondary key there would be a period between the regeneration of the primary key and the time an application could be updated to use the new key. During this period the API calls would not work. The primary and secondary API keys both work for the single URI.
An example of a time when a secondary key might be useful is if a contract developer, who has been using the primary key, completes a development project and you need to end their access to the API subscription.
The GuideStar Developer Portal
API Pricing & Free Trials
What if my question wasn't answered here?
Create a support case.