Charity Verify API

One API call to check tax-deductible eligibility, revocation status, group exemptions, and OFAC sanctions screening for any U.S. nonprofit.

Overview

The Charity Verify API cross-references multiple IRS data sources and OFAC sanctions lists to give you a single, definitive answer on whether a nonprofit can receive tax-deductible donations.

Data sources checked on every request:

• IRS Exempt Organizations Business Master File (EO BMF)
• IRS Publication 78 (eligible donees)
• IRS Auto-Revocation List (with reinstatement detection)
• Group Exemption resolution (subordinate → parent lookup)
• OFAC SDN & Consolidated sanctions lists (fuzzy matching)
• Form 990 leadership screening against OFAC

Authentication

All API requests require an API key passed in the x-api-key header.

# Include your key in every request
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.givalgo.ai/v1/verify?ein=53-0196605"

To get an API key, contact support@givalgo.ai. Keys are scoped to a usage plan (Free, Basic, or Pro) which determines your rate limits.

Keep your API key secure. Do not expose it in client-side code or public repositories. If compromised, contact support for a key rotation.

Quickstart

Get up and running in 60 seconds.

cURL

# Verify American Red Cross
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.givalgo.ai/v1/verify?ein=53-0196605"

Python

import requests

response = requests.get(
    "https://api.givalgo.ai/v1/verify",
    params={"ein": "53-0196605"},
    headers={"x-api-key": "YOUR_API_KEY"}
)
data = response.json()

if data["deductible"]:
    print(f"{data['organization']['name']} is eligible!")
else:
    print(f"Status: {data['status']} - {data['message']}")

JavaScript

const response = await fetch(
  "https://api.givalgo.ai/v1/verify?ein=53-0196605",
  { headers: { "x-api-key": "YOUR_API_KEY" } }
);
const data = await response.json();
console.log(data.status, data.organization?.name);

Verify Endpoint

Returns a complete verification of the nonprofit identified by the given EIN, including tax-deductible eligibility, revocation history, group exemption status, OFAC sanctions screening, and California state compliance (when applicable).

Parameters

Response Fields

sanctions_screening object

Match object (within matches[])

Verification Statuses

Sanctions Screening

Every verification includes an automated OFAC screening of the organization name and its leadership (officers, directors, key employees from Form 990). Matches are checked against both SDN and Consolidated lists, including primary names and aliases.

Overall status

Disambiguation fields

When matches are found, each match object includes remarks and addresses to help you distinguish true positives from false positives:

• remarks — OFAC remarks field containing date of birth, nationality, passport numbers, and other identifying information
• addresses — known addresses for the matched OFAC entry (street, city/state/zip, country)

Example match object

{
  "source": "OFAC SDN",
  "matched_name": "SMITH, John A.",
  "matched_via": "primary_name",
  "similarity_score": 0.912,
  "match_strength": "STRONG",
  "sdn_type": "individual",
  "program": "SDGT",
  "entry_id": 12345,
  "remarks": "DOB 15 Mar 1970; nationality Iran; Passport A1234567",
  "addresses": [
    {
      "address": "123 Example St",
      "city_state_zip": "Tehran",
      "country": "Iran"
    }
  ]
}

In this example, a board member named "John Smith" matched an OFAC entry — but the remarks show an Iranian DOB/passport, and the addresses show Tehran. If your board member is based in Ohio with a different DOB, this is a false positive you can confidently dismiss.

California Compliance

California AB 488 requires fundraising platforms to verify that nonprofits are in good standing with three authorities before facilitating donations involving a California donor or a California-based nonprofit:

1. IRS — federal tax-exempt status (always checked)
2. CA Attorney General — Registry of Charitable Trusts registration status
3. CA Franchise Tax Board — state tax-exempt status (revocation check)

The API automatically runs California checks when the nonprofit is based in CA (per IRS records) or when you provide donor_state=CA. You can also provide ca_entity_id to trigger checks directly.

When do CA checks run?

Lookup cascade

The API uses a three-tier lookup to maximize coverage across the CA AG Registry (556K records):

