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, use the Organization profile API endpoint with the EIN supplied in the Organization search API results.

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 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 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, and "one_year_growth" for the year-over-year growth in employees
• revenues_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 year
• expenses_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 year
• assets_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 year
• liabilities_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 year

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
• from: 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 paging
• total: the total number of organizations that matched the search parameters
  
• results: 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:

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

• 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