Retrieve organization profile information and search for organizations matching query criteria
In this help article...The Cause IQ API enables you to access the industry-leading nonprofit data of Cause IQ directly in machine-readable formats. With the Cause IQ API, you can retrieve information on specific organizations and conduct programmatic searches to retrieve organizations that match specific criteria. The API is a REST API, returns JSON responses, authenticates with API keys via the Authorization header, and uses industry-standard HTTP response codes.
There are two API endpoints currently, created to help with the most common tasks of our customers:
The Cause IQ API requires a Cause IQ subscription, and is included with the Data Enrichment Add-on, which also includes our CSV Upload matching tool and the Salesforce Integration. If you already have the Data Enrichment Add-on, just reach out to your support contact!
Cause IQ uses API keys to authenticate your requests, via the "Authorization" HTTP header. In your GET request, include the "Authorization" key with a value of "Token" and your API, with a whitespace between the two. For example:
Authorization: Token 5029a02959w58hja9305og928ao2h3xoghd9ba5p
Generate your API key within the "API" section of your Cause IQ Account Settings page. If you don't see an "API" section, contact Cause IQ support.
Unauthenticated responses will result in an HTTP 401 "Unauthorized" response. All requests must be made using HTTPS.
The Cause IQ API has usage limits that mirror your existing usage limits for exports and enrichments. Each organization profile retrieved via the API counts as one record exported. As with exports, if you pull the same organization multiple times within a 30-day window, it only counts against your usage once. For the organization search API, search results are not currently rate limited.
To see your limits, either go to your Cause IQ Dashboard, or check the headers of the API response, which will contain the following:
x-rate-limit-limit
: the rate limit ceiling for that given endpointx-rate-limit-remaining
: the number of requests left in your usage periodx-rate-limit-reset
: how many seconds until your usage period resetsIf you go over your included usage, the response will be HTTP 429 "Too Many Requests".
The organization profile API allows you to retrieve information on a specific nonprofit organization using its EIN. Send a GET request to the following endpoint, replacing ":ein" with the organization's EIN (without any dashes, just a nine-digit string):
GET https://www.causeiq.com/api/organizations/:ein/
For example, here's what a request looks like in Python:
import os import requests ein = "530242652" url = "https://www.causeiq.com/api/organizations/{ein}/".format(ein=ein) headers = { "Authorization": "Token {api_key}".format(api_key=os.environ["CAUSEIQ_API_KEY"]) } response = requests.get( url=url, headers=headers ) org_data = response.json()
The response is a JSON representation of the organization, containing 20 of the most commonly-requested fields in Cause IQ on the organization. Here are the fields:
ein
: The EIN of the organization, without any dashesname
: The common / trade name of the organizationother_names
: Other names the organization has gone by, including legal names, previous names, or other names reported on past Form 990s and other disclosures. List of stringsphone
: The office phone number for the nonprofitwebsite_url
: The URL of the website for the organization (e.g., "https://www.nature.org/en-us/")address
: Primary location of the organization. Object containing attributes for the street, city, state, zip code, and (if located in one) the metropolitan area (CBSA) of the organization. The metro area is an object itself, containing the CBSA value (e.g., 47900) and the string name of that metro area (e.g., "Washington-Arlington-Alexandria, DC-VA-MD-WV")description
: A short description of the organization. String, 255 characters or lessntee
: The primary NTEE classification of the organization, determined by Cause IQ analysis of the organization. Object containing two attributes, "value" for the code itself (e.g., "C34") and "label" for the descriptive text of that code (e.g., "Land Resources Conservation"). Note that labels may change over time501_c_type
: The IRS 501(c) subsection type for the organization (e.g., "501(c)(6)")form990_type
: The type of the Form 990 that this organization filled out (i.e., "Form 990-EZ", "Form 990", "Form 990-PF", "Form 990-N / Postcard")year_formed
: The year the nonprofit was formed or formally recognized by the IRS. Integerfiscal_year_end
: The month of the fiscal year end for the organization. String containing the proper name of the month (e.g., "December")most_recent_tax_period
: The year and month of the most recent Form 990 we have for the organization. String containing year and zero-padded month decimal, separated by a dash (e.g., "2018-12")pub78_eligible_tax_deduction
: Whether the organization can receive tax deductible donations, as reported on IRS Publication 78. Booleancauseiq_url
: The URL for the Cause IQ profile of the organizationemployees
: The number of employees the organization has, as reported on the most recent Form 990. Object containing "value" for the number of employees, and "one_year_growth" for the year-over-year growth in employeesrevenues_total
: Most recent total revenues for the organization. Object containing "value" for the total revenues itself, and "one_year_growth", which is the growth in revenues over the previous yearexpenses_total
: Most recent total expenditures of the organization. Object containing "value" for the total expenses itself, and "one_year_growth", which is the growth in expenses over the previous yearassets_total
: Most recent total assets of the organization. Object containing "value" for the assets itself, and "one_year_growth", which is the growth in assets over the previous yearliabilities_total
: Most recent total liabilities for the organization. Object containing "value" for the amount of total liabilities, and "one_year_growth", which is the growth in liabilities over the previous yearHere's an example of the response object with the above default fields:
{ 'ein': '530242652', 'name': 'Nature Conservancy', 'other_names': [], 'phone': '(703) 841-5300', 'website_url': 'https://www.nature.org/en-us/', 'address': { 'city': 'Arlington', 'metro': { 'label': 'Washington-Arlington-Alexandria, DC-VA-MD-WV', 'value': '47900' }, 'state': 'VA', 'street': '4245 Fairfax Drive', 'zip': '22203' }, 'description': 'Nature Conservancy is a land resources conservation in Arlington, VA whose mission is: The mission of The Nature Conservancy is to conserve the lands and waters on which all life depends.', 'ntee': { 'label': 'Land Resources Conservation', 'value': 'C34' }, '501_c_type': '501(c)(3)', 'form990_type': 'Form 990', 'year_formed': 1951 'fiscal_year_end': 'June', 'most_recent_tax_period': '2018-06', 'pub78_eligible_tax_deduction': True, 'causeiq_url': 'https://www.causeiq.com/organizations/nature-conservancy,530242652/', 'employees': { 'one_year_growth': 0.015357939063661119, 'value': 4099 }, 'revenues_total': { 'one_year_growth': 0.17728214640160053, 'value': 1184630698 }, 'expenses_total': { 'one_year_growth': 0.09411288632100125, 'value': 907553872 }, 'assets_total': { 'one_year_growth': 0.05980159866621637, 'value': 7409864700 }, 'liabilities_total': { 'one_year_growth': 0.05377335144784334, 'value': 811391555 }, }
If you want to retrieve fields that are not provided above, simply add a fields
query parameter with a comma-separated string of field names that you want to retrieve. The response will still include name
and ein
, but everything else will be the field values you requested (for a list of fields available, please get in touch with your Cause IQ contact). Here's what a Python request with custom fields looks like:
response = requests.get( url=url, headers=headers, params={ "fields": "revenues_program_services,expenses_all_salaries_employee_benefits,naics" } )
Here's what the response to the above request looks like:
{ 'ein': '530242652', 'name': 'Nature Conservancy', 'expenses_all_salaries_employee_benefits': { 'value': 399350969 'one_year_growth': 0.05463996514369884, 'percent_total': 0.44003004264632783 }, 'naics': { 'value': '813312' 'label': 'Environment, Conservation, and Wildlife Organizations', }, 'revenues_program_services': { 'value': 115642257, 'one_year_growth': -0.005951017172316608, 'percent_total': 0.09761882517077909 } }
Notice the percent_total
attribute for the revenues_program_services
and expenses_all_salaries_employee_benefits
fields. This is the percent of total revenues and expenses, respectively for the two fields. Most non-total financial fields contain this percent of total metric.
The organization search API allows you to search and retrieve information on various organizations at once. For example, you can use this endpoint to find a specific organization if you don't have its EIN, or you can see all organizations that match a set of target market criteria. Just send a GET request to the following endpoint, adding query parameters for your search criteria:
GET https://www.causeiq.com/api/organizations/
For example, here's a Python request that searches for 501(c)(3) organizations in Montana that have more than $1 million in revenue:
import os import requests url = "https://www.causeiq.com/api/organizations/" headers = { "Authorization": "Token {api_key}".format(api_key=os.environ["CAUSEIQ_API_KEY"]) } params = { "state": "MT", "501_c_type": "501(c)(3)", "revenues_total__gte": 1000000 } response = requests.get(url=url, headers=headers, params=params) search_data = response.json()
This is equivalent to calling the following URL (with the authorization headers, of course):
GET https://www.causeiq.com/api/organizations/?state=MT&501_c_type=501(c)(3)&revenues_total__gte=1000000
Use request parameters to add filters, so you can narrow down to just the organizations you care about. You can also use the from
parameter for pagination. The following query parameters are supported:
keywords
: Use this to search for an organization by name. It searches the names, past names, trade names, legal names, abbreviations, and other similar keywords associated with the organization501_c_type
: The specific IRS 501(c) subsection type, such as "501(c)(3)" or "501(c)(6)"website_domain
: Filter organizations by the domain of their website, such as "nature.org". Only include the domain, no trailing slashes, no "https", no "www" or anything else like that. Subdomains are not supportedntee
: The primary NTEE code of the organization, such as "C34". Note that if the NTEE code includes trailing zeroes, such as "C00", the search will use the NTEE code as a prefix (for example, "C30" would search all organizations with NTEE codes that start with "C3")street
: The street address of the organization, including partial matchescity
: The city where the organization resides. Cause IQ recommends using the metro search instead, when possiblestate
: The two-digit capitalized state abbreviation, such as "VA"metro
: The metropolitan statistical area CBSA code, such as "47900". This is provided in the address
field in the Organization Profile API resultsemployees__gte
and employees__lte
: The number of employees at the organization. The "gte" and "lte" after the double underscore represent greater than or equal to the provided number of employees, or less than or equal to the provided number of employees, respectivelyrevenues_total__gte
and revenues_total__lte
: The total revenues at the organization. The "gte" and "lte" after the double underscore represent greater than or equal to the provided revenues, or less than or equal to the provided revenues, respectivelyexpenses_total__gte
and expenses_total__lte
: The total expenses incurred by the organization. The "gte" and "lte" after the double underscore represent greater than or equal to the provided expenses or less than or equal to the provided expenses, respectivelyassets_total__gte
and assets_total__lte
: The total amount of assets held by the organization. The "gte" and "lte" after the double underscore represent greater than or equal to the provided assets, or less than or equal to the provided assets, respectivelyliabilities_total__gte
and liabilities_total__lte
: The amount of liabilities owed by the organization. The "gte" and "lte" after the double underscore represent greater than or equal to the provided liabilities or less than or equal to the provided liabilities, respectivelyfrom
: The 0-indexed start of the search results, used for paging. Each result set contains 20 organizations. If you wanted to retrieve the next set of results, add a parameter "from" containing the value "20". You can retrieve up to the first 500 results, but beyond that we return an error message.The response is a JSON object contains:
from
: the 0-indexed start of the results, used for pagingtotal
: the total number of organizations that matched the search parametersresults
: the first 20 organizations matching the provided parameters, sorted by best match, containing the name
, ein
, address
, 501_c_type
, form990_type
, revenues_total
, and ntee
fields (see organization profile API section for definitions)For example, here is a truncated response:
{ 'from': 0, 'total': 452 'results': [ { '501_c_type': '501(c)(3)', 'address': { 'city': 'Billings', 'metro': { 'label': 'Billings, MT', 'value': '13740' }, 'state': 'MT', 'street': '704 North 30TH Street', 'zip': '59101' }, 'causeiq_url': 'https://www.causeiq.com/organizations/community-crisis-center-llc,203231164/', 'ein': '203231164', 'form990_type': 'Form 990', 'name': 'Community Crisis Center LLC', 'ntee': { 'label': 'Alcohol, Drug, and Substance Abuse, Dependency Prevention and Treatment', 'value': 'F20' }, 'revenues_total': { 'one_year_growth': -0.13735296081551795, 'value': 1240238 } }, { '501_c_type': '501(c)(3)', 'address': { 'city': 'Bozeman', 'state': 'MT', 'street': '351 Evergreen Drive Suite A', 'zip': '59715' }, 'causeiq_url': 'https://www.causeiq.com/organizations/warriors-and-quiet-waters-foundation,208837637/', 'ein': '208837637', 'form990_type': 'Form 990', 'name': 'Warriors and Quiet Waters Foundation', 'ntee': { 'label': 'Rehabilitative Medical Services', 'value': 'E50' }, 'revenues_total': { 'one_year_growth': 0.30717635989010095, 'value': 4025996 } }, ... { '501_c_type': '501(c)(3)', 'address': { 'city': 'Billings', 'metro': { 'label': 'Billings, MT', 'value': '13740' }, 'state': 'MT', 'street': '2721 2ND Ave N Ste 350 No 350', 'zip': '59101' }, 'causeiq_url': 'https://www.causeiq.com/organizations/billings-symphony-society,237083873/', 'ein': '237083873', 'form990_type': 'Form 990', 'name': 'Billings Symphony Society', 'ntee': { 'label': 'Symphony Orchestras', 'value': 'A69' }, 'revenues_total': { 'one_year_growth': 0.025591771030907928, 'value': 1143622 } }, ] }
If you provide an invalid parameter, or an incorrect value for the parameter, the API will return a 400
status code, with additional information in the detail
field in the JSON results.
August 20, 2020
type
field to 501_c_type
August 18, 2020
x-rate-limit-limit
for the rate limit ceiling for that given endpoint, x-rate-limit-remaining
for the number of requests left in your usage period, and x-rate-limit-reset
for how many seconds until your usage period resetsAugust 17, 2020
value
containing the field value that will not change over time (and that you can search on), and label
containing the descriptive text of that field value, which may change over time.August 14, 2020
© 2021 Nonprofit Metrics LLC
Terms of Service and Privacy Policy
255 S. King Street, Suite 800
Seattle, WA 98104