1. ca_entity_id — direct SOS/FTB# lookup (97% of AG records have this)
2. FEIN — federal EIN match (covers ~58% of AG records)
3. Name + city — fuzzy match fallback using trigram similarity (≥0.65 threshold with city filter, ≥0.80 without)

The match_method field in the response tells you which tier was used: ca_entity_id, fein, or name_match.

state_compliance.california object

Impact on overall status

Note: UNKNOWN (organization not found in CA AG) does not penalize the overall status. This may indicate the organization is exempt from CA registration (churches, schools, hospitals, or organizations receiving under $25,000 annually).

Example response

{
  "status": "CAUTION",
  "message": "This organization is listed in IRS Publication 78 ... However, California state compliance checks indicate that the organization's California Attorney General registration status is 'Delinquent'. Under California AB 488, fundraising platforms must verify state-level good standing before facilitating donations.",
  "state_compliance": {
    "california": {
      "trigger": "nonprofit_based_in_ca",
      "ag_registry": {
        "status": "DELINQUENT",
        "registry_status": "Delinquent",
        "reg_number": "CT0252232",
        "last_renewal_date": "2018-05-01",
        "date_status_set": "2020-02-21",
        "match_method": "fein"
      },
      "ftb": {
        "status": "CLEAR"
      },
      "state_status": "NON_COMPLIANT"
    }
  }
}

Rate Limits

Rate limits are applied per API key based on your plan tier.

When you exceed your rate limit, the API returns 429 Too Many Requests. The response includes a Retry-After header indicating when you can retry.

Playground

Test the API directly from your browser. Enter your API key and an EIN to see a live response.

Bulk Verify API

Verify hundreds or thousands of EINs in a single async request. Same 5-step verification, delivered at scale.

Overview

The Bulk Verify API accepts up to 250 EINs (semicolon-separated) or 20,000 EINs (CSV upload), processes them asynchronously via background workers, and delivers results via polling endpoint, webhook callback, or CSV download.

Each EIN goes through the same verification as the single Verify endpoint — IRS data cross-referencing, group exemption resolution, and OFAC sanctions screening.

Authentication

All API requests require an API key passed in the x-api-key header — the same key used for the single Verify endpoint.

# Include your key in every request
curl -X POST "https://api.givalgo.ai/v1/bulk-verify" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"eins": "13-1837418;53-0196605"}'

To get an API key, contact support@givalgo.ai. Keys are scoped to a usage plan (Free, Basic, or Pro) which determines your rate limits and max EINs per job.

Job ownership: Jobs are scoped to your API key. You can only view the status and results of jobs you created.

Quickstart

Submit a bulk job and poll for results in under a minute.

cURL — Submit + Poll

# 1. Submit a bulk job
curl -X POST "https://api.givalgo.ai/v1/bulk-verify" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eins": "13-1837418;53-0196605;06-0646973",
    "format": "both"
  }'

# Response: {"job_id": "bulk_abc123", "status": "PROCESSING", ...}

# 2. Poll for results
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.givalgo.ai/v1/bulk-verify/bulk_abc123"

Python

import requests, time

# Submit bulk job
resp = requests.post(
    "https://api.givalgo.ai/v1/bulk-verify",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "eins": "13-1837418;53-0196605;06-0646973",
        "format": "both"
    }
)
job = resp.json()
job_id = job["job_id"]

# Poll until complete
while True:
    status = requests.get(
        f"https://api.givalgo.ai/v1/bulk-verify/{job_id}",
        headers={"x-api-key": "YOUR_API_KEY"}
    ).json()
    if status["status"] == "COMPLETED":
        print(f"Done! {status['summary']}")
        break
    time.sleep(2)

JavaScript

// Submit bulk job
const resp = await fetch("https://api.givalgo.ai/v1/bulk-verify", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    eins: "13-1837418;53-0196605;06-0646973",
    format: "both"
  })
});
const { job_id } = await resp.json();

// Poll until complete
const poll = async () => {
  const res = await fetch(
    `https://api.givalgo.ai/v1/bulk-verify/${job_id}`,
    { headers: { "x-api-key": "YOUR_API_KEY" } }
  );
  const data = await res.json();
  if (data.status === "COMPLETED") return data;
  await new Promise(r => setTimeout(r, 2000));
  return poll();
};
const results = await poll();

