API Documentation

Base URL: https://charityverify.com

Authentication: Include X-API-Key: your_key_here header with every request (except /health).

Quick Start

curl -H "X-API-Key: YOUR_KEY" https://charityverify.com/v1/verify/119219814RR0001

Rate Limits & Pricing

Tier	Requests/Month	Compliance & Benchmarks	Contacts	Price
Pro	1,000	Yes	Yes	Included with Pro ($39/mo)
Research	10,000	Yes	Yes	$149/mo	Get Research
Enterprise	Custom	Yes	Yes	Custom	Contact Sales

Endpoints

Health

GET/health

Health check. No authentication required. Returns DB status, charity count, last sync time.

Core

GET/v1/verify/:business_number

Quick verification. Returns status, category, trust grade, and flag summary.

GET/v1/charity/:business_number

Full charity detail including directors, trust score, financials, and compensation.

GET/v1/search?name=&limit=

Search charities by name. Limit: 2-100 results.

Historical Data

GET/v1/charity/:bn/financials?year=&from=&to=

Financial data (2009-2023). Revenue, expenditures, assets, liabilities, program spending.

GET/v1/charity/:bn/compensation?year=&from=&to=

Employee compensation data with salary bracket distribution.

GET/v1/charity/:bn/flows?direction=&limit=

Charity-to-charity donation flows. Filter by donor, recipient, or both.

GET/v1/charity/:bn/programs

Charitable program descriptions.

GET/v1/charity/:bn/international

International activities by country with expenditures.

GET/v1/charity/:bn/political

Political activity records.

GET/v1/charity/:bn/trend

Financial trend summary with revenue change percentage.

Directors

GET/v1/directors/:business_number

List directors for a charity with positions.

Peer Benchmarks

GET/v1/benchmarks?category=0160&revenue_band=large

Peer benchmark distributions by charity category and revenue band. Free tier returns sector medians (p50). Pro and API tiers return full distributions (p10–p90).

Example response (Pro tier)

{
  "category": "0160",
  "revenue_band": "large",
  "tier": "pro",
  "metrics": {
    "program_ratio": { "p10": 0.52, "p25": 0.68, "p50": 0.79, "p75": 0.87, "p90": 0.94, "sample_size": 312 },
    "comp_ratio": { "p10": 0.08, "p25": 0.18, "p50": 0.31, "p75": 0.44, "p90": 0.58, "sample_size": 312 },
    "reserves_months": { "p10": 1.2, "p25": 3.8, "p50": 8.4, "p75": 18.6, "p90": 42.1, "sample_size": 312 },
    "revenue_cagr": { "p10": -0.12, "p25": -0.02, "p50": 0.04, "p75": 0.11, "p90": 0.24, "sample_size": 312 }
  }
}

GET/v1/benchmarks/export?category=0160&revenue_band=large

CSV export of benchmark data for a category and revenue band. Requires Research tier or higher.

Trust Scores

GET/v1/risk/:business_number

Full trust score breakdown: legitimacy, effectiveness, compliance, grade, flags. Full component data requires Pro or higher tier.

GET/v1/risk/:bn/history

Score history over time (up to 50 entries).

POST/v1/charity/:bn/comment

Submit a community comment for moderation. Body: { "comment_text": "...", "submitted_by": "..." }

GET/v1/stats/distribution

Aggregate trust grade distribution across all scored charities.

Webhooks

POST/v1/webhooks/subscribe

Subscribe to status changes. Body: { "business_number": "...", "callback_url": "https://..." }

DELETE/v1/webhooks/:subscription_id

Deactivate a webhook subscription.

GET/v1/webhooks

List your active webhook subscriptions.

Error Codes

Code	Meaning
`401`	Missing or invalid API key
`404`	Charity not found
`429`	Monthly rate limit exceeded
`500`	Internal server error