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."

Form 990 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 Form 990 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

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.

funding_sources

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

programs & grants

governance

fundraising

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.

related_organizations / foreign_activities / lobbying / DAFs

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 three 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).

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.