Bulk Verify

Verify hundreds or thousands of EINs in a single request. The Bulk Verify API accepts EINs as a semicolon-separated list (up to 250) or via CSV upload (up to 20,000), processes them asynchronously, and delivers results via polling or webhook.

Each EIN goes through the same 5-step verification as the single Verify endpoint — IRS data cross-referencing, group exemption resolution, and OFAC sanctions screening.

Submit Bulk Job

Submit EINs for bulk verification. Returns 202 Accepted with a job_id for tracking.

JSON body (semicolon-separated EINs)

curl -X POST "https://api.givalgo.ai/v1/bulk-verify" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eins": "13-1837418;53-0196605;06-0646973",
    "webhook_url": "https://your-server.com/hook",
    "format": "both"
  }'

CSV file upload

curl -X POST "https://api.givalgo.ai/v1/bulk-verify" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@organizations.csv" \
  -F "webhook_url=https://your-server.com/hook"

CSV must have an ein column header (case-insensitive). Falls back to the first column if no header match.

Request body fields

Query parameters

Response (202 Accepted)

{
  "job_id": "bulk_a1b2c3d4e5f6",
  "status": "PROCESSING",
  "total_eins": 247,
  "duplicates_removed": 3,
  "estimated_seconds": 8,
  "poll_url": "/v1/bulk-verify/bulk_a1b2c3d4e5f6",
  "created_at": "2026-03-25T14:30:00Z"
}

Validation error (400)

If any EINs fail validation (and skip_invalid is not set), you get a 400 with details:

{
  "error": "VALIDATION_ERROR",
  "message": "3 EINs failed validation",
  "invalid_eins": [
    { "ein": "123", "error": "EIN must be exactly 9 digits" }
  ],
  "valid_count": 247,
  "hint": "Add ?skip_invalid=true to process only valid EINs."
}

Poll Job Status

Check the progress and retrieve results of a bulk verification job. Jobs are scoped to your API key — you can only access jobs you created.

In progress

{
  "job_id": "bulk_a1b2c3d4e5f6",
  "status": "PROCESSING",
  "progress": {
    "total": 247,
    "completed": 180,
    "failed": 2,
    "percent_complete": 73.7
  }
}

Completed

For jobs with 1,000 or fewer EINs, results are included inline. Larger jobs return a csv_download_url only. Each result in the array is a full single-verify response — identical to what you'd get from the /v1/verify endpoint, including organization details, Pub78, revocation history, and OFAC sanctions screening.

{
  "job_id": "bulk_a1b2c3d4e5f6",
  "status": "COMPLETED",
  "summary": {
    "eligible": 200,
    "not_deductible": 30,
    "revoked": 5,
    "not_found": 8,
    "ofac_flags": 3
  },
  "results": [
    {
      "ein": "13-1837418",
      "ein_raw": "131837418",
      "status": "ELIGIBLE",
      "deductible": true,
      "message": "Organization is eligible to receive tax-deductible donations.",
      "organization": { /* full org details: name, city, state, NTEE, assets, ... */ },
      "pub78": { /* listed, deductibility_code, description */ },
      "revocation": { /* ever_revoked, currently_revoked, dates */ },
      "sanctions_screening": { /* status, org & leadership screening, matches */ },
      "checked_at": "2026-03-25T23:11:10Z",
      "api_version": "v1"
    },
    // ... one entry per EIN, same structure as single /v1/verify response
  ],
  "csv_download_url": "https://...presigned...",
  "completed_at": "2026-03-25T14:30:07Z"
}

CSV download

The csv_download_url (pre-signed S3 URL, valid 1 hour) contains a flattened version of the full results with 37 columns covering organization details, Pub78 status, revocation history, and OFAC screening. Column headers:

