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 — May Not Operate or Solicit for Charitable Purposes List (11 CCR § 312). Since 2026-09-02 this is the only list the AG publishes; the full registry export (Current / Exempt registrations) was discontinued, so the AG check is a negative-list check: being on the list is the finding, absence from it is the AB 488 good-standing signal (11 CCR § 316(c)).
3. CA Franchise Tax Board — state tax-exempt status (revocation check)

The California checks run on every request, for every organization, since 2026-09-03. They used to run only for California-based nonprofits or when donor_state=CA was passed. Two things made that gate wrong: the Attorney General's May Not Operate list is not California-only (about 920 of the organizations on it are based in other states), and AB 488 (Gov. Code § 12599.9, 11 CCR § 316) binds a platform because it serves people in California and covers every organization it solicits for, wherever that organization is based. donor_state is still accepted but changes nothing. ca_entity_id still gives a direct lookup by California SOS/FTB entity number.

When an organization based outside California is on the list, ag_registry.notice explains that the finding bars it from soliciting in California and says nothing about its home-state standing — so a grantmaker in Ohio understands why the overall status is CAUTION.

Lookup cascade

The API uses a three-tier lookup to match against the CA AG May Not Operate list (~30K records; 82% carry a FEIN):

1. ca_entity_id — direct SOS/FTB entity-number lookup (92% of list rows carry one)
2. FEIN — federal EIN match (82% of list rows carry one)
3. Name + city — trigram similarity ≥0.80 within the same city. No city, no name match: on a negative-only list a false positive is a false accusation.

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

Changed 2026-09-03: COMPLIANT and UNKNOWN were retired with the AG's move to a negative-only list. COMPLIANT rested on finding a Current or Exempt registration, which the AG no longer publishes in bulk; CLEAR states exactly what was checked. Registration details for a specific organization are available in the AG's Registry Search Tool.

Example response

{
  "status": "CAUTION",
  "message": "This organization is listed in IRS Publication 78 ... However, California state compliance checks indicate that the organization is on the California Attorney General's May Not Operate or Solicit for Charitable Purposes List (status 'Delinquent'). Under California AB 488, fundraising platforms must verify state-level good standing before facilitating donations.",
  "state_compliance": {
    "california": {
      "ag_registry": {
        "status": "DELINQUENT",
        "registration_status": "Delinquent",
        "entity_status": "Listed",
        "reg_number": "CT0252232",
        "match_method": "fein"
      },
      "ftb": {
        "status": "CLEAR"
      },
      "state_status": "NON_COMPLIANT"
    }
  }
}

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-2875808;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-2875808;53-0196605;06-0646973",
    "format": "both"
  }'

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

# 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-2875808;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"] == "done":
        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-2875808;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 === "done") 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-2875808;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": "running",
  "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": "running",
  "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": "done",
  "summary": {
    "eligible": 200,
    "not_deductible": 30,
    "revoked": 5,
    "not_found": 8,
    "ofac_flags": 3
  },
  "results": [
    {
      "ein": "13-2875808",
      "ein_raw": "132875808",
      "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 46 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,
ca_state_status, ca_ag_status, ca_ag_registration_status,
ca_ag_entity_status, ca_ag_reg_number, ca_ag_match_method,
ca_ftb_status, ca_ftb_revocation_date,
error_message, checked_at

The eight ca_* columns (added 2026-09-03) are populated on every row — the California checks run for every organization. ca_state_status is CLEAR, NON_COMPLIANT or REVOKED; ca_ag_status is NOT_LISTED or the finding for an organization on the Attorney General's May Not Operate list. Same meanings as state_compliance.california on GET /v1/verify.

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": "done",
  "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

These limits apply to every bulk job.

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-2875808" \
  -o report.pdf

Quickstart

Generate your first PDF report in seconds:

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

# Open the PDF
open verification-report.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

Search 1.9M+ U.S. nonprofits by EIN, name, cause, geography, financials — or a plain-English prompt — and get back clean, lean org records built from 3.3M+ Form 990 filings.

Overview

The Data API is a nonprofit search engine. One endpoint, POST /v1/data, accepts three kinds of request:

• search_terms — an EIN ("13-2875808") or an organization name ("Human Rights Watch"). Keywords match organization names — not mission text, and not cause. To search by cause use filters.organization.causes (plain English) or ntee_major_codes (codes), or prompt for a whole question.
• filters — structured search: cause (NTEE), geography (state / city / zip), org type, IRS standing, and financial screens (revenue, assets, grants, program expense ratio, months of cash, growth streaks, revenue concentration)
• prompt — Ask: one plain-English sentence ("private foundations in Ohio funding youth mental health"), parsed and semantically ranked by the same pipeline that powers Ask on Givalgo Discover. Returns the top 20.

Every mode returns the same lean org record (~40 fields): identity, geography, cause, IRS standing, latest financial toplines — plus the organization's logo, website, and website-scraped contact details where available.

When you've found the organization you care about, go deep with the Data Pro API:

• POST /v1/data Data — search & discovery; lean records, Ask prompts
• GET /v1/data-pro Pro — the full single-org profile (~410 fields: full financial detail, compensation cube, governance, schedules, registration)

Migrating from another nonprofit data API? Familiar request-body conventions and field aliases are accepted where the data overlaps — unsupported fields return a 400 with a hint naming the nearest supported equivalent. See Filters.

Tiers: Data vs Data Pro

The two tiers differ by how you interact, not just field count. The Data API answers "which organizations?" — search, filter, Ask — with lean records. Data Pro answers "tell me everything about this one" — a single-EIN deep profile. Both require the same x-api-key header.

The deep-profile sections below (organization, financials, trends, compensation, …) document the Data Pro response:

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, Basic, Pro) which determines rate limits and the daily Ask-prompt quota.

# Data API — search
curl -X POST -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"search_terms": "Human Rights Watch"}' \
  "https://api.givalgo.ai/v1/data"

