GuideStar APIs

Document created by communitymanager Administrator on Dec 10, 2015Last modified by JackCowardin on May 22, 2017
Version 59Show Document
  • View in full screen mode

The GuideStar APIs deliver comprehensive current data from GuideStar's database of Nonprofit and Charitable Organizations and Foundations. Return data is available in either JSON or XML

 

The GuideStar API site provides 3 ways to get started:

 

1. GuideStar Production APIs

GuideStar Production APIs are subscription-based, and include:

  • CharityCheck,
  • CharityCheck PDF,
  • Detail,
  • Exchange (Profile Update Program data)
  • and Search.

(described below)

 

2. The GuideStar QuickStart API

GuideStar QuickStart APIs are free APIs intended to provide developers with an easy way to experiment with the integration of GuideStar data into existing applications. The Quickstart APIs provide two interfaces:

  • QuickstartSearch API allows keyword and wildcard searches.
  • QuickstartDetail API provides a fixed-format data set in either XML or JSON format.

Software that integrates these APIs can be quickly modified to use any of GuideStar's production APIs. Learn more…

 

3. The GuideStar API Sandbox

The API Sandbox provides complete API functionality with a limited data set. API users can use this site to prototype software for demonstrations or in anticipation of becoming a paid subscriber to the full-data version of Guidestar's APIs. Developers should note that this data is not guaranteed to be current and is refreshed only on occasion. The interfaces and functionality are identical to the production versions. Learn more…

 

GuideStar Production APIs

 

 

API Code Examples

Use these code examples as suggestions for coding API access using cURL, C# .NET, Java, Ruby, or PHP. These examples use the search API. Use these examples as a template and substitute the URL from the tables below for the API you need.

Example Data Classes for API Return Data

Use these classes to hold deserialized API data

 

Note About Using GuideStar API Keys - Authentication

What is an API Key? Why and how should I use one?

 

Note about calling GuideStar APIs from Javascript or other client-side scripting.

This is considered to be unsafe because it removes access control for the APIs.

 

GuideStar Charity Check API 

GuideStar CharityCheck is the only pre-grant due-diligence tool that is 100% compliant with IRS requirements.

The GuideStar CharityCheck API provides this essential data via our REST API in XML or JSON formats.

 

Requests

ExampleDescription
https://data.guidestar.org/v3/charitycheck/{EIN}.{xml/json}https://data.guidestar.org/v3/charitycheck/54-1774039.xml 


Request CharityCheck API information for GuideStar (EIN 54-1774039) with results in XML.

GuideStar Charity Check API XML Results

https://data.guidestar.org/v3/charitycheck/54-1774039.json


Request CharityCheck API information for GuideStar (EIN 54-1774039) with results in a JSON format.

GuideStar Charity Check API JSON Sample Results

Available Fields

  • organization_info_last_modified
  • ein
  • organization_id
  • organization_type_2
  • organization_name
  • organization_name_aka
  • addressline_1
  • addressline_2
  • city
  • state
  • state_name
  • zip
  • charity_check_last_modified
  • pub78_organization_name
  • pub78_ein
  • pub78_verified
  • pub78_city
  • pub78_state
  • organization_type_1
  • deductibility_limitation_1
  • pub78_indicator
  • deductibility_status_description_code_1
  • _status_description_code_2
  • organization_type_2
  • deductibility_limitation_2
  • deductibility_status_description_code_3
  • organization_type_3
  • deductibility_limitation_3
  • deductibility_status_description_code_4
  • organization_type_4
  • deductibility_limitation_4
  • deductibility_status_description_code_5
  • organization_type_5
  • deductibility_limitation_5
  • deductibility_status_description_code_6
  • organization_type_6
  • bmf_subsection
  • subsection_description
  • deductibility_limitation_6
  • deductibility_status_description_code_7
  • organization_type_7
  • deductibility_limitation_7
  • most_recent_pub78
  • most_recent_irb
  • bmf_organization_name
  • bmf_ein
  • bmf_status
  • most_recent_bmf
  • foundation_code
  • foundation_code_description
  • ruling_month
  • ruling_year
  • adv_ruling_month
  • adv_ruling_year
  • group_exemption
  • exemp_status_code
  • ofac_status
  • revocation_code
  • revocation_date
  • reinstatement_date
  • irs_bmf_pub78_conflict
  • foundation_509a_status
  • irb_organization_id
  • bulletin_number
  • bulletin_url
  • effective_date
  • irb_last_modified

 