ein, status, deductible, message,
org_name, org_city, org_state, subsection_code, subsection_label,
deductibility_code, deductibility_label, foundation_code, foundation_label,
status_code, status_label, affiliation_code, affiliation_label,
group_exemption_number, ruling_date, ntee_code,
asset_amount, income_amount, revenue_amount,
pub78_listed, pub78_deductibility_code, pub78_deductibility_description,
pub78_via_group_exemption,
ever_revoked, currently_revoked, revocation_date, revocation_posting_date,
reinstatement_date,
sanctions_status, ofac_org_matches_found, ofac_leadership_matches_found,
screened_at, error_message, checked_at

Job statuses

Webhooks

If you provide a webhook_url when submitting a bulk job, we'll POST a notification when the job completes. This is the recommended approach for large jobs instead of polling.

Webhook payload

# POST to your webhook_url
# Headers:
#   Content-Type: application/json
#   User-Agent: Givalgo-Webhook/1.0
#   X-Givalgo-Event: bulk_verify.completed
#   X-Givalgo-Job-Id: bulk_a1b2c3d4e5f6

{
  "event": "bulk_verify.completed",
  "job_id": "bulk_a1b2c3d4e5f6",
  "status": "COMPLETED",
  "total_eins": 247,
  "completed": 245,
  "failed": 2,
  "summary": {
    "eligible": 200,
    "not_deductible": 30,
    "ofac_flags": 3
  },
  "csv_download_url": "https://...presigned-url...24hr-expiry...",
  "poll_url": "/v1/bulk-verify/bulk_a1b2c3d4e5f6"
}

Retry policy

Webhook delivery is attempted up to 3 times with exponential backoff (1s, 5s delays). If your endpoint returns a 2xx status, delivery is marked as successful. The csv_download_url is a pre-signed S3 URL valid for 24 hours.

Throughput

Job Statuses

A bulk job progresses through these statuses:

Verification Statuses

Each EIN in a bulk job receives the same verification statuses as the single Verify endpoint:

Limits & Throughput

Bulk job limits are applied per API key based on your plan tier.

Estimated processing times

Processing time depends on current load and Lambda warm-start state. For time-sensitive workloads, use a webhook for instant notification on completion.

Report API

Generate professional, branded PDF verification reports for any U.S. nonprofit — ready to share with donors, board members, or compliance teams.

Overview

The Report API takes an EIN and returns a multi-page PDF document containing the same verification data as the Verify endpoint — presented in a polished, print-ready format with Givalgo branding.

Each report includes a cover page, verification outcome with status badge, IRS data breakdown, OFAC sanctions screening results, financial snapshot, and a branded back page.

Authentication

The Report API uses the same API key authentication as the Verify and Bulk Verify endpoints. Include your key in the x-api-key header:

curl -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/pdf" \
  "https://api.givalgo.ai/v1/report?ein=13-1837418" \
  -o report.pdf

Quickstart

Generate your first PDF report in seconds:

# Download a verification report for Candid (EIN 13-1837418)
curl -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/pdf" \
  "https://api.givalgo.ai/v1/report?ein=13-1837418" \
  -o candid-verification.pdf

# Open the PDF
open candid-verification.pdf

Tip: Include the Accept: application/pdf header to receive decoded binary PDF. In Postman, use Send and Download (dropdown next to Send) to save the file.

Report Endpoint

Takes an EIN and returns a professionally formatted PDF verification report. The underlying data is identical to the /v1/verify endpoint — the Report API simply renders it into a branded, multi-page PDF document.

Parameters

Headers

Success Response

Error Responses

Error responses are returned as JSON (not PDF):

Note: All valid verification statuses (ELIGIBLE, REVOKED, NOT_FOUND, CAUTION, NOT_DEDUCTIBLE) return a 200 with a PDF. Only auth or input errors return JSON.

Report Sections

Each generated PDF contains the following pages:

Verification Statuses

The report displays the same verification statuses as the Verify endpoint, rendered as color-coded badges:

Important Notes

Response Time

PDF generation typically takes 2–4 seconds (cold start may add 3–5 seconds on first request). The API Gateway timeout is 29 seconds.

Data Source

Reports contain the same data as the /v1/verify endpoint. The PDF is generated on-the-fly from live verification data — it is not cached. Each request produces a fresh report with the current timestamp.