# Data Pro API — deep single-org profile
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 — look up one org (EIN or name)

curl -X POST -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"search_terms": "13-2875808"}' \
  "https://api.givalgo.ai/v1/data"

cURL — structured search

curl -X POST -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "search_terms": "community foundation",
    "filters": {"geography": {"state": ["FL"], "city": "Miami"}},
    "size": 10
  }' \
  "https://api.givalgo.ai/v1/data"

Search by cause — three worked examples

Plain English in filters.organization.causes, resolved to NTEE codes and composed with any other filter. Every response reports what the phrase became in causes_resolved.

# 1. A cause in one city — Plymouth Housing Group, Bellwether Housing
{
  "filters": {"organization": {"causes": "homelessness"},
              "geography": {"city": "Seattle", "state": ["WA"]}},
  "sort": {"by": "total_revenue", "order": "desc"},
  "size": 5
}

# 2. A cause + an efficiency screen — Feeding America, Houston Food Bank
{
  "filters": {"organization": {"causes": "hunger relief"},
              "financials": {"program_expense_ratio": {"min": 0.90},
                             "total_revenue": {"min": 5000000}}},
  "sort": {"by": "total_revenue", "order": "desc"},
  "size": 5
}

# 3. Grantmakers working on a cause — Dana-Farber, AACR
{
  "filters": {"organization": {"causes": "cancer research",
                               "org_type": "foundation"}},
  "sort": {"by": "grants_paid", "order": "desc"},
  "size": 5
}

cURL — Ask (natural language)

curl -X POST -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt": "private foundations in Ohio funding youth mental health"}' \
  "https://api.givalgo.ai/v1/data"

Python — search, then go deep with Data Pro

import requests

HEADERS = {"x-api-key": "YOUR_API_KEY"}

# 1. Find California food banks with $10M+ revenue, biggest first
search = requests.post(
    "https://api.givalgo.ai/v1/data",
    json={
        "filters": {
            "geography": {"state": ["CA"]},
            "organization": {"ntee_major_codes": ["K"]},
            "financials": {"total_revenue": {"min": 10000000}},
        },
        "sort": "revenue_desc",
    },
    headers=HEADERS,
).json()

top = search["results"][0]
print(top["name"], top["ein"], top["website"])

# 2. Full profile for the top hit
deep = requests.get(
    "https://api.givalgo.ai/v1/data-pro",
    params={"ein": top["ein"]},
    headers=HEADERS,
).json()
print(deep["financial_profile"]["expense_composition"]["program_expense_ratio"])

JavaScript

