The Candid Generation II APIs consist of these APIs:

  1. The Essentials (Search) API
  2. The CharityCheck API
  3. The CharityCheck PDF API
  4. The CharityCheck Bulk API
  5. The Premier API

Version 1 of the APIs was released in January of 2018. This version uses the base URL of:

https://apidata.guidestar.org/{apiname}/v1

Version 2 of the APIs was released in January of 2019 and uses the same base URL with V2 replacing V1.

https://apidata.guidestar.org/{apiname}/v2

The Generation II APIs will be updated annually, with the release of a new version planned for January of each year.

Previous versions will be active and supported for 2 years.

Migrating from Candid API Generation II Version 1 to Version 2.

The differences between the Generation II Version 1 and Version 2 APIs are relatively minor, and any application that uses Gen II V1 APIs can be modified to use V2, in some cases, without modification. The changes from V1 to V2 are detailed here: https://apiportal.guidestar.org/api-static-documentation-v2. The yellow bar at the top of the page lists all the changes.

For the CharityCheck API, there is no change, and so the version number for CharityCheck remains V1 This includes the CharityCheck PDF and Bulk APIs. There is no change to the version number in the calling URL:  https://apidata.guidestar.org/charitycheck/v1/{ein}.

For Essentials, three new data filters and a new data element have been added. Since these changes are additions, existing JSON search queries may be used unchanged, and the return data may likely be deserialized without change in most applications. To use the new filters and logo_url, however, changes would be necessary.

  • Foundation Code Filter – Select all organization having a specific foundation code(s)
  • BMF Status Filter – Select all organizations with BMF Status = true (in BMF) or false (not in BMF). No selection means that this filter is not applied. 
  • Pub78 Verified Filter– Select all organizations with Pub 78 Status = true or false. No selection means that this filter is not applied. 
  • One new data element has been added:  Logo URL - Allows applications to retrieve and display an organization’s logo from GuideStar data

Premier API

The Premier API has significantly expanded data. Because these are deleted fields and changes in names, existing deserialization routines will fail unless they are modified.

Additions:

  • Most Recent 5 Years of IRS 990 EZ Financials
  • Added new 990 EZ fields to Current Year Financials
  • Most Recent 5 years of Financial Health Metrics
  • Unrestricted Net Assets, Net fixed Assets, and Mortgages to F990 and Current Year Financials
  • Months of Cash metric to Current Year Financials
  • Salary and Employee Benefit Expense from 990EZ to Current Year Financials
  • Platinum Evaluation Documents
  • Expanded Organizational Demographics
  • Date the Organization Was Last Listed on the IRS BMF
  • Date the Organization Was First Listed on the IRS BMF
  • Premier Pro PDF
  • Premier Financial Trend Analysis PDF

Other Premier Changes:

  • "gs_premium_pdf"renamed to "gs_pro_pdf"

       The full path of the link is "data": "summary": "gs_premium_pdf"

  • Removed "other_revenue" from F990 financials (duplicate field)

       The full path of the deleted data element is:          
       "financials":"f990_financials":"other_revenue"

  • "net_assets_eoy"renamed to "net_assets_end_of_year" in F990 financials

       The full path of the renamed data element is:
       "financials":"f990_financials":"net_assets_eoy"

  • "net_assetss"renamed to "net_assets" in PF990 financials

       The full path of the renamed data element is:
       "financials":"pf990_financials":"net_assetss"

Did this answer your question?