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, 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:

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.
3. Organization personnel: List the top personnel at any given organization with GET request, providing the organization's EIN and criteria for the types of personnel you want to retrieve (like title or contact detail requirements). The results provide a list of personnel at the organization that meet your provided requirements.
4. Match organizations: Used most commonly to quickly identify which organization corresponds to a web lead form submit, or to otherwise quickly match organization data to the legal entity and EIN, using a GET request and user-supplied set of parameters. You provide the endpoint with the fields you have available on an organization (e.g., name, domain, state) and the endpoint returns the top results that match those data points.
5. Form 990 PDFs: Retrieve listings of Form 990s available for a specific organization with a GET request with the organization's EIN. You can then retrieve download URLs for specific Form 990 PDFs with follow-up requests.
6. Field definitions: Discover all the values available for specific fields available in the API. Provide the endpoint the field name and the system will respond with all potential available values and labels for that field. This is only available for fields with predefined values.

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". 

For all users of Cause IQ's API, we have these high-level limits in place:

• 20 paginations deep per search, up to the first 3,000 records (e.g., six pages deep at 500 records per search, 20 paginations deep at 150 records per search)
• 240 request per minute
• 25,000 records per day

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 default 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.
• 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 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")
• 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 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
• county: 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, 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.

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

For example, here's a Python request that retrieves the vice president level personnel identified for a given EIN :

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 person
• name_first: The person's first name
• name_middle: The person's middle name or initial
• name_last: The person's last name
• title: The title (or combination of titles) for the person
• title_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 label
• title_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 label
• email: The person's work email address
• phone: The person's work phone number
• linkedin_url: The person's LinkedIn profile page URL
• bio: A short bio blurb of the person, often as found on the organization's staff and profile listing pages
• most_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 organization

Here's an example of the response object:

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:

For example, here's a Python request that searches for organizations that match a lead with the email "[email protected]" and state of "CA".

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 organization
• ein: The EIN of the organization
• city: The name of the city in which the organization is based
• state: The state in which the organization is based, either two-character abbreviation or state name spelled out
• zipcode: The five-digit zip code where the organization is based
• url: The organization's website URL
• email: 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 person

The 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:

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).

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 itself
• ein: The EIN of the organization
• form: 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 organization
• url: 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:

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).

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.

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:

For example, here's a Python request that provides all the options available for the cats_types field:

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:

If you provide an invalid field, the API will return a 400 status code.

October 23, 2024

• Added new Organization personnel endpoint, allowing you to see which personnel Cause IQ has identified as being on the staff or board at a specific organization.

October 15, 2024

• Added California AB-488 data, from the California Office of the Attorney General and Franchise Tax Board (FTB), to the organization profile and search endpoints:
  • ca_ag_status: AB 488 status
  • ca_ag_registry_status: Charity Registration status
  • ca_ftb_status_revoked: FTB status revoked
  • ca_ag_reg_num: AG Registration Number
  • ca_ftb_entity_id: FTB Entity ID
  • ca_ag_date_status_set: Current status set date
  • ca_ag_date_last_renewal: Last renewal date
  • ca_ag_date_issue: Approval issued date
  • ca_ftb_status_revoked_date: FTB tax-exempt status revoked date
  • ca_ag_date_as_of: AB 488 data last updated ("as-of") date
• Added California AB-488 ca_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

• Added new Form 990 PDF endpoint, where you can see the Form 990s available for a given organization and obtain a download URL to save or view the Form 990 PDF

November 15, 2023

• Added 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.
• Added new definition endpoint, so you can see the various options available to see or search for a given field. Initial support for the ntee, 501_c_type, naics, metro, state, county, cats_types, cats_issues, and cats_characteristics fields.

May 16, 2023

• Added new match organizations endpoint, where you can provide the fields you have on any given organization and receive a list of the likely matches (with EINs) for that organization.

May 14, 2023

• Added new 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).
• Ability to search by county field in the search endpoint. Use the five-digit FIPS county code.

March 1, 2023

• Added new optional 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

• Added ability to search multiple 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

• 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