Metadata & Codes
Metadata routes expose the IRS and CharityQuery code definitions used throughout the API. Use them to understand coded fields, build dropdowns, validate filter values, and interpret enriched response objects.
How metadata is used
Metadata routes help developers build reliable filters and readable interfaces.
- Populate selects, dropdowns, comboboxes, and filter menus.
- Look up valid values before sending metadata-validated filters.
- Understand enriched fields such as
ntee_code,deductibility, andgeocode_status. - Cache metadata in your own application when values are used frequently.
Metadata requests do not count against your daily request limit.
Metadata key
A broad reference for coded fields used throughout CharityQuery.
GET /metadata/charity-keyThis route is primarily a reference. It does not validate requests, but it helps explain the coded fields available in the API.
| field | label | description |
|---|---|---|
| ein | Employer Identification Number | A nine-digit number assigned by the IRS to identify a particular organization's account. |
| name | Primary Name of Organization | Legal non-profit name. |
| ico | In Care Of Name | Person (officer, director, etc.) to whose attention any correspondence should be directed. |
| street | Street Address | Street address of the organization. |
| city | City | City where the organization is located. |
| state | State | State where the organization is located. |
| zip | Zip Code | Postal code of the organization. |
| group | Group Exemption Number | A four-digit internal number assigned to central or parent organizations holding group exemption letters. |
| subsection | Subsection Code | Codes shown under section 501(c) of the Internal Revenue Code of 1986 that define the category under which an organization may be exempt. |
| affiliation | Affiliation Code | Defines the organizational grouping. |
| classification | Classification Code | Codes under section 501(c) defining the classification of the organization within a subsection. |
| ruling | Ruling Date | Month and year (YYYYMM) on the ruling or determination letter recognizing the organization's exempt status. |
| deductibility | Deductibility Code | Signifies whether contributions made to the organization are deductible. |
| foundation | Foundation Code | Codes that differentiate between private foundations and public charities. |
| activity | Activity Codes | Deprecated with the adoption of the National Taxonomy of Exempt Entities (NTEE) coding system in January 1995. Previously three activity codes (AAABBBCCC) described the organization's cause. |
| organization | Organization Code | Indicates the legal structure of the nonprofit organization. |
| status | Exempt Organization Status Code | Defines the type of exemption held by the organization. |
| tax_period | Tax Period | Tax period of the latest return filed (YYYYMM). |
| filing_req_code | Filing Requirement Code | Indicates the primary return(s) the organization is required to file. |
| pf_filing_req_code | Private Foundation Filing Requirement Code | Indicates the primary return(s) the organization is required to file for private foundations. |
| account_paid | Accounting Period | Designates the accounting period or fiscal year ending month (MM) of the organization. |
| asset_amount | Asset Amount | Total assets from the most recent Form 990 series return filed by the organization. |
| income_amount | Income Amount | Total income from the most recent Form 990 series return filed by the organization. |
| revenue_amount | Revenue Amount | Total revenue from the most recent Form 990 series return. |
| ntee_code | National Taxonomy of Exempt Entities (NTEE) Code | Code used to classify an exempt organization based on its primary exempt activity. |
| ntee_group | National Taxonomy of Exempt Entities (NTEE) General Group | A modifier used to describe activities in support of nonprofit organizations |
| geocode_status | Indicates how a charity's geographic coordinates were determined | Charities may have either physical addresses or P.O. Boxes. Physical addresses are processed through the U.S. Census geocoder to obtain latitude and longitude. In some cases, an exact match is not possible, and fallback methods such as ZIP code centroids are used. The geocode_status value indicates how the coordinates were obtained and the level of accuracy for each record. |
Fields with metadata routes
These fields have dedicated metadata endpoints.
These routes are especially useful when building UI filters. They let your application show readable labels while sending valid API values.
Subsection and classification are a special case and should be handled as a paired value.
| key | type | metadataRoute |
|---|---|---|
| subsection | string | /metadata/subsection-classification-codes |
| classification | string | /metadata/subsection-classification-codes |
| ntee_code | string | /metadata/ntee-codes |
| ntee_group | string | /metadata/ntee-groups |
| account_paid | string | /metadata/account-paid-codes |
| pf_filing_req_code | string | /metadata/pf-required-codes |
| filing_req_code | string | /metadata/filing-required-codes |
| organization | string | /metadata/organization-codes |
| status | string | /metadata/status-codes |
| affiliation | string | /metadata/affiliation-codes |
| deductibility | string | /metadata/deductibility-codes |
| foundation | string | /metadata/foundation-codes |
Recommended usage
Use metadata as a reference layer for your application.
- Fetch metadata during development to understand available codes.
- Use metadata endpoints to power user-facing filters.
- Store returned JSON locally when your application uses it often.
- Refresh periodically if you want updated definitions.
- Use metadata definitions to explain enriched API responses.
Next steps
Learn how metadata connects to filters and response fields.