GuideStar Charity Check PDF API 

The GuideStar CharityCheck PDF API allows user applications to retrieve a binary data stream that can be saved and rendered as an Adobe PDF document.  The calling program must invoke a PDF-enabled browser or the Adobe Acrobat application to display the PDF.

 

An example of how to invoke the CharityCheck PDF in C# is here. The first part explains the deprecated SOAP web service. The second part describes the REST API for the CharityCheck PDF:

Web Service To REST API Conversion - CharityCheck PDF Example 

 

Requests

 

 

GuideStar Exchange API

The GuideStar Exchange API combines nonprofit-supplied information with data from other sources to provide comprehensive information about millions of organizations. Organizations that choose to participate in the GuideStar Profile Update Program (formerly "GuideStar Exchange") provide additional data that is more comprehensive than the data GuideStar collects from the IRS Returns for an organization. This data is made available through the Exchange API.

 

Use the GuideStar Search API with an organization's EIN to find the Organization ID.

 

Requests

ExampleDescription
https://data.guidestar.org/v3/exchange/{OrganizationID}.{xml/json}https://data.guidestar.org/v3/exchange/7831216.xml


Request Exchange API data for organization ID 7831216 with result in XML. (GuideStar Exchange API XML Sample Results)

https://data.guidestar.org/v3/exchange/7831216.json


Request Exchange API data for organization ID 7831216 with result in JSON format.(GuideStar Exchange API JSON Sample Results)

 

Available Fields

  • GuideStar Organization ID
  • EIN (Government issued ID)
  • Bridge ID
  • Primary Organization Name
  • AKA Name
  • Doing Business As
  • Formerly Known As (list)
  • Doing Business As
  • Government Registered Name
  • IRS Subsection Code
  • IRS 509a Status
  • Organization Logo Url
  • Logo Name
  • Government Issued Ruling Year
  • Year Founded
  • Incorporation Year
  • Keywords
  • Mission Statement
  • Geographic Areas Served (list)
  • Geographic Areas Served Narrative
  • Impact Statement
  • CEO Comments
  • GuideStar Profile Level
  • Primary Telephone
  • Fax
  • International Telephone
  • Primary Address
  • Physical Address
  • International Address
  • Website URL
  • Blog URL
  • Social media URLs
  • Organization Email
  • NTEE Codes (list)
  • Fiscal Year Start
  • Fiscal Year End
  • Contributions Gifts and Grants
  • Program Service Revenue
  • Membership Dues
  • Net Income from Special Event
  • Total Revenue
  • Program Expenses
  • Description of Other Revenue
  • Amount of Other Revenue
  • Administration Expenses
  • Fundraising Expenses
  • Payments to Affiliates
  • Description of Other Expense
  • Amount of Other Expense
  • Total Expenses
  • Total Assets
  • Total Liabilities
  • Net Assets End of Year
  • Primary Contact
  • Executive Director
  • CoExecutive Director
  • Board Chair
  • Board CoChair
  • Board Members (list)
  • Senior Staff (list)
  • Letter of Determination document
  • Letter of Dissolution document
  • Other Staff (list)
  • Programs (list)
  • Financial Statement documents (list)
  • Annual Report documents (list)
  • Form 990 documents (list)
  • Form 990T documents (list)
  • Form 1023/1024 documents (list)
  • Other documents (list)
  • Funding Sources (list)
  • Funding Needs (list)
  • Accreditations (list)
  • Awards (list)
  • Affiliations (list)
  • Charting Impact Answers
  • Videos (list)
  • Photos (list)
  • Notes
  • Board Source Answers
  • Demographics Details

 

 

GuideStar Detail API

The GuideStar Detail API combines nonprofit-supplied information with data from other sources to provide comprehensive information about millions of organizations.

Requests

ExampleDescription
https://data.guidestar.org/v1/detail/{OrganizationId}.{xml/json}https://data.guidestar.org/v1/detail/7831216.xml


Request Detail API data for GuideStar (organization ID 7831216) with result in XML.

GuideStar Detail API XML Sample Results

https://data.guidestar.org/v1/detail/7831216.json


Request Detail API data for organization ID 7831216 with result in JSON format.

GuideStar Detail API JSON Sample Results

 

