Catapultian Charity Verification API

Overview

Welcome to Catapultian! Here you will find information about integrating with and using the Catapultian Charity Verification API.

The Catapultian Charity Verification API allows you to quicky verify, based upon EIN (Employer identification number), whether an organization is able to receive tax deductible donations.

The Catapultian Charity Verification API is architectured around REST, using standard HTTP verbs to communicate and HTTP response codes to indicate status and errors. All responses come in standard JSON. The Catapultian API is served over HTTPS to ensure data privacy. HTTP is not supported. Every request must include your registered username and API Key. Request data can be included in either the body or query string, though using the body is recommended.

We are making this API available to you, for both commercial and non-commercial uses, free of charge for up 1,000 calls per months. If you need more calls per month, please contact us.

We have tried to make this documentation user-friendly. Still, if questions arise in your use of the API please contact us with any questions.

Gaining Access

To gain access to the Catapultian Charity Verification API, please create an account on our website. After signing-up and verifying your email, please navigate to the "My Account" page. On the "My Account" page, navigate to "Developer Tools" and click the button that says: "Access Charity Verification API". An API Key will be immediately be generated. And you will be able to see a count of the number of calls you have used month-to-date and have remaining for the month.

Please supply your credentials (username and API Key) alongside every API request. The examples below show how to achieve this in common programming languages.

Response Codes

We use standard HTTP response codes for success and failure notifications, and our errors are further classified by block. In general, 200 HTTP codes respond to success, 40X codes are for client-related failures, and 50X codes are for Catapultian-related issues. We're doing our best to minimize the latter. However, if you find consistent issues, please contact support immediately.

Sample code

Sample code for interacting with the API is provided below. JSON output is used.

