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, conduct programmatic searches to retrieve organizations that match specific criteria, view the personnel at a specific organization, and more. 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 six API endpoints currently, created to help with the most common tasks of our customers:
The Cause IQ API requires a Cause IQ Pro Subscription. If you already have the Pro Subscription (or the legacy Data Enrichment Add-on), reach out to your support contact to activate your API access.
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 (if any) for exports and enrichments. In general, legacy Annual Usage-Based Subscription plans with the Data Enrichment Add-on have monthly usage limits, whereas newer Cause IQ Pro Subscription plans do not. If your plan has usage limits, 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".
For all users of Cause IQ's API, we have these high-level limits in place:
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 default 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. Integer.fiscal_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. Boolean.ca_ag_status
: For charities registered with the State of California, their AB-488 charity registration / solicitation status.causeiq_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, "one_year_growth" for the year-over-year growth in employees, and "historical" for the historical employment valuesrevenues_total
: Most recent total revenues for the organization. Object containing "value" for the total revenues itself, "one_year_growth", which is the growth in revenues over the previous year, and "historical" for the historical total revenue valuesexpenses_total
: Most recent total expenditures of the organization. Object containing "value" for the total expenses itself, "one_year_growth", which is the growth in expenses over the previous year, and "historical" for the historical total expendituresassets_total
: Most recent total assets of the organization. Object containing "value" for the assets itself, "one_year_growth", which is the growth in assets over the previous year, and "historical" for the historical total assetsliabilities_total
: Most recent total liabilities for the organization. Object containing "value" for the amount of total liabilities, "one_year_growth", which is the growth in liabilities over the previous year, and "historical" for the historical total liabilitiesHere's an example of the response object with the above default fields:
{ "ein": "530242652", "name": "The Nature Conservancy" "other_names": [], "phone": "(703) 841-5300", "website_url": "https://www.nature.org/en-us/", "address": { "city": "Arlington", "state": "VA", "street": "4245 Fairfax Drive", "zip": "22203", "metro": { "value": "47900", "label": "Washington-Arlington-Alexandria, DC-VA-MD-WV" } }, "description": "The mission of The Nature Conservancy is to conserve the lands and waters on which all life depends. The mission of The Nature Conservancy is to conserve The lands and waters on which all life depends. Tnc's mission is to conserve The lands and waters...", "ntee": { "value": "C34", "label": "Land Resources Conservation" }, "501_c_type": "501(c)(3)", "form990_type": "Form 990", "year_formed": 1951, "fiscal_year_end": "June", "most_recent_tax_period": "2020-06", "pub78_eligible_tax_deduction": true, "causeiq_url": "https://www.causeiq.com/organizations/nature-conservancy,530242652/", "employees": { "historical": [ {"value": 4091, "year": 2020}, {"value": 4185, "year": 2019}, {"value": 4099, "year": 2018}, {"value": 4037, "year": 2017}, {"value": 3875, "year": 2016} ], "one_year_growth": -0.022461170848267598, "value": 4091 }, "revenues_total": { "value": 1137390674, "one_year_growth": 0.1395687043149081, "historical": [ {"value": 1137390674, "year": 2020}, {"value": 998088724, "year": 2019}, {"value": 1184630698, "year": 2018}, {"value": 1006241963, "year": 2017}, {"value": 914539673, "year": 2016} ] }, "expenses_total": { "value": 907041369, "one_year_growth": -0.02742449794671975, "historical": [ {"value": 907041369, "year": 2020}, {"value": 932617948, "year": 2019}, {"value": 907553872, "year": 2018}, {"value": 829488331, "year": 2017}, {"value": 810283620, "year": 2016} ] }, "assets_total": { "value": 7975541090, "one_year_growth": 0.03440216355284886, "historical": [ {"value": 7975541090, "year": 2020}, {"value": 7710290418, "year": 2019}, {"value": 7409864700, "year": 2018}, {"value": 6991747049, "year": 2017}, {"value": 6697479313, "year": 2016} ] }, "liabilities_total": { "value": 923191581, "one_year_growth": -0.07091367191771991, "historical": [ {"value": 923191581, "year": 2020}, {"value": 993655329, "year": 2019}, {"value": 811391555, "year": 2018}, {"value": 769986785, "year": 2017}, {"value": 782237564, "year": 2016} ], } }
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": "metro,last_updated,expenses_all_salaries_employee_benefits,naics,last_updated" } )
Here's what the response to the above request looks like:
{ "ein": "530242652", "name": "The Nature Conservancy", "causeiq_url": "https://www.causeiq.com/organizations/nature-conservancy,530242652/", "last_updated": "2022-02-08", "metro": {"value": "47900", "label": "Washington-Arlington-Alexandria, DC-VA-MD-WV" }, "naics": {"value": "813312", "label": "Environment, Conservation, and Wildlife Organizations" }, "expenses_all_salaries_employee_benefits": { "value": 414954661, "one_year_growth": -0.02124872164654612, "percent_total": 0.45748151647976265, "historical": [ { "value": 414954661, "year": 2020}, { "value": 423963340, "year": 2019}, { "value": 399350969, "year": 2018}, { "value": 378660948, "year": 2017}, { "value": 350864501, "year": 2016} ] } }
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")cats_types
: Each organization can have multiple types values, which describe at a high-level the kind of organization it is, such as professional_association
, charities
, or hq_parent
. Contact Cause IQ for a list of values available.cats_issues
: The issues that an organization works on or cares about, with each organization potentially having multiple issues, such as education
, animals
, and business_industry
.cats_characteristics
: A listing of general activities an organization undertakes or how it operates, such as memberships
, lobbying
, or pub78_tax_deductible
.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 resultscounty
: The five-digit FIPS county code of the organization, such as "30063" for Missoula County, Montana.employees__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, respectivelyemployees_gte
and employees_lte
: The number of people employed by the organization (i.e., people filling out W-2s). 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, respectivelylast_updated__gte
and last_updated__lte
: The date we last updated an organization's information. This is for any update on an organization, even just minor tweaks. The "gte" and "lte" after the double underscore represent greater than or equal to the date provided or less than or equal to the date provided, respectively. Use YYYY-MM-DD string format for the dates, such as "2020-12-31".from
: The 0-indexed start of the search results, used for paging. 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 3,000 results, but beyond that we return an error message.limit
: How many organization results are returned in the results
response field. By default, 20 organizations are displayed. The maximum value is 500.fields
: If you want to customize the fields you are retrieving, add a comma-separated string of field names that you want to retrieve.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 (or limit
) organizations matching the provided parameters, sorted by best match, containing the name
, ein
, address
, 501_c_type
, form990_type
, revenues_total
, ntee
, employees
, and last_updated
fields by default (see organization profile API section for definitions)For example, here is a truncated response:
{ "total": 464, "from": 0, "results": [ { "last_updated": "2021-10-21", "name": "Oregon Foundation For North American Wild Sheep", "employees": { "historical": [ {"value": 18, "year": 2020}, {"value": 19, "year": 2019}, {"value": 17, "year": 2018}, {"value": 16, "year": 2017}, {"value": 13, "year": 2016} ], "one_year_growth": -0.05263157894736848, "value": 18 }, "causeiq_url": "https://www.causeiq.com/organizations/oregon-foundation-for-north-american-wild-sheep,421109229/", "form990_type": "Form 990", "address": { "city": "Bozeman", "state": "MT", "street": "412 Pronghorn Trail", "zip": "59718" }, "revenues_total": { "historical": [ {"value": 8086144, "year": 2020}, {"value": 7792380, "year": 2019}, {"value": 7770571, "year": 2018}, {"value": 6770550, "year": 2017}, {"value": 6228596, "year": 2016} ], "one_year_growth": 0.037698880188081096, "value": 8086144 }, "501_c_type": "501(c)(3)", "ntee": {"value": "D20", "label": "Animal Protection and Welfare" }, "ein": "421109229" }, { "last_updated": "2021-06-24", "name": "Livingston HealthCare", "employees": { "historical": [ {"value": 496, "year": 2020}, {"value": 489, "year": 2019}, {"value": 431, "year": 2018}, {"value": 428, "year": 2017}, {"value": 383, "year": 2016} ], "one_year_growth": 0.014314928425357865, "value": 496 }, "causeiq_url": "https://www.causeiq.com/organizations/livingston-healthcare,810378200/", "form990_type": "Form 990", "address": { "city": "Livingston", "state": "MT", "street": "320 Alpenglow Lane", "zip": "59047" }, "revenues_total": { "historical": [ {"value": 57886186, "year": 2020}, {"value": 58437851, "year": 2019}, {"value": 53145457, "year": 2018}, {"value": 52184141, "year": 2017}, {"value": 45023262, "year": 2016} ], "one_year_growth": -0.009440199982713282, "value": 57886186 }, "501_c_type": "501(c)(3)", "ntee": {"value": "E22", "label": "Hospital, General" }, "ein": "810378200" }, ... ] }
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.
The organization personnel API lets you retrieve the personnel that Cause IQ has identified as being on the staff or board at any individual organization. Note that these are only the personnel we've identified -- via the Form 990, website personnel listings, our research team's efforts, and other available sources -- and only includes personnel we've confirmed being at the organization in the past three years (we purposefully exclude older personnel because of the increased probably of them not working at the organization anymore), and is limited to 25 personnel in any given request. To retrieve the personnel, send a GET request to the following endpoint, replacing ":ein" with the organization's EIN (sans dashes, just nine-digit string):
GET https://www.causeiq.com/api/organizations/:ein/personnel/
For example, here's a Python request that retrieves the vice president level personnel identified for a given EIN :
import os import requests ein = "941730465" url = f"https://www.causeiq.com/api/organizations/{ein}/personnel/" headers = { "Authorization": "Token {api_key}".format(api_key=os.environ["CAUSEIQ_API_KEY"]) } params = { "title_levels": "chief,director,vice-president" } response = requests.get( url=url, headers=headers ) personnel_data = response.json()
Use request parameters to add filters, so you can narrow down the personnel to the specific ones that matter to your company. You can use the following parameters to filter personnel:
title_levels
: How high up a person is at the organization, such as "chief" or "director". Use the Field Definitions endpoint to see all the potential values for this filter.title_functions
: The type of work the person does at the organization, such as "executive" or "developmentfundraising". Use the Field Definitions endpoint to see all the potential values for this filter.title_keywords
: Search for personnel whose titles contain specific works or phrases. You can construct advanced query phrases with this filter, as detailed in this Help Center article.title_keywords_exclude
: Exclude personnel whose titles contain specific works or phrases. You can construct advanced query phrases with this filter, as detailed in this Help Center article.require_email
: Only return personnel for whom Cause IQ has identified an email address, by using this field with a "true" value.require_phone
: Only return personnel for whom Cause IQ has identified an associated phone number, by using this field with a "true" value.The response is a JSON object containing a single attribute, personnel
, which contains an array of matching personnel. The personnel objects contain the following attributes (attributes are only provided if values are present for that person):
name
: The full name of the personname_first
: The person's first namename_middle
: The person's middle name or initialname_last
: The person's last nametitle
: The title (or combination of titles) for the persontitle_levels
: The levels we've identified based on the person's title, which is a list of objects containing the title level's value and labeltitle_functions
: The functions we've identified based on the person's title, which is a list of objects containing the title function's value and labelemail
: The person's work email addressphone
: The person's work phone numberlinkedin_url
: The person's LinkedIn profile page URLbio
: A short bio blurb of the person, often as found on the organization's staff and profile listing pagesmost_recent_data_point
: The date of the most recent data point obtained on the organization; the date was last confirmed this person was at the organizationHere's an example of the response object:
{'personnel': [ { 'most_recent_data_point': '2024-06-04', 'name': 'Jack Arnoldy', 'name_first': 'Jack', 'name_last': 'Arnoldy', 'title': 'Director of Content Strategy', 'title_functions': [], 'title_levels': [{'label': 'Director', 'value': 'director'}] }, { 'email': '[email protected]', 'most_recent_data_point': '2023-09-06', 'name': 'Jessica Megna', 'name_first': 'Jessica', 'name_last': 'Megna', 'title': 'AVP, Financial Planning', 'title_functions': [{'label': 'Controller / Comptroller', 'value': 'controllercomptroller'}], 'title_levels': [{'label': 'Director', 'value': 'director'}] }, ... { 'email': '[email protected]', 'most_recent_data_point': '2022-02-23', 'name': 'Sarah Katzschner', 'name_first': 'Sarah', 'name_last': 'Katzschner', 'title': 'Director, Foundation Relations', 'title_functions': [{'label': 'Grants / Foundations', 'value': 'grants'}], 'title_levels': [{'label': 'Director', 'value': 'director'}] } ]}
If you provide an EIN that doesn't exist, you will receive a 404 response. If you provide filters that are so restrictive that there are no matching personnel, even though the organization exists, you will receive an empty array for the personnel
attribute.
The match organization API lets you find the organizations that most likely match random data points you have on an organization. The most common use case is when you have a lead form on the website where you want to match the submitted data to the corresponding organization, so that you can properly evaluate the lead. Send a GET request to the following endpoint:
GET https://www.causeiq.com/api/match/organizations/
For example, here's a Python request that searches for organizations that match a lead with the email "[email protected]" and state of "CA".
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 = { "email": "[email protected]", "state": "CA" } response = requests.get(url=url, headers=headers, params=params) search_data = response.json()
Use request parameters to add different fields to try to find the corresponding organization. Depending on the fields you provide, the match organizations endpoint will try a variety of queries and combine the fields in different ways to try to find the best organization matches. The following query parameters are supported:
name
: The name of the organizationein
: The EIN of the organizationcity
: The name of the city in which the organization is basedstate
: The state in which the organization is based, either two-character abbreviation or state name spelled outzipcode
: The five-digit zip code where the organization is basedurl
: The organization's website URLemail
: The work email address of an employee at the organization. The algorithm extracts the domain from the email address, it does not match to an individual personThe response is a JSON array object contains containing name
, ein
, website_url
, 501_c_type
, address
, other_names
, ntee
, and causeiq_url
fields for up to five likely match organizations. For example, here is a response to the above query:
[{ '501_c_type': '501(c)(3)', 'address': { 'city': 'San Francisco', 'metro': { 'label': 'San Francisco-Oakland-Berkeley, CA', 'value': '41860' }, 'state': 'CA', 'street': '50 California St Suite 500', 'zip': '94111' }, 'causeiq_url': 'https://www.causeiq.com/organizations/earthjustice,941730465/', 'ein': '941730465', 'name': 'Earthjustice', 'ntee': { 'label': 'Legal Services', 'value': 'I80' }, 'other_names': [], 'website_url': 'https://earthjustice.org/' }]
If you provide an invalid field, or don't include at least one of the name
, ein
, email
, or url
fields, the API will return a 4xx status code, with additional information in the detail
field in the JSON results.
Sometimes you need automated access to Form 990 PDFs, such as for building out your own custom Cause IQ CRM integrations. Use the Form 990 PDF endpoints to both see which Form 990s are available for any organization and to obtain a download URL so you can view or save the PDF file.
List Form 990 PDFs available
Send a GET request to the following endpoint, replacing ":ein" with the organization's EIN (without any dashes, just the nine-digit string).
GET https://www.causeiq.com/api/organizations/:ein/form990pdfs/
The response is a JSON array containing object representations of the Form 990s available for the organization. Note that this does not contain Form 990-N (e-Postcard) information, just Form 990s, Form 990-EZs, and Form 990-PFs. Here are the Form 990 fields returned:
id
: The internal Cause IQ ID for the specific Form 990, which you can use to obtain a URL for the PDF itselfein
: The EIN of the organizationform
: The type of Form 990, such as "Form 990-PF"tax_period
: The fiscal year end of the tax period the Form 990, such as "2023-12"date_scanned
: When the IRS received the Form 990 from the organizationurl
: The Cause IQ API URL where you can obtain a link to download the Form 990 PDF (API authentication still required)Here's an example of the response object:
[{ 'date_scanned': '2024-05-29', 'ein': '832859786', 'form': 'Form 990-PF', 'id': 'b7892ee07d29f08b69bae573f9dc7f6e', 'tax_period': '2023-12', 'url': 'https://www.causeiq.com/api/organizations/832859786/form990pdfs/b7892ee07d29f08b69bae573f9dc7f6e/' }, { 'date_scanned': '2023-11-14', 'ein': '832859786', 'form': 'Form 990-PF', 'id': '4354b802855cf9912d52f4d11609840f', 'tax_period': '2022-12', 'url': 'https://www.causeiq.com/api/organizations/832859786/form990pdfs/4354b802855cf9912d52f4d11609840f/' }, { 'date_scanned': '2022-11-15', 'ein': '832859786', 'form': 'Form 990-PF', 'id': '9bf4d2c89a20982c7dbb4914da7c946b', 'tax_period': '2021-12', 'url': 'https://www.causeiq.com/api/organizations/832859786/form990pdfs/9bf4d2c89a20982c7dbb4914da7c946b/' }, ..., { 'date_scanned': '2021-11-02', 'ein': '832859786', 'form': 'Form 990-PF', 'id': 'e3961736caae74cfbbfc2349afc926bc', 'tax_period': '2018-12', 'url': 'https://www.causeiq.com/api/organizations/832859786/form990pdfs/e3961736caae74cfbbfc2349afc926bc/' }]
If you provide an EIN that doesn't exist, the API will return an empty array.
Obtain download URL for a Form 990 PDF
Send a GET request to the following endpoint, replacing ":ein" with the organization's EIN (without any dashes, just the nine-digit string) and ":id" with the Form 990 ID (provided above).
GET https://www.causeiq.com/api/organizations/:ein/form990pdfs/{id}/
The response is a JSON object containing a single attribute, download_url
, which is an AWS S3 download link where you can view or download the PDF. Note that the download URL is only good for ten minutes. If you are looking to provide ways for more permanent URLs for the PDFs, dynamically call the above API endpoint containing the Form 990 ID, then redirecting the browser to the download_url
download link, such as with the javascript location.replace() method.
For security reasons, the AWS S3 download URL for the Form 990 PDF is only good for 10 minutes.
It can be helpful to know all the various options available for fields accessible with the API, whether pulling individual organization details or searching for specific types of organizations. Use the field definitions endpoint to see all options available for a given API-accessible field. Just send a GET request to the following endpoint, adding a field_name
query parameter for the field you want the various values for:
GET https://www.causeiq.com/api/definitions/
For example, here's a Python request that provides all the options available for the cats_types
field:
import os import requests url = "https://www.causeiq.com/api/definitions/" api_key = os.environ["CAUSEIQ_API_KEY"] headers = { "Authorization": f"Token {api_key}" } params = { "field_name": "cats_types" } response = requests.get(url=url, headers=headers, params=params) search_data = response.json()
The follow fields are currently supported for identifying the correspond values for: ntee
, 501_c_type
, naics
, metro
, state
, county
, cats_types
, cats_issues
, cats_characteristics
, and widget_types
.
The response is simply an array / list containing the value
and label
for each of the options available for that field. For example:
[ {'label': 'Political advocacy', 'value': 'advocacy'}, {'label': 'Buddhist', 'value': 'buddhist'}, {'label': 'Catholic', 'value': 'catholic'}, {'label': 'Christian', 'value': 'christian'}, {'label': 'Conservation easement', 'value': 'conserve_easement'}, {'label': 'Operates donor advised funds', 'value': 'donor_advised_fund'}, {'label': 'Endowed support', 'value': 'endowment'}, {'label': 'e-Postcard filer', 'value': 'epostcard_filer'}, ... {'label': 'Terminated', 'value': 'terminated'}, {'label': 'Community engagement / volunteering', 'value': 'volunteer_comm'} ]
If you provide an invalid field, the API will return a 400 status code.
October 23, 2024
October 15, 2024
ca_ag_status
: AB 488 statusca_ag_registry_status
: Charity Registration statusca_ftb_status_revoked
: FTB status revokedca_ag_reg_num
: AG Registration Numberca_ftb_entity_id
: FTB Entity IDca_ag_date_status_set
: Current status set dateca_ag_date_last_renewal
: Last renewal dateca_ag_date_issue
: Approval issued dateca_ftb_status_revoked_date
: FTB tax-exempt status revoked dateca_ag_date_as_of
: AB 488 data last updated ("as-of") dateca_ag_status
field as default field returned on organization profile and search endpoints, showing whether a charity can solicit donations in the State of California (if registered with the state)August 7, 2024
November 15, 2023
cats_types
, cats_issues
, and cats_characteristics
fields to the search endpoint, so that you can find organization similar to how you do in the Cause IQ search interface.May 16, 2023
May 14, 2023
county
field to organization profile and search endpoints, which provides fips_code
and name
attributes when the organization has an identified county. If the organization doesn't have an identified county, the field is returned with a null
value. The county is identified according to FIPS code, which is a unique five-digit string code for each county. For example, King County, WA is "53033" (53 for the state of Washington, 033 for King County).county
field in the search endpoint. Use the five-digit FIPS county code.March 1, 2023
central_organization
field to organization profile and search endpoints, which provides ein
and name
attributes when the organization has a parent of a group exemption or clear centralized organization from Schedule R. For example, 'central_organization': {'ein': '536001666', 'name': 'National Gallery of Art (NGA)'}
September 27, 2022
ntee
, 501_c_type
, naics
, metro
, and state
fields in the search endpoint. Just added a comma between the two values, such as params = {"state": "WA,MT"}
February 10, 2022
fields
parameterhistorical
attributeJanuary 31, 2022
limit
parameter to the search endpoint, in which you can customize how many results per page of search results you want displayed, up to 500 per pageJanuary 13, 2022
last_updated
) and number of employees (employees
).last_updated
and employees
to the fields returned for organizations in the search endpoint.January 10, 2022
metro
) and Grant Recipient Metros (grantee_metros
) to {'label': 'Missoula, MT', 'value': '33540'}
instead of just 'Missoula, MT'
. This now matches the value of the metro area in the default address
field.value
is the Core-Based Statistical Area (CBSA) code for that metro area.January 6, 2022
ntee_all
), All NAICS Codes (naics_all
), Types Categories (cats_types
), Issues Categories (cats_issues
), Characteristics Categories (cats_characteristics
), Form 990 Tax Preparer (tax_preparer
), A-133 Audit CFDA Codes (a133_cfda_items
), A-133 Audit Federal Agencies (a133_federal_agencies
)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
© 2024 Nonprofit Metrics LLC
Terms of Service and Privacy Policy
255 S. King Street, Suite 800
Seattle, WA 98104