File Size

Reports are typically 115–130 KB depending on the amount of data (e.g., OFAC matches increase size slightly).

Disclaimer

Each report includes a footer disclaimer: "This report is generated from publicly available IRS data and OFAC sanctions lists. It does not constitute legal or tax advice."

Data API

Structured access to every meaningful number, ratio, and peer benchmark from U.S. nonprofit Form 990 filings — for 3.3M+ filings covering 1.9M+ unique organizations.

Overview

The Data API turns raw IRS e-file XML into a clean JSON response covering financials, compensation, programs, governance, fundraising, liquidity, expense composition, related organizations, foreign activity, and more. Every core ratio is benchmarked against peer cohorts (NTEE major group × revenue band × state), so you see not just the number but where it sits in its sector.

Two tiers share the same endpoint family:

• /v1/data Base — ~150 fields, all core sections, all peer benchmarks
• /v1/data-pro Pro — base + three deep-detail attachments (~410 fields total)

Tiers: Data vs Data Pro

Tier is determined entirely by the endpoint path — there is no public include= parameter. Both tiers accept the same query parameters (ein, tax_year) and require the same x-api-key header.

New indicates fields added in the April 2026 release.

Authentication

All requests require an API key passed in the x-api-key header. Keys are scoped to a usage plan (Free, Base, Pro) which determines rate limits and tier access.

# Base tier
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.givalgo.ai/v1/data?ein=53-0196605"

# Pro tier
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.givalgo.ai/v1/data-pro?ein=53-0196605"

To upgrade to Pro or request a trial key, contact support@givalgo.ai.

Quickstart

cURL — most recent filing

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.givalgo.ai/v1/data?ein=53-0196605"

cURL — specific tax year

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.givalgo.ai/v1/data?ein=53-0196605&tax_year=2022"

Python

import requests

r = requests.get(
    "https://api.givalgo.ai/v1/data-pro",
    params={"ein": "53-0196605"},
    headers={"x-api-key": "YOUR_API_KEY"},
)
data = r.json()

name = data["organization"]["name"]
prog_pct = data["financial_profile"]["expense_composition"]["program_expense_ratio"]
peer_median = data["financial_profile"]["expense_composition"] \
    ["peer_benchmarks_by_metric"]["program_expense_ratio"] \
    ["by_ntee_and_revenue_band_and_state"]["median"]

print(f"{name}: program = {prog_pct:.0%}, peer median = {peer_median:.0%}")

JavaScript

const r = await fetch(
  "https://api.givalgo.ai/v1/data?ein=53-0196605",
  { headers: { "x-api-key": "YOUR_API_KEY" } }
);
const data = await r.json();
console.log(data.organization.name, data.trends.computed.revenue_trend);

Endpoints

Returns base sections (~150 fields): organization, financials, trends, compensation, funding_sources, programs, governance, fundraising, financial_profile, related_organizations, foreign_activities, lobbying_and_political, contributor_summary, donor_advised_funds, data_freshness.

Returns the base shape plus three detail attachments (~410 fields total): financials_detail, governance_detail, registration.

Parameters

Response Top-Level

organization

financials

financial_documents New

Candid-parity filing-document links. Synthesized from EIN + object_id + return_type via ProPublica Nonprofit Explorer (we don't host PDFs directly; ProPublica's open viewer is the de-facto public equivalent).

trends

compensation

Top-level scalars are drawn from Form 990 Part VII (officers, key employees, highest-paid) and Part IX (salaries & benefits aggregate).

Top-level fields

by_role New

Highest-paid person whose title matches common patterns for each role. null per role if no match.

peer_benchmarks_by_metric New

One cube per metric — see How Cubes Work. Metrics with no peer data (e.g. small revenue bands) are omitted.

• top_officer_comp — absolute top-officer dollar amounts
• top_officer_comp_to_revenue_pct — scale-normalized
• ceo_comp, cfo_comp, dev_director_comp — role-specific benchmarks
• avg_compensation_per_employee — whole-org payroll per FTE

The legacy key peer_benchmarks (top-level, not nested) remains for backwards compatibility and mirrors peer_benchmarks_by_metric.top_officer_comp.

