Charity Search Getting Started: Quickstart Guide (2026)

Getting started overview

This guide provides a focused walkthrough for integrating the Charity Search API, covering account creation, API key acquisition, and executing a foundational request. The Charity Search API enables developers to programmatically access and integrate data on charitable organizations into their applications and services. By following these steps, you can establish a working connection and begin querying charity data.

The process is designed to be streamlined, moving from initial setup to a successful data retrieval with minimal overhead. Authentication relies on API keys, a common method for securing access to web services and identifying legitimate requests, as detailed in web security best practices from sources like the IETF OAuth 2.0 Bearer Token Usage specification.

Quick Reference Guide

The following table summarizes the essential steps for getting started with Charity Search:

Create an account and get keys

Before making any requests to the Charity Search API, you must create a developer account and obtain an API key. This key serves as your authentication credential for all API calls.

Account Registration

1. Navigate to the official Charity Search signup page.
2. Provide the required information, typically including your name, email address, and a password.
3. Complete any verification steps, such as email confirmation, as prompted.

Charity Search offers a Developer Plan, which is free and includes 500 requests per month, making it suitable for initial development and testing. Paid plans, such as the Basic Plan, start at $29/month for 5,000 requests, as detailed on the Charity Search pricing page.

API Key Retrieval

Once your account is active:

1. Log in to your newly created Charity Search account.
2. Access your API Dashboard, which is typically found under a 'Developer' or 'API' section.
3. Locate your unique API key. This key is usually displayed prominently and may be labeled as 'API Key', 'Secret Key', or similar.
4. Copy your API key. Keep this key secure, as it grants access to your Charity Search account and usage quotas. Treat it like a password.

The API key is a string of alphanumeric characters. You will include this key in the headers or query parameters of your API requests to authenticate with the Charity Search service. For instance, the AWS API Gateway documentation on API key usage illustrates common methods for passing API keys in requests.

Your first request

With an API key in hand, you can now make your first request to the Charity Search API. This example demonstrates querying for a charity by its name using cURL, Python, and Node.js. Always refer to the Charity Search API documentation for the most up-to-date endpoint details and parameters.

The base URL for the Charity Search API is typically https://api.charitysearch.org/v1/.

Example: Search for a Charity by Name

Let's assume an endpoint for searching charities by name is /charities/search and it accepts a query parameter like name.

cURL Example

cURL is a command-line tool for making HTTP requests and is useful for quick testing.

curl -X GET \
  "https://api.charitysearch.org/v1/charities/search?name=Red%20Cross" \
  -H "Authorization: Bearer YOUR_API_KEY"

Replace YOUR_API_KEY with the actual API key you obtained from your dashboard.

Python Example

Using the requests library in Python:

import requests

api_key = "YOUR_API_KEY"
base_url = "https://api.charitysearch.org/v1"
endpoint = "/charities/search"
query_params = {"name": "Red Cross"}
headers = {"Authorization": f"Bearer {api_key}"}

response = requests.get(f"{base_url}{endpoint}", params=query_params, headers=headers)

if response.status_code == 200:
    print("Success!")
    print(response.json())
else:
    print(f"Error: {response.status_code} - {response.text}")

Ensure you have the requests library installed (pip install requests).

Node.js Example

Using the built-in fetch API (available in modern Node.js versions) or a library like node-fetch:

const fetch = require('node-fetch'); // If using older Node.js or not globally available

const apiKey = "YOUR_API_KEY";
const baseUrl = "https://api.charitysearch.org/v1";
const endpoint = "/charities/search";
const charityName = "Red Cross";

async function searchCharity() {
  try {
    const response = await fetch(`${baseUrl}${endpoint}?name=${encodeURIComponent(charityName)}`, {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    });

    if (response.ok) {
      const data = await response.json();
      console.log("Success!");
      console.log(data);
    } else {
      const errorText = await response.text();
      console.error(`Error: ${response.status} - ${errorText}`);
    }
  } catch (error) {
    console.error("Network or parsing error:", error);
  }
}

searchCharity();

For Node.js environments that do not natively support fetch, install node-fetch: npm install node-fetch.

Common next steps

After successfully making your first API call, consider these common next steps to further integrate Charity Search into your application:

• Explore Additional Endpoints: Review the comprehensive Charity Search API reference to discover other available endpoints, such as retrieving charity details by ID, financial data, or programmatic access to annual reports.
• Implement Error Handling: Develop robust error handling in your code to gracefully manage various API responses, including rate limit errors (HTTP 429), authentication failures (HTTP 401), and invalid requests (HTTP 400).
• Manage API Keys Securely: Ensure your API key is not hardcoded in client-side applications or publicly accessible repositories. For server-side applications, use environment variables or a secure secret management service. Google's API key best practices offer valuable guidance on this topic.
• Monitor Usage: Regularly check your API usage against your plan limits (e.g., 500 requests/month for the free tier) via the Charity Search API Dashboard to avoid service interruptions.
• Upgrade Your Plan: If your application requires higher request volumes or additional features, consider upgrading from the Developer Plan to a paid subscription like the Basic Plan or higher.
• Integrate into a Full Application: Begin integrating the retrieved charity data into your user interface or backend logic to build out your application's features.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

• Check API Key: Double-check that your API key is correct and has not expired. Ensure there are no leading or trailing spaces if copied manually. The API key must match what is shown in your Charity Search API Dashboard.
• Authentication Header: Verify that the Authorization: Bearer YOUR_API_KEY header is correctly formatted. Some APIs might expect X-API-Key or other headers, but Charity Search uses a Bearer token. Refer to the authentication section of the API documentation for specifics.
• Base URL and Endpoint: Confirm that the base URL (https://api.charitysearch.org/v1) and the specific endpoint (e.g., /charities/search) are accurate as per the Charity Search API documentation. Typos are a frequent cause of 404 Not Found errors.
• Query Parameters: Ensure that all required query parameters (e.g., name=Red%20Cross) are included and correctly encoded. Incorrect parameters can lead to 400 Bad Request responses.
• Network Connectivity: Verify your internet connection. If you are behind a firewall or proxy, ensure it is configured to allow outbound HTTPS requests to api.charitysearch.org.
• Rate Limiting: If you receive an HTTP 429 (Too Many Requests) error, you may have exceeded your plan's request limit. Check your usage in the API Dashboard and wait for the rate limit to reset, or consider upgrading your plan.
• Response Body: For non-200 responses, always inspect the response body. Charity Search's API is noted for generally descriptive error messages, which can provide specific clues about what went wrong.
• Consult Documentation: The Charity Search API documentation is the authoritative source for all API specifics, including error codes and expected request formats.