Quickstart

Make your first CharityQuery request, return nearby nonprofits, and understand the response structure.

1. Base URL
All API requests use the CharityQuery API domain.
https://api.charityquery.com
2. Authenticate with your API key
Send your API key using the x-api-key request header.
x-api-key: YOUR_API_KEY

Website login and API access are separate. Sign in to the dashboard to manage your account and generate API keys. API requests use the x-api-key header.

Read Auth & Limits →
3. Make your first nearby search
Find nonprofits within 25 miles of ZIP code 28403.
curl "https://api.charityquery.com/nearby?origin_zip=28403&radius=25&fields=ein,name,city,state,ntee_group,distance_miles&limit=2" \
  -H "x-api-key: YOUR_API_KEY"

The /nearby endpoint requires either origin_zip or both lat and lng. If both are provided, latitude and longitude should be treated as the search origin.

4. Example response
{
  "page": 1,
  "limit": 2,
  "total": 143,
  "totalPages": 72,
  "next": 2,
  "prev": null,
  "origin": {
      "lat": 34.2237,
      "lng": -77.8862,
      "source": "zip"
    },
  "charities": [
    {
      "ein": "020421110",
      "name": "Example Animal Rescue",
      "city": "Wilmington",
      "state": "NC",
      "ntee_group": {
        "code": "D",
        "description": "Animal-Related"
      },
      "distance_miles": 3.44
    },
    {
      "ein": "030389985",
      "name": "Example Community Foundation",
      "city": "Wilmington",
      "state": "NC",
      "ntee_group": {
        "code": "T",
        "description": "Philanthropy, Voluntarism, and Grantmaking Foundations"
      },
      "distance_miles": 3.71
    }
  ]
}
5. Select only the fields you need
Use fields as a comma-separated list to reduce response size.
/nearby?origin_zip=28403&fields=ein,name,state,distance_miles

distance_miles is only available on /nearby. The standard /charities endpoint does not include distance because it does not use a search origin.

Read Field Selection →
6. Add filters
Filter nearby results by IRS classification, NTEE code, state, financial ranges, and more.
/nearby?origin_zip=28403&radius=25&ntee_group=D&deductibility=1
/charities?state=NC&ntee_code=D20&asset_amount_gte=100000

Some filters accept one value. Others accept comma-separated lists. Check the filtering guide for the full list.

Read Filtering & Sorting →
7. Understand enriched fields
Many IRS-coded fields return structured objects instead of raw codes.
"ntee_code": {
  "code": "D20",
  "description": "Animal Protection and Welfare"
}
"subsection_classification": {
  "subsection": "03",
  "classification": "2000",
  "description": "Educational Organization"
}
Read Response Format →
8. Handle errors
Errors use a consistent machine-readable format.
{
  "code": "validation_error",
  "message": "Request validation failed.",
  "reqId": "1e526aeb-258b-45ff-b092-3da872536e9f",
  "details": [
    {
      "path": "origin_zip",
      "message": "Provide either origin_zip or both lat and lng"
    }
  ]
}
Read Error Handling →
Next steps
Once your first request works, continue with the main guides.
Nearby Search →Filtering & Sorting →Field Selection →OpenAPI Reference →