Help Center

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:

1. Organization profile: Retrieve details on a specific organization with a GET request, providing the organization's EIN. By default, we provide the 20 most commonly-used fields in the response, including name, address, 501(c) type, NTEE code, fiscal year end, high-level financials, website URL, and phone number, among other fields. If you want more details, you can provide a comma-separated list of field names as a URL parameter, allowing you to retrieve any of more than 200 fields we have on organizations.
2. Organization search: Find multiple organizations that meet various criteria, using a GET request and user-supplied set of parameters. You can paginate on the results to see all the organizations that meet your criteria. The results provide a few of the most common fields; if you want detailed organization information, you can provide a comma-separated list of field names.

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:

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 endpoint
  
• x-rate-limit-remaining: the number of requests left in your usage period
  
• x-rate-limit-reset: how many seconds until your usage period resets
  

If 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):

For example, here's what a request looks like in Python:

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 dashes
• name: The common / trade name of the organization
  
• other_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 strings
• phone: The office phone number for the nonprofit
• website_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 less
• ntee: 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 time
  
• 501_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
  
• causeiq_url: The URL for the Cause IQ profile of the organization
• employees: 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 values
• revenues_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 values
• expenses_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 expenditures
• assets_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 assets
• liabilities_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 liabilities

Here's an example of the response object with the above default fields:

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:

Here's what the response to the above request looks like:

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:

For example, here's a Python request that searches for 501(c)(3) organizations in Montana that have more than $1 million in revenue:

This is equivalent to calling the following URL (with the authorization headers, of course):

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 organization
  
• 501_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 supported
  
• ntee: 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 matches
  
• city: The city where the organization resides. Cause IQ recommends using the metro search instead, when possible
  
• state: 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 results
  
• 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, respectively
  
• revenues_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, respectively
• expenses_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, respectively
• assets_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, respectively
• liabilities_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, respectively
• employees_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, respectively
• last_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 paging
• total: the total number of organizations that matched the search parameters
  
• results: 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:

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.

February 10, 2022

• Ability to customize fields returned on the search endpoint by sending comma-separated fields in the  fields parameter
• Added historical financial / quantitative information on organization endpoint and search endpoint, under the historical attribute

January 31, 2022

• Added new 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 page
• Increased maximum total results returned in search endpoint from 500 to 3,000

January 13, 2022

• Added new search fields, the last organization update date (last_updated) and number of employees (employees).
• Added last_updated and employees to the fields returned for organizations in the search endpoint.

January 10, 2022

• Changed value returned for metro area in the Metro Area (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.
• Note that the number in the value is the Core-Based Statistical Area (CBSA) code for that metro area.

January 6, 2022

• Added new option fields to the organization profile endpoint: All NTEE Codes (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

• Organization Search API is now live!
• Renamed type field to 501_c_type

August 18, 2020

• Details on usage and rate limits (if applicable) now included in response headers, with 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 resets

August 17, 2020

• Documentation page (this page!) now live
• Standardized object for categorical fields with a machine-focused name (e.g., "47900" for metro area). These fields now contain an object response, with 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

• Private beta launch of the Cause IQ organization profile API