GuideStar API Sandbox

Document created by communitymanager Administrator on Feb 25, 2016Last modified by JackCowardin on May 31, 2017
Version 29Show Document
  • View in full screen mode

The API Sandbox provides complete API functionality with a limited data set. API developers 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, however, are identical to the production versions.

GuideStar Sandbox APIs are free to use. However, a license and authentication keys are required. 

 

Use this link to signup for GuideStar Sandbox API licenses.

 

How to sign up for GuideStar Sandbox APIs 

 

 

 

Using GuideStar API Keys - Authentication 

Description of API keys and how to use them for authentication


GuideStar Charity Check API

GuideStar Charity Check is the only pre-grant due-diligence tool that is 100% compliant with IRS requirements. The GuideStar Charity Check API provides this essential data via our RESTful API in XML or JSON formats.

Available Fields

  • organization_info_last_modified

  • ein

  • 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

  • pub78_indicator

  • organization_id

  • deductibility_status_description_code_1

  • organization_type_1

  • deductibility_limitation_1

  • deductibility_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

  • 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

  • bmf_subsection

  • subsection_description

  • 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

Requests

The default return format for Guidestar APIs is JSON.

GuideStar Exchange API

Available Fields

  • GuideStar Organization ID
  • EIN
  • Primary Organization Name
  • AKA Name
  • Formerly Known As (list)
  • Doing Business As
  • Government Registered Name
  • IRS Subsection Code
  • IRS 509a Status
  • Organization Logo Url
  • Logo Name
  • Logo Link
  • Government Issued Ruling Year
  • Year Founded
  • Incorporation Year
  • Keywords
  • Mission Statement
  • Geographic Areas Served Narrative
  • Geographic Areas Served (list)
  • Impact Statement
  • CEO Comments
  • Primary Telephone
  • Net Assets End of Year
  • Funding Source(s)
  • Executive Director
  • CoExecutive Director
  • Board Chair
  • Board CoChair
  • 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 Events
  • Description of Other Revenue
  • Amount of Other Revenue
  • Total Revenue
  • Program Expenses
  • Administration Expenses
  • Fundraising Expenses
  • Payments to Affiliates
  • Description of Other Expense
  • Amount of Other Expense
  • Total Expenses
  • Total Assets
  • Total Liabilities
  • Board Members (list)
  • Senior Staff (list)
  • Other Staff (list)
  • Programs (list)
  • Letter of Determination document
  • Letter of Dissolution document
  • 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)
  • Awards (list)
  • Accreditations (list)
  • Affiliations (list)
  • Charting Impact Answers
  • Videos (list)
  • Photos (list)
  • Board Source Answers
  • Demographics Details

 

Request Examples

The default return format for Guidestar APIs is JSON. Append ".xml" to the request to receive the results in XML.

Use the Search API with an EIN to find the organization ID.

 

ExampleDescription
https://Sandboxdata.guidestar.org/v3/exchange/{OrganizationId}.{xml/json}

https://Sandboxdata.guidestar.org/v3/exchange/7831216.xml

 

Request GuideStar Exchange data for organization ID 7831216 and give me the result in well-formedXML.

(GuideStar Exchange API Sandbox - XML Sample Results)

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

 

Request GuideStar Exchange data for organization ID 7831216 and give me the result in JSON format.

(GuideStar Exchange API Sandbox - JSON Sample Results)

GuideStar Search API

Search 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

 

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

 

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
  • online_giving_flag

 

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 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 results.
rThe r parameter specifies the number of NPOs returned on each page for values of 1 through 25. The default is 10 NPOs per page.

Requests

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

Search for all organizations with an IRS Foundation Code = 15

(Sandbox Foundation Code Sample Results)

https://Sandboxdata.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://Sandboxdata.guidestar.org/v1_1/search?q=irs_foundation_code:15&r=5Search for IRS Foundation Code = 15 and return 5 results
https://Sandboxdata.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://Sandboxdata.guidestar.org/v1_1/search.json?q=irs_foundation_code:15

Search for IRS Foundation Code = 15 and return JSON format

(Sandbox Foundation Code Sample Results JSON Format)

Search API Code Lists

 

 

GuideStar Detail API

 

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)

Requests

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

https://Sandboxdata.guidestar.org/v1/detail/7831216.xml

 

Request data for organization Id 7831216 and get the result in well-formed XML. (GuideStar Detail API Sandbox - XML Sample Results)

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

 

Request data for organization Id 7831216 and give me the result in JSON format. (GuideStar Detail API Sandbox - JSON Sample Results)

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.

 

GuideStar API Sandbox - Code Examples

1 person found this helpful

Attachments

    Outcomes