const r = await fetch("https://api.givalgo.ai/v1/data", {
  method: "POST",
  headers: { "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ search_terms: "Human Rights Watch" }),
});
const { results, total } = await r.json();
console.log(total, results[0].name, results[0].mission);

Endpoints

The Data API. JSON body with search_terms (EIN / organization name), filters, or an Ask prompt — see Request Body. Returns a page of lean org records; the full field list is under Data API Response.

The same endpoint also answers GET /v1/data?ein={ein} — a body-less convenience for single-org lookups, identical to POSTing {"search_terms": "{ein}", "size": 1}. Changed 2026-07: the deep Form 990 profile formerly served on that URL now lives exclusively on /v1/data-pro.

The deep single-org profile (~410 fields): all core sections plus financials.detail, governance.detail, disclosures, and registration. Documented under Data Pro Response.

Parameters (GET endpoints)

There is no include parameter. The endpoint is the tier contract: /v1/data-pro returns every Pro section on every request, and data_freshness.includes_applied is always ["all"]. An ?include= on the query string is ignored — a request with and without it returns byte-identical JSON. You never need it to obtain a section.

Search Request Body

POST /v1/data takes a JSON body. At least one of search_terms, filters, prompt is required; prompt cannot be combined with the other two (Ask parses the prompt into its own filters).

Filters

Three sections: geography, organization, financials. Filters AND together across fields; lists within a field are OR. Alternate field nesting (organization.properties.*, financials.most_recent_year.*) is accepted for painless migration from other nonprofit data APIs, as are the aliases noted below. Unsupported fields (e.g. subject_codes, county, last_updated) return 400 UNSUPPORTED_FILTER with a hint naming the nearest equivalent.

geography

organization

financials

Ranges are {"min": n, "max": n} objects (either bound optional). Also accepted nested under most_recent_year.

The financial-health screens (ratio, cash, streaks, concentration) aren't available in traditional nonprofit data APIs — they're computed from the full filing history.

Data API Response — the Lean Org Record

{
  "mode": "search",
  "result_kind": "orgs",
  "total": 512,
  "total_is_capped": false,
  "from": 0, "size": 25, "took_ms": 412,
  "suggestion": null,
  "results": [ { /* lean org record */ } ]
}

Each result is a lean org record (~40 fields):

Ask (Natural-Language Search)

Send a prompt and the same pipeline that powers Ask on Givalgo Discover parses it (causes, geography, financial constraints, intent), retrieves deterministically, and semantically reranks. The response adds an interpretation — a plain-English echo of how the prompt was understood.

POST /v1/data
{ "prompt": "private foundations in Ohio funding youth mental health" }

// →
{
  "mode": "ask",
  "result_kind": "funders",
  "interpretation": "Showing foundations based in OH that fund mental health",
  "total": 318,
  "results": [ …top 20… ]
}

result_kind is orgs for most prompts (items = lean org records). Funding-intent prompts return graph-backed kinds with intent-specific item shapes (every item still carries ein + name):

Quota: Ask prompts are LLM-metered and carry a daily budget. Structured searches never touch the quota, and failed or timed-out asks don't count. Over quota returns 429 ASK_QUOTA_EXCEEDED with a quota object and a Retry-After header (next UTC midnight).

Data Pro Response — Top-Level

This section and everything below it document the deep single-org response served by GET /v1/data-pro. (For the Data API's lean search records, see Data API Response.)

Form 990-N (e-Postcard) filers. 1.28 million organizations — 61% of every EIN with a filing on record — have only ever filed the postcard. They return a profile with identity and full IRS registration, and empty financial sections, because the IRS collects no financial data on that form. Check data_availability to tell that apart from a gap. These EINs previously returned 404.

organization

financials

financial_documents New

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

Profitability derivations from financial_trends_analysis.business_model_indicators. Always-on under financial_profile (no include gate).

full_cost_components New

"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

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

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

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. Data Pro only — always present on /v1/data-pro, never on /v1/data. Schedule L lives here, not under governance.detail.

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 carries the Part IV checklist flags. transactions is every Schedule L row for the organization-year in one flat array, and the four named arrays are that same array regrouped by transaction_type (each present only when it has rows).

Do not sum transactions with the four typed arrays — on a Form 990 filer they are the same rows, and adding them double-counts. Use one or the other. The exception is 990-PF filers: self-dealing rows (transaction_type: SelfDealing) appear in transactions and in none of the typed arrays, which are filtered to the Form 990 types.

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. Data Pro only — always present for those filers.

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

registration Pro

IRS Business Master File, Publication 78, and California AG/FTB status, joined at request time. This is registration status — it comes from the agencies, not from the Form 990 filing, so it reflects the org today rather than the tax year you requested.

registration.bmf

Business Master File fields: subsection, classification, foundation_code, deductibility_code, affiliation, ruling_date (YYYY-MM), group_exemption, activity, status, ntee, filing_requirement, pf_filing_requirement, in_care_of, plus the financials_at_ruling snapshot.

Every coded field is also served pre-decoded, so you don’t need to carry IRS code tables:

financials_at_ruling carries a BMF financial snapshot (tax_period, accounting_period_end_month, asset_code/asset_code_label, income_code/income_code_label, asset_amount, income_amount, revenue_amount). Despite the name it reflects the most recent BMF refresh, not the ruling year literally.

registration.pub78

registration.california

CA Attorney General Registry + Franchise Tax Board status — the same shape GET /v1/verify returns as state_compliance.california.

When the checks run: for every organization, since 2026-09-03. The Attorney General's list is not California-only, so there is no "not applicable" case any more.

Two things to get right. NOT_APPLICABLE means the org isn’t California-based and no check ran — it is not a compliance finding, so don’t render it as one. And ag_registry.match_method tells you how much to trust the match: fein is an exact EIN match, while name is a name+city match and is weaker evidence — treat name-matched results as advisory.

For a non-CA org the block is still present with a stable shape:

{
  "trigger": null,
  "ag_registry": null,
  "ftb": null,
  "state_status": "NOT_APPLICABLE"
}

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 D (supplemental financials) highlights, Schedule O (narratives). Also carries summary_extras.gross_receipts, expenses_extras.other_program_service_expenses, reconciliation (Part XII) and reconciliation_part_xi.net_unrealized_gains_losses.

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). Also headcount, schedule_j_flags, activity_indicators, contributions_handling, compliance_filings, schedule_o_explanations, books_in_care_of and liquidation. Schedule L lives under disclosures, not here.

registration

IRS Business Master File (with every coded field also served pre-decoded), Publication 78 listing, and California AG Registry + FTB status. Full field list under registration.

Error Codes

Search-specific errors (POST /v1/data)

FaithVerify API

Verify a church from its name, city and state. No EIN required — and for most churches, none exists.

POST /v1/faith-verify
{"name": "First Baptist Church", "city": "Dallas", "state": "TX"}

Every response carries a verdict with a plain-language recommendation, and the evidence behind it.

Why churches are different

A church is exempt under 501(c)(3) automatically, without applying, and is not required to file a Form 990 or appear in Publication 78 (IRC §508(c)(1)(A)).

Two consequences shape this API:

• The EIN often does not exist. GET /v1/verify starts from one, so it cannot answer for a congregation that never applied.
• Absence from IRS lists is normal, not suspicious. A church missing from Publication 78 has not failed anything — it was never required to be there. Treating that absence as a negative signal would decline legitimate churches at scale.

So FaithVerify gathers evidence in layers and tells you which layer answered, rather than reducing everything to present-or-absent in one list.

Quickstart

curl -X POST https://api.givalgo.ai/v1/faith-verify \
  -H "x-api-key: $GIVALGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "First Baptist Church", "city": "Dallas", "state": "TX"}'

A church the IRS or a denomination vouches for answers immediately:

{
  "triage":   { "status": "resolved", "matched_in": ["denominational_directory", "irs_bmf"] },
  "irs":      { "ein": "75-0800696", "irs_classified_church": true },
  "verdict":  { "status": "ELIGIBLE", "deductible": true, "basis": "group_exemption" }
}

If the records do not settle it, you get 202 and a poll URL instead — see Website evidence.

Verify a church

POST /v1/faith-verify

Poll a website review

GET /v1/faith-verify/{job_id}

Returns the complete verification — triage, irs, denominational, website_evidence and verdict — not just the crawl. You never hold half an answer.

The record-layer findings are exactly as they stood when the job was created, so the verdict stays pinned to the facts that produced it.

Cadence: most reviews finish in under two minutes. Poll first at ~20s, then every 10s, and give up after 5 minutes.

status is queued or running while it works, then done — including when the review was inconclusive, which is a result rather than a failure. failed means our own error and is safe to retry.

Job ids are scoped to the key that created them; polling another key’s returns 404.

Three outcomes

All three return 200. Branch on triage.status.

A name that identifies a town is not an answer. Some denominations file congregations under the place rather than a congregation name — an LDS ward listed as Batesville, a Kingdom Hall listed as its address. Such a record is only returned when you wrote that same name; ask about a different church in that town and you get needs_street with the addresses to choose from, never the ward.

A church one town over is still found. Congregations routinely file with the IRS under a neighbouring municipality, so matching your city exactly reports real churches as missing — A Restoration Church, Glenview IL is in the IRS file under Northbrook, 3.8 miles away. When your city matches nothing, we search the towns within 5 miles and return triage.nearby_city_match naming the city we actually found it in and the distance. A church in the town you named always wins; the radius is only a fallback.

When we hold no record of your church, the website review runs. That is what it is for. We ask you to choose an address only when the choice is real — several congregations we genuinely cannot tell apart, or a record carrying your church's name at a different address. If nothing we hold matches the name you gave, you get not_found and a website review, not a list of other people's churches.

needs_street and not_found are answers, not errors. Your request was well-formed; we could not settle it. A 4xx would put them in the same bucket as a malformed body and invite a retry instead of an action.

A city holds six Kingdom Halls and four St Mary’s. When a name identifies a denomination and a town rather than a congregation, guessing would produce a confidently wrong answer — so we ask instead.

The three evidence layers

Gathered strongest first, stopping at the first that answers. An answer from the IRS is not improved by reading a website.

Many churches are covered by a denomination’s group exemption rather than holding their own determination. We follow that link: a subordinate not listed in Publication 78 is checked against its parent, and irs.group_exemption reports the parent’s EIN and standing.

Website evidence

Reached only when neither record layer settles the question. We find the church’s website — for most we have no URL on file — confirm it belongs to that congregation, read it, and grade five criteria.

Each carries a status, a summary, and evidence_url — the page the finding came from, so you can check it yourself.

Every value is verified against the page

Anything you might act on — an address, a phone number, an email, a service time, a person’s name — is dropped if we cannot find it on the page we read, and listed in facts.unverified_dropped. That distinction matters: “the church publishes no phone number” and “a phone number was produced that we could not confirm” are different facts.

Doctrinal statements are kept with verbatim: false when they are close paraphrases rather than quotes.

not_found is not fail

A criterion is not_found when no page addressing it was available to read, and fail when the topic was covered and the characteristic was genuinely absent. A church with a thin website has not failed the test.

What a denominational listing means — and what it does not

A listing is evidence the congregation exists and is affiliated with that body. It is not confirmation of IRS group-exemption coverage. Where coverage exists we report it from the organisation’s own IRS record, under irs.group_exemption — never inferred from the directory, and never estimated from how the denomination usually files.

We measured the difference rather than assuming it. For up to 300 congregations per directory we found the organisation in the IRS Business Master File and read its affiliation code: subordinacy is the norm for some bodies (ELCA 99%, LCMS 99%, Assemblies of God 90%) and rare for others (UPCI 29%, LDS 9%). That measurement is why this endpoint no longer tells you a listing means the denomination’s group ruling covers the congregation — for several bodies that was simply untrue.

⚠️ We deliberately do not publish that per-denomination rate as a field. affiliation and group_code are Business Master File columns, so being recorded as a group subordinate requires an IRS record. A congregation that has one already has its own answer in irs.group_exemption; a congregation that has none is excluded from the population the rate was measured on, and its absence is if anything mild evidence against coverage. A denomination-level average shown beside it would reassure in the wrong direction.

What the sanctions screening covers

The organization’s name, and nothing else. A church does not file a Form 990 — that is the premise of this endpoint — so we hold no officer or director records for one. Rather than return an empty leadership_screening block that reads as “we checked the leadership and found nothing”, the block is omitted and sanctions_screening.scope says what was covered.

⚠️ Leaders named on the church’s own website appear under website_evidence and have not been screened. If a church does have officers on record, the leadership_screening block is present and real.

We do not score it

evidence.tally counts the five criteria by status — pass, partial, fail, not_found. That is all it does. There is no threshold and no pass mark, because the IRS sets none: its own guidance says “there is no minimum number of criteria an organization must meet” and warns that a numerical approach “might unconstitutionally favor established churches at the expense of newer, less traditional institutions”. We collect the evidence; the rule for acting on it is yours.

Results are cached for 30 days per church. Two requests arriving together share one crawl.

Limited release

FaithVerify is enabled per API key while we finish validating it against real queries. If your key does not have access yet, every FaithVerify route answers 403 with error: "FORBIDDEN" — your key is fine, this endpoint just is not switched on for it. Email support@givalgo.ai to request access. Every other endpoint is unaffected.

Verdicts

The status says where the church was found, not how eligible we judge it. What was found lives in deductible, basis and message.

⚠️ Revocation is the exception, and it has its own status. Everything else the status tells you is where we found the church; deductible and basis tell you what we found. One case is not visible in the status at all: a church whose IRS row contradicts itself returns FOUND_IRS with deductible: null and basis: "irs_church_classification_contradicted". Branch on deductible and basis if that matters to you.

verdict.basis names what the answer rests on, and verdict.recommendation says what to do next in plain words.

Deductibility code 2 does not by itself decline a church. Where Publication 78 or a group ruling settles the question, deductible stays true and the contradictory code is reported next to it — the code is applied inconsistently even within a single group ruling, so it is not treated as decisive. Where the church classification is the only basis, nothing outvotes it: deductible becomes null and the basis is irs_church_classification_contradicted. /v1/verify answers the same way for the same organization.

Website evidence never moves the verdict at all. It stays UNDETERMINED with basis: "website_evidence", and the marks, the extracted facts and the tally are attached for you to judge. Five characteristics on a website are not an IRS determination — and neither is a count of them, which is why we stopped publishing one.

Research API

Pass a nonprofit's website URL or its EIN and get back the fields the organization states about itself. Today that is its mission.

With an EIN we resolve the organization's website for you, from IRS filings and our own verified records — useful when your own records are stale, incomplete, or point at a domain that has since lapsed.

This endpoint reads the organization's website and nothing else. It is not derived from Form 990 — for filing data use the Data API. The two pair naturally: Data Pro tells you what an organization filed, Research tells you what it says.

It is also not a generic web scraper. You do not get HTML or markdown to post-process; you get named fields, each carrying the exact URL it came from.

Authentication

Send your API key in the x-api-key header on every request, exactly as with the other Givalgo APIs.

curl https://api.givalgo.ai/v1/research \
  -H "x-api-key: YOUR_API_KEY"

Don't have a key? Contact support@givalgo.ai.

Quickstart

Step 1 — submit. Send a url, an ein, or both. At least one is required.

By website:

curl -X POST https://api.givalgo.ai/v1/research \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"url": "https://www.hrw.org", "ein": "13-2875808"}'

By EIN alone — we resolve the website ourselves:

curl -X POST https://api.givalgo.ai/v1/research \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"ein": "13-2875808"}'

The response's url_source tells you which happened: caller if we used the URL you sent, discovered if we resolved it.

{
  "job_id": "rj_evtOorsq7NkVSx6AUNs4Rw",
  "status": "queued",
  "host": "hrw.org",
  "poll": "/v1/research/rj_evtOorsq7NkVSx6AUNs4Rw",
  "cached": false,
  "expected_ready_in_seconds": 30
}

Step 2 — poll for the result.

curl https://api.givalgo.ai/v1/research/rj_evtOorsq7NkVSx6AUNs4Rw \
  -H "x-api-key: YOUR_API_KEY"

{
  "job_id": "rj_evtOorsq7NkVSx6AUNs4Rw",
  "status": "done",
  "host": "hrw.org",
  "url": "https://www.hrw.org",
  "fetch_status": "ok",
  "cached": false,
  "crawled_at": "2026-08-10T22:44:29Z",
  "pages_crawled": 3,
  "fields": {
    "mission": {
      "value": "Everything we do circles back to our commitment to justice, dignity, compassion, and equality.",
      "kind": "unlabeled",
      "source_url": "https://www.hrw.org/about-us",
      "verbatim": true
    },
    "mission_proxy": null
  }
}

Polling

Every submit returns 202 with a job_id — including when we already hold a recent result for that website. There is no synchronous variant, so your integration has one code path no matter how slow the target site is.

A crawl typically completes in 15–30 seconds. Poll first at about 20 seconds, then every 10 seconds, and give up after 5 minutes.

If you would rather not poll at all, tell us — a webhook callback is on the roadmap and customer demand sets its priority.

Submit a job

POST /v1/research

Returns 202 with job_id, host, poll, cached, url_source, and expected_ready_in_seconds.

status is queued when a crawl has started, or done when the answer is already available — a website we hold a recent result for, or a request that resolved to nothing crawlable. The result is never in this response either way, so always poll; done just means the wait is nil.

Sending a URL, an EIN, or both

At least one is required. What you send changes what we can do for you.

The response always reports which we used:

You are never silently redirected — if we crawled a different site than you asked about, url_source and url say so.

Why a mission can be missing

A null mission always comes with a reason. The first three are settled answers about the organization; the rest are about one website read that did not work.

Poll a job

GET /v1/research/{job_id}

status is queued or running while the crawl is in flight, then done. A failed status means the job errored on our side.

Job IDs are scoped to the API key that created them. Polling another key's job returns 404 JOB_NOT_FOUND.

Mission & mission_proxy

These are two separate fields, and the distinction is the point of the API.

If you want only what the organization actually wrote, read mission and ignore mission_proxy entirely. Both may be null — some websites simply don't say.

The kind field

Both are quoted verbatim — kind only tells you where on the site the sentence sits. Many nonprofits never write the words "Our Mission" but state one perfectly clearly, and unlabeled is how you get it.

Fetch statuses

fetch_status tells you how the crawl went. Anything other than ok or partial means we returned less than we wanted to.

We identify ourselves honestly as GivalgoResearchBot and honor robots.txt. Some sites will legitimately yield nothing.

Caching

Results are cached for 30 days per website. Caching is keyed on the website's host, so example.org, www.example.org, and https://WWW.Example.org/about all resolve to the same cached result.

Cached results do not count against your daily quota. Two fields tell you what you got:

Pass force_refresh: true to bypass the cache. Forced requests always count against your quota.

Organizations API

List every nonprofit in a place — a county, a city, a ZIP, or a whole state — with a lean identity-and-location record and a cursor that does not run out.

Built for the case where you need the whole set rather than the best matches: a community foundation mapping its service area, a directory keeping a county in sync, a dashboard counting nonprofits per county.

When to use this instead of the Data API

Rule of thumb: if you would page through more than a couple of hundred results, or you need a county, use this endpoint. If you are searching by name, mission or cause, use the Data API.

Quickstart

Every 501(c)(3) in Harris County, Texas — a hundred at a time:

curl -H "x-api-key: $GIVALGO_API_KEY" \
  "https://api.givalgo.ai/v1/organizations?state=TX&county=Harris&subsection=03&limit=100"

{
  "organizations": [
    {
      "ein": "01-0610009",
      "name": "HOPE CENTER INC",
      "dba_name": null,
      "street": "3618 STASSEN ST",
      "city": "HOUSTON",
      "state": "TX",
      "zip": "77051-1544",
      "county": "Harris County",
      "ntee_code": "T20",
      "ntee_source": "irs",
      "subsection": "03"
    }
  ],
  "count": 100,
  "next_cursor": "010610009",
  "has_more": true
}

Then walk the cursor until has_more is false:

curl -H "x-api-key: $GIVALGO_API_KEY" \
  "https://api.givalgo.ai/v1/organizations?state=TX&county=Harris&subsection=03&limit=100&cursor=010610009"

List organizations

One endpoint. view chooses what comes back — organizations (the default), counts, or the change feed — and every filter below means the same thing in all three.

A scope is required — at least one of state, county, city or zip. Enumerating the whole Business Master File (1,957,340 organizations) is a bulk export rather than a page; contact us if that is what you need.

Typical latency is ~90ms state-wide and ~180ms for a county, regardless of how large the county is.

A city is not a metro

These three scopes answer three different questions about “Houston”:

The city field is the municipality the organization files under, which is not the same as the area it serves. For a metro, request each county and merge.

Filters

All four endpoints take the same filter vocabulary, so learning one teaches you the rest.

Regions

Rather than naming counties, ask for a region. region uses the same vocabulary as Ask, so “Bay Area” means the same set of organizations in both products. It counts as a geographic scope on its own — no state needed.

Multi-state regions — these constrain the state:

deep south, east coast, great lakes, gulf coast, mid-atlantic, midatlantic, midwest, new england, northeast, northwest, pacific northwest, rust belt, rustbelt, southeast, southwest, sun belt, sunbelt, tri-state, tristate, west coast

Sub-state regions — these constrain state and city:

Hyphens, underscores and capitalisation are ignored, so Bay Area, bay-area and BAY_AREA are the same request.

How a sub-state region is defined

A sub-state region matches its counties OR its cities — a union, not an intersection.

Counties are the primary definition: socal is the ten Southern California counties (Imperial, Kern, Los Angeles, Orange, Riverside, San Bernardino, San Diego, San Luis Obispo, Santa Barbara, Ventura). The city list is kept as a safety net, because 7.9% of organizations have a ZIP the US Census crosswalk cannot place and so carry no county at all — 1,566 of them in Houston alone. Matching on counties only would silently drop them.

Regions deliberately overlap where geography does: Santa Barbara and Ventura are both socal and central coast; Kern is both socal and central valley; Brevard is both central florida and space coast. A nonprofit in Ventura is honestly in both, and forcing a partition would mean picking a loser.

Passing a state the region does not contain returns 400 REGION_STATE_CONFLICT rather than an empty page — an empty page reads as “no organizations here” when the truth is that the two filters contradict each other.

⚠️ region and county answer different questions

region is a curated list of city names. county is exhaustive by geography. For the same metro they do not return the same set:

The county form finds 9% more, because county lines also catch the smaller towns nobody lists by name. Use region to match how Ask talks about a place; use county when you need every organization in it.

County names are not unique

There are 30 Washington Counties and 25 Jefferson Counties in the United States, so county without state returns 400 COUNTY_NEEDS_STATE rather than guessing. A name we do not recognise returns 400 UNKNOWN_COUNTY with the near misses:

{
  "error": "UNKNOWN_COUNTY",
  "message": "No county named 'Harrs' in TX.",
  "hint": "Did you mean: Harris County, Harrison County?"
}

A typo gets an answer that names the problem, never an empty page that reads as “no organizations here”.

Choosing an NTEE source

Roughly a quarter of registered nonprofits were never assigned an NTEE code by the IRS. We infer codes for many of them, and ntee_source decides whether the ntee filter considers those:

What each tier is worth, across all 1,957,340 registered organizations:

Every record reports which tier produced its code in ntee_source, so an inferred code is never mistaken for an IRS one. Reach for inferred when recall matters — building a candidate list — and stay on irs when you are going to act on the classification.

Note: POST /v1/data folds inferred codes into its NTEE matching with no way to opt out. The same ntee=B therefore returns different counts on the two endpoints. This endpoint defaults to IRS-only on purpose.

The record

Two forms of every string

name, street and city come back exactly as the IRS publishes them, which means ALL CAPS — HOPE CENTER INC, HOUSTON, 3618 STASSEN ST. That is the stable form, and the one to match against your own records.

Alongside each is a display-cased twin:

These are additional fields, not replacements. Match on the verbatim ones, render the display ones. Nothing you already integrated against changes.

Casing is computed once per Business Master File reload and shared with the rest of the platform, so the same organization can never appear differently in two places. It is a hard problem — YMCA is an acronym, KNIGHTS is a word, CT is Connecticut in a name and Court in an address — so a display field is null rather than wrong when we have not computed one yet.

Sorting

Default is ein — a stable enumeration order, which is what you want when mirroring a place. Add sort to rank instead.

curl -H "x-api-key: $GIVALGO_API_KEY" \
  "https://api.givalgo.ai/v1/organizations?state=TX&county=Harris&subsection=03&sort=revenue_desc&limit=1000"

That is the 1,000 largest charities in Houston — Memorial Hermann Health System, Methodist Hospital Group, Texas Children's Hospital, and on down to about $700K.

⚠️ Only 28.6% of organizations have a revenue figure

Across all 1,957,340 registered organizations:

An organization filing the 990-N postcard reports no revenue at all, and the IRS records that as 0 as often as it leaves it blank. So revenue_desc ranks the 28.6% that have a figure and then trails everything else in EIN order.

Those organizations are unmeasured, not small. A top-1,000 or top-5,000 is sound. Paging deep into a revenue sort is paging through unranked rows.

⚠️ revenue_asc is rarely what you want. “Smallest first” returns 825,946 zero-revenue organizations before it reaches anything with a real figure. It exists for symmetry with the Data API.

Keep sort constant across a walk

The cursor encodes the ordering it was issued under. Handing a cursor to a different sort returns 400 INVALID_CURSOR rather than silently skipping or repeating rows. Every response echoes sort so you can assert it never changed.

Pagination

Cursor-based, with no depth ceiling. Read next_cursor from each response and pass it back as cursor; stop when has_more is false.

cursor = None
while True:
    params = {"state": "TX", "county": "Harris", "limit": 500}
    if cursor:
        params["cursor"] = cursor
    r = requests.get("https://api.givalgo.ai/v1/organizations",
                     params=params, headers={"x-api-key": KEY}).json()
    yield from r["organizations"]
    if not r["has_more"]:
        break
    cursor = r["next_cursor"]

Pick a page size deliberately

Larger pages are markedly cheaper per organization. Measured over a full California enumeration (176,698 organizations):

If you are mirroring a whole state, use limit=2000. Fewer calls is also a smaller bill.

Responses are compressed

Send Accept-Encoding: gzip — every HTTP client does by default — and responses come back gzipped. This JSON compresses well because the same keys repeat once per organization: a 1,000-row page is 374KB raw and 78KB compressed, a 79% saving. A 2,000-row page is roughly 156KB on the wire.

If your client does not send the header you still get plain JSON, byte for byte as before.

Treat the cursor as opaque — a value we did not issue returns 400 INVALID_CURSOR. Ordering is stable (by EIN), so a page never repeats or skips a record while you walk.

Counts — view=facets

The dashboard question — “how many nonprofits in each county in Texas?” — answered without transferring 153,779 records.

Takes the same filters as the list endpoint plus a required by: county, city, state, ntee or subsection.

curl -H "x-api-key: $GIVALGO_API_KEY" \
  "https://api.givalgo.ai/v1/organizations?view=facets&state=TX&by=county&limit=5"

{
  "dimension": "county",
  "facets": [
    { "value": "Harris County",  "count": 20207 },
    { "value": null,             "count": 18709 },
    { "value": "Dallas County",  "count": 14117 },
    { "value": "Tarrant County", "count":  9691 },
    { "value": "Travis County",  "count":  9143 }
  ],
  "total": 153779,
  "truncated": true
}

null is a real bucket

That second row is not a bug. Those 18,709 organizations have a ZIP that is absent from the US Census crosswalk, so we cannot place them in a county. They are included as their own bucket so the counts sum to total — if we hid them you would have no way to tell missing coverage from genuine absence.

total counts everything matching your filters across every bucket, so it stays correct even when limit truncates the list. truncated tells you whether it did.

by=county and by=city require a state (or narrower) scope — counting every county in the country reads the entire dataset.

Newly formed — a filter, not a view

“Who just formed in my service area?” is not a separate view — it is a filter (ruling_since) and an ordering (sort=ruling_desc) over the same rows. Every record carries a ruling_month.

Because it is a plain filter it composes with any sort, which a dedicated endpoint could not do. The largest organizations formed since 2015:

curl -H "x-api-key: $GIVALGO_API_KEY" \
  "https://api.givalgo.ai/v1/organizations?state=TX&county=Harris&ruling_since=2015-01&sort=revenue_desc"

curl -H "x-api-key: $GIVALGO_API_KEY" \
  "https://api.givalgo.ai/v1/organizations?state=TX&county=Harris&ruling_since=2026-01&sort=ruling_desc"

since is a month, not a day, because that is the resolution the IRS publishes.

Two things this date is not

• A determination can be backdated, so a ruling month is not the month the organization appeared in our data.
• The IRS Business Master File reloads monthly, so “new since last month” can lag reality by up to that reload.

It is still the right field: it is the only date the IRS publishes for this, and it never changes — re-running the same query tomorrow gives the same answer for the same period.

The cursor here is a composite YYYYMM:EIN, because ordering is by ruling month and many organizations share one. Treat it as opaque, like any other cursor.

Changes — view=changes

An append-only feed of material changes, so you can keep a mirror current without re-enumerating a whole county.

Call it once without since_id and keep the next_cursor; from then on pass that cursor as since_id and you receive only what has happened since. A geographic scope is optional here — the cursor already bounds the response.

curl -H "x-api-key: $GIVALGO_API_KEY" \
  "https://api.givalgo.ai/v1/organizations?view=changes&state=TX&county=Harris&since_id=448817"

What this feed does not cover

This reports things that happened to an organization. It does not report edits to the fields this API returns: an organization that renames itself or moves across town emits no event.

Every response repeats this in a covers object, because assuming otherwise is the expensive mistake — you would hold a stale name indefinitely with nothing to tell you. To pick those up, re-enumerate the scope periodically; monthly matches the IRS reload cadence.

The feed is bursty, not daily

IRS batches land every 21–35 days. A daily poll sees nothing for three weeks and then tens of thousands of events at once — that is normal, not an outage. Page the cursor rather than assuming a day fits in one response.

Coverage & caveats

Everything worth knowing before you build on this, in one place.

What the list contains

The universe here is the IRS Business Master File — organizations the IRS currently recognises as tax-exempt. Organizations that lost exemption drop off the BMF and therefore out of these results.

This endpoint tells you an organization exists and is registered. It does not tell you a donation to it is deductible today — that is Charity Verify, which checks Publication 78, the auto-revocation list and OFAC. Enumerate here, verify there before you grant.

Freshness

The Business Master File reloads monthly, so registration facts move on that cadence. The change feed detects new filings daily, but those arrive in IRS batches every 21–35 days.