The examples use dummy values. The results shown do not match the real results. (Don't forget to change the credentials and the query parameters in the URL.)

          $ curl -u bilbo.baggins@hobbitmail.com:yourapikey "https://www.catapultian.org/eocheck?ein=123456789"
          [
              {
                  "ein": 123456789,
                  "org_name": Sturdy Wing,
                  "address": 1234 Main St, Brooklyn, NY,
                  "ruling_month": 200810,
                  "deductibility": 1,
                  "subsection":3
              }
          ]
          
          $url = "https://www.catapultian.org/eocheck?ein=123456789";
          $credentials = "bilbo.baggins@hobbitmail.com:yourapikey";
          $ch = curl_init();
          curl_setopt($ch, CURLOPT_URL, $url);
          curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
          curl_setopt($ch, CURLOPT_USERPWD, $credentials);
          curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
          $output = curl_exec($ch);
          $errno = curl_errno($ch);
          $error = curl_error($ch);
          $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
          curl_close($ch);
          if ($errno != CURLE_OK)
             throw new Exception("Error: ".$error);
          if ($code != 200)
             throw new Exception("Error: Expected 200 response code but got {$code}");
          $array = json_decode($output, true);
          if (!$array || count($array) == 0)
             throw new Exception("No results found");
          foreach($array as $item) {
             echo "ein = ".$item["ein"]."n";
          }
          
          import https://catapultian.org/wp-content/themes/vqifwbqnvcecaghobbtnte64578/files/api/java.io.BufferedReader;
          import https://catapultian.org/wp-content/themes/vqifwbqnvcecaghobbtnte64578/files/api/java.io.InputStreamReader;
          import https://catapultian.org/wp-content/themes/vqifwbqnvcecaghobbtnte64578/files/api/java.lang.reflect.Type;
          import https://catapultian.org/wp-content/themes/vqifwbqnvcecaghobbtnte64578/files/api/java.net.*;
          // GSON available at https://code.google.com/p/google-gson/
          // Required for JSON parsing
          import https://catapultian.org/wp-content/themes/vqifwbqnvcecaghobbtnte64578/files/api/com.google.gson.*;
          //Joda-Time available at http://www.joda.org/joda-time/
          //Only needed for working with datetime types
          import https://catapultian.org/wp-content/themes/vqifwbqnvcecaghobbtnte64578/files/api/org.joda.time.DateTime;
          public class JsonTest {
            public static void main(String[] args) throws Exception {
              (new JsonTest()).example();
            }
            public void example() throws Exception
            {
              Authenticator.setDefault (new Authenticator() {
                protected PasswordAuthentication getPasswordAuthentication() {
                  return new PasswordAuthentication ("bilbo.baggins@hobbitmail.com:yourapikey", "t_0833c272b4d06569b4045ace6babe87d".toCharArray());
                }
              });
              String urlstr = "https://www.catapultian.org/eocheck?ein=123456789";
              URL url = new URL(urlstr);
              HttpURLConnection connection = (HttpURLConnection) url.openConnection();
              BufferedReader rd  = new BufferedReader(new InputStreamReader(connection.getInputStream()));
              GsonBuilder gsonBuilder = new GsonBuilder();
              gsonBuilder.registerTypeAdapter(DateTime.class, new DateTimeTypeConverter());
              Gson gson = gsonBuilder.create();
              Item[] items = gson.fromJson(rd, Item[].class);
              if (items == null || items.length == 0)
                throw new Exception("No results found");
              for(Item item: items) {
                System.out.println("ein = " + item.ein);
              }
              rd.close();
            }
            class Item {
              Integer ein;
              String org_name;
              String address;       
              String ruling_month;
              Integer deductibility;
              Integer subsection;
            }
            // Only needed for working with datetime types
            class DateTimeTypeConverter implements JsonDeserializer {
              public DateTime deserialize(JsonElement json, Type type, JsonDeserializationContext context)
                  throws JsonParseException {
                return new DateTime(json.getAsString());
              }
            }
          }
          
          using System;
          using System.Collections.Generic;
          using System.Net;
          // Relies upon JSON.NET from http://json.codeplex.com/
          using Newtonsoft.Json;
          namespace ConsoleApplication1
          {
              public class Program
              {
                  static void Main(string[] args)
                  {
                      WebClient webClient = new WebClient();
                      webClient.UseDefaultCredentials = true;
                      webClient.Credentials = new NetworkCredential("bilbo.baggins@hobbitmail.com", "yourapikey");
                      string url = "https://www.catapultian.org/eocheck?ein=123456789";
                      string json = webClient.DownloadString(url);
                      Item[] array = JsonConvert.DeserializeObject(json);
                      if (array == null || array.Length == 0)
                      {
                          Console.WriteLine("No results found");
                          return;
                      }
                      foreach(Item item in array) {
                         Console.WriteLine("ein = " + item.ein);
                      }
                  }
                  public class Item
                  {
                      public int? ein { get; set; }
                      public string? org_name { get; set; }
                      public string?  address { get; set; }
                      public string? ruling_month { get; set; }
                      public int?  deductibility { get; set; }
                      public int?  subsection { get; set; }
                  }
              }
          }                    
          
          $.ajax({
            //HTTP is not supported, must use HTTPS
            url: "https://www.catapultian.org/eocheck?ein=123456789",
            crossDomain : true,
            beforeSend: function(xhr, settings) {
              xhr.setRequestHeader("Authorization","Basic "+btoa("bilbo.baggins@hobbitmail.com:yourapikey"));
            }
          })
          .done(function(data) {
            if (data.length == 0) {
              console.log("No results found");
              return;
            }
            $.each(data, function(key, value) {
               console.log(value.ein);
            });
          })
          .fail(function() {
            console.log("Failed");
          });
          

Definitions

Catapultian provides a complete list of exempt organizations based upon IRS data. We regularly update this records based upon the IRS's data publication schedule. All the data in our API is update with [2] days of the IRS publicly updating its records.

You may check that an organization is exempt based upon its EIN (Employer Identification Number).

With this function:

Charity Check
FieldTypeDescription
einintegerEmployer Identification Number (EIN) is a nine digit number assigned by the IRS to identify a particular organization’s account
namestringName consists of the organization's "primary name" and if applicable, "sort name." Sort Name may be another name under which the organization does business; it is also may consist of trade names, chapter names, or local numbers for subordinate organizations of group rulings. We separate "primary name" and "sort name" using a dash.
addressstringAddress consists of the organization's street address, city, and state as it is currently on file with the IRS
rulingintegerRuling date is the month and year (YYYYMM) on a ruling or determination letter recognizing the organization's exempt status.
deductibilityintegerThe deductibility code signifies whether contributions made to an organization are currently deductible. Please see table immediately below for more information about returned codes.
subsectionintegerSubsection Codes are the codes shown under section 501(c) of the Internal Revenue Code of 1986, which define the category under which an organization may be exempt.
Deductibility Code — Codes
CodeDescription
1Contributions are deductible.
2Contributions are not deductible.
4Contributions are deductible by treaty (foreign organizations).
Subsections — Codes
CodeDescription
1 501(c)(1) — Corporations Organized Under Act of Congress (including Federal Credit Unions)
2 501(c)(2) — Title Holding Corporation for Exempt Organization
3 501(c)(3) — Religious, Educational, Charitable, Scientific, Literary, Testing for Public Safety, to Foster National or International Amateur Sports Competition, or Prevention of Cruelty to Children or Animals Organizations
4 501(c)(4) — Civic Leagues, Social Welfare Organizations, and Local Associations of Employees
5 501(c)(5) — Labor, Agricultural and Horticultural Organizations
6 501(c)(6) — Business Leagues, Chambers of Commerce, Real Estate Boards, etc.
7 501(c)(7) — Social and Recreational Clubs
8 501(c)(8) — Fraternal Beneficiary Societies and Associations
9 501(c)(9) — Voluntary Employee Beneficiary Associations
10 501(c)(10) — Domestic Fraternal Societies and Associations
11 501(c)(11) — Teachers’ Retirement Fund Associations
12 501(c)(12) — Benevolent Life Insurance Associations, Mutual Ditch or Irrigation Companies, Mutual or Cooperative Telephone Companies, etc.
13 501(c)(13) — Cemetery Companies
14 501(c)(14) — State-Chartered Credit Unions, Mutual Reserve Funds
15 501(c)(15) — Mutual Insurance Companies or Associations
16 501(c)(16) — Cooperative Organizations to Finance Crop Operations
17 501(c)(17) — Supplemental Unemployment Benefit Trusts
18 501(c)(18) — Employee Funded Pension Trust
19 501(c)(19) — Post or Organization of Past or Present Members of the Armed Forces
20 501(c)(20) — Group Legal Services Plan Organizations
21 501(c)(21) — Black Lung Benefit Trusts
22 501(c)(22) — Withdrawal Liability Payment Fund
23 501(c)(23) — Veterans Organization
24 501(c)(24) — Section 4049 ERISA Trusts
25 501(c)(25) — Title Holding Corporations or Trusts with Multiple Parents
26 501(c)(26) — State-Sponsored Organization Providing Health Coverage for High-Risk Individuals
27 501(c)(27) — State-Sponsored Workers’ Compensation Reinsurance Organization
28 501(c)(28) — National Railroad Retirement Investment Trust
29 501(c)(29) — Qualified Nonprofit Health Insurance Issuers