Available Fields

  • GuideStar Organization ID
  • EIN
  • Organization Name
  • Address Line 1
  • Address Line 2
  • City
  • State
  • Zip + 4
  • Affiliation Code and Description
  • AKA Name
  • Total Assets
  • Contact Fax
  • Contact Phone
  • Deductibility Code and Description
  • Total Expenses
  • Foundation Code and Description
  • Group Exemption
  • Total Income
  • IRS Subsection Code and Description
  • National Headquarters Indicator
  • Total Liabilities
  • Mission Statement
  • Geographic Areas Served (list)
  • Telephone
  • Link to organization's public report on GuideStar's website
  • Ruling Year
  • Tax Year
  • Website url
  • Year Founded
  • NTEE Codes (list)
  • Total Revenue
  • CEO and Co-Ceo
  • Programs (list)

 

 

GuideStar Search API Version 1_1.

Search GuideStar's data about nonprofits and quickly find organizations most relevant to your needs. You can use those results to get more data from our other APIs.

 

GuideStar’s Search APIs use the Lucene Search Engine and there is a good deal of technical information about using the Lucene API query syntax available on the internet. For example see: lucene.apache.org queryparsersyntax.html

 

Some technical details of the Search API can be found here.

 

Here are some examples of how to make basic calls using the GuideStar Search API:

 

Parameters

ParameterExplained
qThe 'q' parameter is the main query for the request.
pThe 'p' parameter is used to paginate results from a query where each page has "r" NPOs (see 'r' parameter). The 'p' parameter specifies which "page" of "r" NPOs should be returned. The default value is 1 and returns NPOs 1..r. A query with p=2&r=5 returns NPOs 6-10 from the overall return set for the query. This allows users to obtain as many return results for a particular query as desired.
r

The 'r' parameter specifies the number of NPOs returned on each page for values of 1 through 25. The default is 10 NPOs per page.

 

An implementation of the Search API that displays 50 or 100 results would need to make 2 calls with an "r" parameter of 25 (e.g., "&r=25") to get 50 results or 4 calls to get 100 results. The results can be stored in a list in the calling program and then displayed once the results are compiled.

Requests

ExampleDescription
https://data.guidestar.org/v1_1/search?q=ein:54-1774039Search for an organization with an EIN = 54-1774039
https://data.guidestar.org/v1_1/search?q=irs_foundation_code:15

Search for all organizations with an IRS Foundation Code = 15

(Foundation Code Sample Results)

https://data.guidestar.org/v1_1/search?q=irs_foundation_code:15&p=2Search for IRS Foundation Code = 15 and return "page" 2 of the result
https://data.guidestar.org/v1_1/search?q=irs_foundation_code:15&r=5Search for IRS Foundation Code = 15 and return 5 results
https://data.guidestar.org/v1_1/search?q=irs_foundation_code:15&p=2&r=5Search for IRS Foundation Code = 15 and return 5 results of "page" 2
https://data.guidestar.org/v1_1/search.json?q=irs_foundation_code:15

Search for IRS Foundation Code = 15 and return JSON format

(Foundation Code Sample Results JSON Format)

Search API 1_1 Wild Card Search Results Example

Search API 1_1 Zip Code Search Results Example

 

Available Fields

  • organization_id
  • ein
  • organization_name
  • mission
  • city
  • state
  • zip
  • nteecode
  • participation
  • public_report
  • irs_subsection
  • irs_foundation_code
  • msa
  • logo_url
  • national_hq
  • website
  • parents
  • bmf
  • pub78
  • revocation
  • organization_name_aka
  • online_giving_flag
  • gs_donation_optin

 

MSA Code List

Advanced Search API MSA Code List

Subsection Code List

Advanced Search API Subsection Code List

 

 

Return Codes

ErrorExplained
200OK, all went through!
401Unauthorized, returned when the request requires user authentication. The response header will include WWW-Authenticate header realm "GuideStar Middleware API"
403Forbidden, returned when the API understood the request, but is refusing to fulfill it. Most commonly, this means that the user has exceeded their request limit or does not have permissions to access this API.
404There is an error in the URL string or the requested organization Id is not available.
500Server Error, returned when the API encountered an unexpected condition which prevented it from fulfilling the request. A generic message (security reasons) will be displayed to the consumer but a detailed exception will be logged on API side.
503Service Unavailable, returned when the API is unavailable to handle the request due to a temporary overloading or maintenance of the server. The existence of the 503 status code does not imply that we will be using it on a regular basis. It is here to cover rare cases only so that we can message and inform consumers if needed.

Attachments

    Outcomes