schedule_j_supplemental New

Best-effort parse of the Schedule J Part III narrative (Part I Lines 4A/4B free text). Present only when the filing has Schedule J narrative text.

Note: each individual compensation_breakdown object in people[] also carries the Schedule J Part II base/bonus/deferred/nontaxable split (filing_org + related_orgs) for people listed on Schedule J.

funding_sources

Aggregated from Schedule I of grantmakers that reported this EIN as a grant recipient.

programs & grants

governance

fundraising

contractors[] New

Schedule G Part I — paid fundraising contractors. Always-on (no include gate). Distinct from operations.contractors[] (Form 990 Part VII Section B top-5 highest-paid independent contractors).

financial_profile

Our headline analytics section — every ratio here comes with a peer benchmark cube.

liquidity

revenue_concentration

operating_sustainability

expense_composition New

Two views of where the dollars go — the functional split Charity Navigator uses, plus the FASB-required natural-category split from Form 990 Part IX.

Functional view (program / admin / fundraising)

Natural view (FTA — Part IX line items) New

Note: absolute third-party thresholds (Charity Navigator's 70% program benchmark, BBB Wise Giving's 65%, etc.) are deliberately NOT returned. Peer percentiles already place the org in its cohort, and absolute thresholds often penalize nonprofits for legitimate sector differences.

profitability New

Candid-parity profitability derivations from financial_trends_analysis.business_model_indicators. Always-on under financial_profile (no include gate).

full_cost_components New

Candid-parity "true cost of operating" composite. PARTIAL today — includes only the IRS-derivable components (expenses + depreciation). Does NOT include debt_principal_payment + fixed_asset_additions, which come from audited financials (not on the 990).

balance_sheet_composition New

Candid-parity land/buildings/equipment basis + ratios. Sourced from Schedule D Part VI line rollups. NULL when filing has no Schedule D Part VI.

accounting_ratios New

Candid-parity liquidity ratio. IRS Form 990 does NOT break out current vs. non-current liabilities — we approximate "current liabilities" as Accounts Payable + Grants Payable + Deferred Revenue (Part X Lines 17+18+19).

operations New

Filing-level operations metadata. Always-on (no include gate).

contractors[] New

Top-5 highest-paid Form 990 Part VII Section B independent contractors. Distinct from fundraising.contractors[] (Schedule G Part I).

books_in_care_of New

Form 990 Part VI Line 20 — record-keeper contact (the person/firm responsible for keeping the books). Object emitted when at least one of the 5 fields is populated.

Board / co-leader name fields New

Candid-parity board-leadership names derived from a title-text heuristic over the Part VII Section A people roster. Documented as a heuristic — not a structured IRS field. Each key is emitted only when a match is found.

disclosures New Pro

Schedule-shaped disclosure data — tax-exempt bonds, non-cash contributions, significant dispositions, foreign individual grants, and interested-person transactions. Gated by ?include=disclosures on /v1/data-pro.

Bug fix: ?include=disclosures is now self-sufficient. Previously this include was implicitly gated by ?include=governance, so callers asking only for disclosures got an empty section. Schedule L still appears when both includes are requested.

schedule_k.bonds[] New

Tax-exempt bond issues from Schedule K Parts I + IV. One row per bond.

schedule_n.dispositions[] New

Significant disposition / liquidation detail (Schedule N). Only emitted when array is non-empty. Distinct from the top-level dissolution block (whole-org liquidation signal).

schedule_m.contributions[] New

Non-cash contribution types received during the tax year (Schedule M).

schedule_f New

Schedule F — foreign grants & activities. Distinct from the top-level foreign_activities[] (Part I region-level).

schedule_l New

Schedule L — transactions with interested persons. indicators / transactions carry the Part IV checklist flags + 990-PF self-dealing rows; the four named arrays carry Form 990 Parts I–IV grouped by type (each present only when it has rows). All transaction objects share the same leaf set: person_name, relationship, description, amount, in_default, corrected, excess_benefit_date, uncorrected_amt, loan_from_org_ind, loan_written_agreement, grant_recipient_rel, grant_type_desc.

