Using the Essentials API to find the Organization ID used to call the Premier API

Document created by JackCowardin Administrator on Apr 3, 2018Last modified by JackCowardin Administrator on Apr 3, 2018
Version 4Show Document
  • View in full screen mode

Detailed instructions for calling the GuideStar Premier API.

 

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 GuideStar Premier API takes a single parameter, the organization ID of any non-profit organization (NPO) in the GuideStar database of more than 2.5 million organizations.

 

The organization ID is an internal GuideStar identifier that is found by first calling the GuideStar Essentials API, which is included as part of the Premium API product.

 

So calling the Premier API is a two-step process, unless you already know the organization_id of the NPO you want information about.

  1. Use the Essentials API to locate the brief record for the NPO.
  2. Use the organization_id field from the search results.
  3. Call the Premier API using that organization_id.

 

Here's an example of a 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

{
  "search_terms": "54-1774039",
}

How you actually POST this query to the GuideStar API Webserver is described in the GuideStar Developer Portal, where you can try searching without writing any code. 

Go to the GuideStar Essentials API Try It Page and click on the "Try It" button.

The query above returns this result, which includes the organization_id, 7831216:

{
  "code": 200,
  "message": "Request was processed successfully!",
  "took": 47,
  "errors": [],
  "data": {
    "took": 46,
    "total_hits": 1,
    "hits": [{
      "organization_id": "7831216",
      "bridge_id": "7349589081",
      "ein": "54-1774039",
      "organization_name": "GuideStar USA",
      "also_known_as": "GuideStar",
      "mission": "GuideStar USA, Inc.'s mission is to revolutionize philanthropy and nonprofit practice by providing information that advances transparency, enables users to make better decisions, and encourages charitable giving.",
      "address_line_1": "4801 Courthouse St",
      "address_line_2": "Ste. 220",
      "city": "Williamsburg",
      "state": "VA",
      "zip": "23188",
      "county": "James City",
      "msa": "VA - Norfolk-Virginia Beach-Newport News, VA-NC",
      "lat_long": "37.3268,-76.7606",
      "ntee_code": "T50 Philanthropy / Charity / Voluntarism Promotion (General)",

 

The Essentials API provides a mechanism for searching by EIN, as in the example above, or by free text searching. The application of certain 'filters" can also be used to narrow the range of search results. These filters include:

 

 

Here is the full JSON framework of an Essentials API Search query:

{
  search_terms: "",
  from: 0,
  size: 25,
  sort: {
    sort_by: "",
    ascending: true
  },
  filters: {
    geography: {
      state: [],
      zip: "",
      radius: 0,
      msa: [],
      city: [],
      county: []
    },
    organization: {
      profile_levels: [],
      ntee_major_codes: [],
      ntee_minor_codes: [],
      subsection_codes: [],
      affiliation_type: {
        parent: false,
        subordinate: false,
        independent: false,
        headquarter: false
      },
      specific_exclusions: {
        exclude_revoked_organizations: false,
        exclude_defunct_or_merged_organizations: false
      },
      number_of_employees_range: {
        min: 0,
        max: 0
      },
      form_types: {
        f990: false,
        f990pf: false,
        required_to_file_990t: false
      },
      audits: {
        a_133_audit_performed: false
      }
    },
    financials: {
      total_revenue: {
        min: 0,
        max: 0
      },
      total_expenses: {
        min: 0,
        max: 0
      },
      total_assets: {
        min: 0,
        max: 0
      }
    }
  }
}
               

 

However, in its simplest form, it can be as short as this example:

{
  "search_terms": "cancer",
}

 

This simple query returns 10,437 "hits", each of which contains the organization_id required to call the Premier API:

 

{
  "code": 200,
  "message": "Request was processed successfully!",
  "took": 437,
  "errors": [],
  "data": {
    "took": 435,
    "total_hits": 10437,
    "hits": [{
      "organization_id": "6908061",
      "bridge_id": "6412491372",
      "ein": "13-1788491",
      "organization_name": "American Cancer Society, Inc.",
      "also_known_as": "NATIONAL HOME OFFICE",
      "mission": "The American Cancer Society's mission is to save lives, celebrate lives, and lead the fight for a world without cancer.",
      "address_line_1": "250 Williams Street NW",
      "address_line_2": "",
      "city": "Atlanta",
      "state": "GA",
      "zip": "30303",
      "county": "Fulton",
      "msa": "GA - Atlanta",
      "lat_long": "33.7506,-84.3877",
      "ntee_code": "P20 Human Service Organizations",
etc....

 

Once you have received a result set from your search query, you can add filters to narrow the results. In this example, we add a State Filter of "GA" and a city filter of "Atlanta". We could use the zip code feature with a radius to limit the results further. We also sort by organization_name in ascending alpha order:

 

{
  "search_terms": "cancer",
  "from": 0,
  "size": 100,
  "sort": {
    "sort_by": "organization_name",
    "ascending": true
  },
  "filters": {
    "geography": {
      "state": [
        "GA"
      ],
      "city": [
        "Atlanta"
      ],
    }
}

 

Using the organization_id above, 6908061, to call the Premier API, using the URL

https://apidata.guidestar.org/premier/v1/6908061

we get these results:

 

{
  "code": 200,
  "message": "Request was processed successfully!",
  "took": 444,
  "errors": [],
  "data": {
    "summary": {
      "organization_id": 6908061,
      "organization_name": "American Cancer Society, Inc.",
      "ein": "13-1788491",
      "bridge_id": "6412491372",
      "address_line_1": "250 Williams Street NW",
      "address_line_2": "",
      "city": "Atlanta",
      "state": "GA",
      "zip": "30303-1032",
      "fax": "",
      "govt_registered_name": "American Cancer Society Inc",
      "also_known_as": null,
      "fiscal_year_end": "Dec 31",
      "fiscal_year_start": "Jan 1",
      "affiliation_code": "6",
      "affiliation_description": "Central - This code is used if the organization is a parent (group ruling) and is not a church or 501(c)(1) organization.",
      "contact_name": "Catherine Mickle",
      "contact_title": "Chief Financial Officer",
      "contact_email": "catherine.mickle@cancer.org",
      "contact_phone": "404-329-7934",
      "contact_fax": "-",
      "gs_profile_update_level": "Gold 2017",
      "gs_profile_update_level_logo": "https://www.guidestar.org/App_Themes/MainSite2/images/ProfilePageSvgs/guideStarSeal_2017_gold_SM.svg",
      "deductibility_code": "1",
      "deductibility_description": "Contributions are deductible, as provided by law",
      "donation_to_ein": "",
      "donation_to_name": "American Cancer Society, Inc.",
      "areas_served_narrative": "",
      "ruling_year": "1942",
      "gs_public_report": "https://www.guidestar.org/profile/13-1788491",
      "gs_premium_pdf": "Coming Soon",
      "impact_statement": "",
      "incorporation_year": "1913",
      "subsection_code": "03",
      "subsection_description": "501(c)(3) Public Charity",
      "keywords": "cancer, research, prevention, detection, advocacy, education, service",
      "logo_url": "https://www.guidestar.org/ViewEdoc.aspx?eDocId=3850802&approved=True",
      "mission": "The American Cancer Society's mission is to save lives, celebrate lives, and lead the fight for a world without cancer.",
      "is_national_hq": false,
      "ntee_code": "P20 - Human Services",
      "website_url": "http://www.cancer.org",
      "year_founded": "1913",
      "year_incorporated": "1913",
      "addresses": [{
        "address_line_1": "250 Williams Street NW",
        "address_line_2": "",
        "city": "Atlanta",
        "state": "GA",
        "postal_code": "30303-1032",
        "country": "USA",
        "address_type": "Main Address"
      },

Results continue with much more data...

 

Once again, you can try out the Premier API. Use this link:

GuideStar Premier API Try It Page

Click on the "Try IT" button, use the organization_id 6908061 and see the results.

Attachments

    Outcomes