Response Format

CharityQuery response fields can return strings, numbers, enriched code objects, special combined objects, null values, or be omitted entirely when they are not requested.

Present, null, or omitted
Field selection changes which fields appear in a response.
  • Present: the field was requested and has a value.
  • Null: the field was requested, but no value exists.
  • Omitted: the field was not requested with fields.
Enriched code objects
Many IRS-coded values return both the original code and a human-readable description.
  • ntee_code
  • ntee_group
  • affiliation
  • deductibility
  • foundation
  • organization
  • status
  • filing_req_code
  • pf_filing_req_code
  • account_paid
  • geocode_status
"ntee_code": {
  "code": "D20",
  "description": "Animal Protection and Welfare"
}
"geocode_status": {
  "code": 12,
  "description": "Census geocoder match"
}

If an enriched field is requested but no value exists, it returns null.

"ntee_code": null
Subsection classification object
Subsection and classification are resolved together.

The subsection_classification field combines two IRS values into one object with a resolved description.

"subsection_classification": {
  "subsection": "03",
  "classification": "2000",
  "description": "Educational Organization"
}

If either value is unavailable or the combination cannot be resolved, this field may return null.

String fields
String fields return plain text values or null.

Non-null string fields

  • ein

Nullable string fields

  • name
  • ico
  • street
  • city
  • state
  • zip
  • group
  • ruling
  • activity
  • tax_period
"state": "NC"
"group": "0429"
"group": null
Numeric fields
Numeric fields return numbers when values are available.
  • asset_amount
  • income_amount
  • revenue_amount
  • lat
  • lng
"asset_amount": 125000.45
"lat": 34.2257
"asset_amount": null

If your implementation returns Prisma Decimal values without conversion, some numeric fields may serialize as strings. For public API consistency, normalizing these fields to numbers is recommended.

Nearby-only numeric fields
Nearby search adds distance information.
  • distance_miles

The distance_miles field is calculated from the search origin and is only available on /nearby.

"distance_miles": 3.44
Nearby Search Origin
Nearby responses include the resolved search origin used to calculate distance.

The origin field describes the exact location used as the starting point for the nearby search. This ensures transparency when calculating distance_miles.

The origin may come from a ZIP code lookup or directly from provided coordinates.

"origin": {
  "lat": 34.2237,
  "lng": -77.8862,
  "source": "zip"
}
  • lat — resolved latitude used for distance calculation
  • lng — resolved longitude used for distance calculation
  • source — how the origin was determined
    • "zip" — derived from origin_zip
    • "coordinates" — provided via lat and lng

This field is always included in nearby responses and reflects the final coordinates used for distance calculations.

TypeScript example
Frontend applications should account for optional and nullable fields.
type CodedValue = {
  code: string | number
  description: string
}

type SubsectionClassification = {
  subsection: string
  classification: string
  description: string
}

type Charity = {
  ein?: string
  name?: string | null
  ntee_code?: CodedValue | null
  state?: string | null
  asset_amount?: number | null
  lat?: number | null
  lng?: number | null
  geocode_status?: CodedValue | null
  subsection_classification?: SubsectionClassification | null
  distance_miles?: number | null
}