schedule_a New

Schedule A — public charity status & public support test. Present only when the filing has a public-support block.

schedule_o New

Schedule O — supplemental narrative explanations. Flat array; each entry is {form_section, reference, explanation}.

dissolution New

Top-level block. Emitted ONLY when the org liquidated or ceased operations during the tax year (i.e. liquidation_date or cessation_of_operations_date is populated on the filing). Absent otherwise. Always-on.

conservation_easements / art_collections / private_foundation New

Three top-level always-on blocks (no include gate). Each is present only when the org has the relevant data; absent otherwise.

conservation_easements

Schedule D Part II.

art_collections

Schedule D Part III — art / historical-treasure collection policies (booleans).

private_foundation 990-PF only

Form 990-PF metrics. Present ONLY on 990-PF filers; absent for public charities (990 / 990-EZ). Five top-level rollup scalars plus nested Part I col B/C/D walkers, Part II FMV breakdown, Part III changes-in-net-assets, and Part XII qualifying-distributions detail. Empty nested objects mean “section not filed”.

hospitals New

Schedule H data. Present ONLY for 501(c)(3) hospital filers that report at least one hospital facility. Gated by ?include=hospitals.

filing_summary

Org-wide Schedule H scalars (Parts I–III).

facilities[] · facility_policies[] · other_facilities[] · joint_ventures[] · community_benefit_by_category[]

related_organizations / foreign_activities / lobbying / DAFs

filing_meta New

Filing-level metadata for the response year, drawn from the Form 990 return header. Always-on (no include gate).

data_freshness

Peer Benchmarks: How Cubes Work

Every ratio in compensation.peer_benchmarks_by_metric and financial_profile.*.peer_benchmarks_by_metric returns a cube: the same metric sliced across seven peer-group dimensions, each with the same six percentile stats.

Shape of a single cube

{
  "by_ntee":                          { ...PeerStats },
  "by_revenue_band":                  { ...PeerStats },
  "by_state":                         { ...PeerStats },
  "by_ntee_and_revenue_band":         { ...PeerStats },
  "by_ntee_and_state":                { ...PeerStats },
  "by_revenue_band_and_state":        { ...PeerStats },
  "by_ntee_and_revenue_band_and_state": { ...PeerStats }
}

PeerStats

Peer Benchmarks: 7 Dimensional Cuts

Each cube is the same metric sliced seven ways. The intersection cuts (triple) are the narrowest and usually most meaningful, but may have small cohorts.

NTEE major group

A–Z first letter of the IRS National Taxonomy of Exempt Entities code. Examples: A Arts & Culture, B Education, E Health, P Human Services.

Revenue band

Eight bands based on total revenue: 1 <$100K, 2 <$500K, 3 <$1M, 4 <$5M, 5 <$10M, 6 <$50M, 7 <$100M, 8 $100M+.

State

Two-letter state code from the organization's mailing address.

Intersections

4 compound cuts: ntee ∩ revenue_band, ntee ∩ state, revenue_band ∩ state, and the triple ntee ∩ revenue_band ∩ state.

Peer Benchmarks: Metrics Covered

17 metrics currently ship with peer-benchmark cubes. New metrics are added as underlying data coverage grows.

Pro-Only Attachments Pro

Calling /v1/data-pro attaches four extra sections on top of the base shape.

financials_detail

Line-by-line Part VIII (revenue) and Part IX (expenses) breakdowns plus Schedule A (public charity status), Schedule B (contributors summary), Schedule D (supplemental financials) highlights, Schedule O (narratives).

Newly surfaced child-table arrays New

governance_detail

Full voting-board roster with titles, committee memberships, compensation-review process, meeting-minutes flags, and policies (conflict of interest, whistleblower, document retention, joint venture, independence).

registration

State-level registration filings (where ingested), Schedule R related-organization full roster with ownership percentages, foreign registration details.

Error Codes

Rate Limits

When you exceed a limit, API Gateway returns 429 Too Many Requests. Back off and retry after 30 seconds. Contact support@givalgo.ai to adjust plans.