How to Use the CharityCheck REST API to Check Revocation Status

Document created by JackCowardin Administrator on Feb 2, 2017Last modified by JackCowardin Administrator on May 2, 2018
Version 9Show Document
  • View in full screen mode
    1. Note to API Users: 

      This page provides details about the the first generation GuideStar CharityCheck API, for which the calling URL is

    2.{organization EIN}
    3. GuideStar has  released a next generation of the CharityCheck API.  For more information about the new CharityCheck  API, and other GuideStar Next Generation APIs, and to request a free trial subscription, use this link:

    4. The "Free Trial" request link can be found at the bottom of the page.

      The Generation 1 CharityCheck REST API and the Next Gen (Gen 2) API returns essentially the same       data elements.

See the list for Gen 1 here.

See the Gen 2 list here.


Below is a discussion of the elements that are important for checking an organization's tax exempt status.


Two CharityCheck data elements that are indicators are:

  • pub78_verified  - this element should have the value "true" if an organization is in good standing with the IRS.
  • bmf_status  - should also have a value of  "true".

However, religious organizations, which are tax exempt by default, may not be  in the IRS Business Master File (BMF) or in the IRS Pub 78.


There are 3 reasons that an organization’s tax exempt status may be revoked by the IRS. API return fields to check are shown below for each reason, with the key element, the most important, highlighted:

  1. The organization has failed to file a Form 990 for three consecutive years. In this case, the organization will not be listed in the IRS Pub 78, which is updated monthly. The following CharityCheck API fields, normally null or empty, will have these values, of which revocation_code is the most important.

    A revocation_code value of "F" means the organizations exempt status has been revoked.



“F” for failure to file. A value of “R” indicates reinstatement.




The date of the last Pub 78 that included the organization.


The date of the revocation if revocation_code is “F”.


The date of reinstatement as tax exempt if revocation_code is “R”.


 2. The organization is revoked and does not appear in the IRS Bulletin (the IRB) which is issued weekly as a modification to Pub 78. For example, if a tax exempt organization engages in political activity, its tax exempt status may be revoked and it will not appear in the IRB.  In this case, the following CharityCheck API fields, normally null or empty, will have these values:



The number of the IRS Bulletin that includes the revocation notice.


The EIN of the organization that has been revoked.


The URL of the bulletin revoking tax exempt status


The date of the IRB that revokes tax exempt status.


 3. The organization's tax exempt status has been revoked by the Office of Foreign Asset Control (OFAC) because, for example, it has been determined by         OFAC that the organization contributes money to terrorist groups. In this case, the following CharityCheck API fields, normally null or empty, will have these    values:



The text describing the reason for revocation.


It is important to note that the most frequent revocation update is to the IRB and occurs weekly. In practice using the CharityCheck API once a month for each organization is sufficient. GuideStar API’s are “throttled” meaning that the number of calls allowed in a given period is limited. So calling any API several thousand times per month is not, in general, allowed by the terms of an API license. However, special terms can be granted if required by a customer application.