CauseComp API & connector docs

POST /executive/benchmark

Executive (officer / leadership) benchmark from 990 Schedule J.

Example request

curl https://www.causecomp.org/api/v1/executive/benchmark \
  -H "Authorization: Bearer cc_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"role": "Executive Director / CEO", "ntee_sector": "Human Services",
       "state": "CA", "revenue": "$5,000,000"}'

Example response

{
  "benchmark": {
    "p10": 97714, "p25": 121425, "median": 156421, "p75": 199200, "p90": 243426,
    "confidence": "Medium", "n_obs": 6070,
    "revenue_band": "$5M-$10M", "col_tier": "Tier 1 - Very High",
    "data_vintage": "990 data + trend projection (projected 2025 to 2026)",
    "method": "990 gradient-boosted quantiles + peer-cohort anchor + ECI aging",
    "base_median": 159464, "bonus_median": 0, "benefits_median": 9600, "other_median": 0,
    "retirement_deferred_median": 4703, "retirement_deferred_pct_nonzero": 0.668,
    "base_n_disclosed": 1219, "bonus_n_disclosed": 897, "benefits_n_disclosed": 1050,
    "other_n_disclosed": 870, "retirement_deferred_n_disclosed": 989,
    "components_cohort_n": 2025,
    "is_bls_primary": false
  },
  "input": { "role": "Executive Director / CEO", "ntee_sector": "Human Services",
             "state": "CA", "revenue_raw": "$5,000,000", "org_type": null },
  "disclaimer": "CauseComp provides comparability data for informational purposes and does not provide legal or tax advice. ..."
}

Also returned: n_obs_typed, org_type_cohort_used, warning, pct_nonzero ratios for every pay component, and p10/p25/p75/p90 for each pay component (base, bonus, benefits, other, retirement_deferred). When a cohort has 1–9 comparable filings the benchmark is served with a low_confidence flag.

Component semantics (July 2026). Component percentiles are computed across the peers that itemize that component on Schedule J: a reported $0 is included, an undisclosed amount is excluded, and the *_pct_nonzero denominator is the disclosing peers. Each component carries an additive *_n_disclosed count alongside components_cohort_n. When fewer than 20 peers disclose a component, or under 20% of the component cohort discloses it, that component's percentile and pct_nonzero keys are served as null (insufficient disclosure) — key names and positions are unchanged.

POST /workforce/benchmark

Broad-based staff benchmark from BLS OEWS/ECEC + O*NET.

Example request

curl https://www.causecomp.org/api/v1/workforce/benchmark \
  -H "Authorization: Bearer cc_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"role": "Registered Nurse", "state": "IL", "ntee_sector": "Health",
       "revenue": "$10,000,000", "level": 2, "mode": "nonprofit"}'

Example response

{
  "benchmark": {
    "p10": 77153, "p25": 89900, "median": 109172, "p75": 125735, "p90": 153848,
    "confidence": "High", "n_obs": 51,
    "revenue_band": "$10M-$25M",
    "data_vintage": "BLS OEWS May 2025 (aged to Jul 2026)",
    "method": "BLS OEWS primary + ECI aging + state ratio + industry adjustment",
    "seniority_tier": "Mid (Tier II)", "is_bls_primary": true, "mode": "nonprofit",
    "role_description": "Direct nursing staff in the provision of patient care ..."
  },
  "input": { "role": "Registered Nurse", "ntee_sector": "Health", "state": "IL",
             "revenue_raw": "$10,000,000", "mode": "nonprofit" },
  "disclaimer": "CauseComp provides comparability data for informational purposes and does not provide legal or tax advice. ..."
}

Incentive and benefits-load fields (incentive_p50_pct, total_cash_p50_usd, benefits_load_pct, …) are populated for roles with ECEC incentive coverage and null otherwise.

POST /comparables

The §4958 comparable organizations behind an executive benchmark. Same inputs as /executive/benchmark (role, ntee_sector, state, revenue; optional ntee_subsector). This is the compliance layer for a board file.

Example response (20 organizations)

{
  "comparables": [
    { "org": "CREATIVE SUPPORT", "city": "HUNTINGTN BCH", "state": "CA",
      "fiscal_year": 2023, "title": "Executive Director", "sector": "Human Services",
      "ntee_code": "P20", "ntee_description": "Human Service Organizations",
      "total_comp": 200000, "revenue": 4976979 },
    { "org": "YOUNG WOMENS FREEDOM CENTER", "city": "SAN FRANCISCO", "state": "CA",
      "fiscal_year": 2020, "title": "Executive Director", "sector": "Human Services",
      "ntee_code": null, "ntee_description": null,
      "total_comp": 162885, "revenue": 5028928 }
    // ... 20 organizations total
  ],
  "disclaimer": "CauseComp provides comparability data for informational purposes and does not provide legal or tax advice. ..."
}

GET /meta/exec_roles  ·  GET /meta/roles

Valid executive role labels / workforce role labels. Optional ?search= substring filter resolves fuzzy input to a canonical label before you benchmark (avoids an unrecognized_role error).

GET /api/v1/meta/exec_roles?search=chief
{ "roles": ["Chief Administrative Officer", "Chief Compliance Officer",
             "Chief Data Officer", "Chief Development Officer", "..."] }

GET /api/v1/meta/roles?search=nurse
{ "roles": ["Nurse Practitioner", "Registered Nurse",
             "Licensed Vocational Nurse (LVN)", "Nurse Anesthetist (CRNA)", "..."] }

GET /meta/metros

Metro areas (MSAs) for a state, largest employment first — the valid msa codes a benchmark call can pass. ?state= is required.

GET /api/v1/meta/metros?state=IL
{ "metros": [ { "code": "16980", "name": "Chicago-Naperville-Elgin, IL-IN" },
              { "code": "37900", "name": "Peoria, IL" },
              { "code": "40420", "name": "Rockford, IL" } ] }

GET /meta/sectors

Valid NTEE sector labels for the ntee_sector input. No parameters. sectors_detail pairs each label with its NTEE major-group letter (sorted by code); pass the bare label as the ntee_sector input.

GET /api/v1/meta/sectors
{ "sectors": ["Arts, Culture & Humanities", "Civil Rights",
               "Community Improvement", "Education", "..."],
  "sectors_detail": [
    { "code": "A", "label": "Arts, Culture & Humanities" },
    { "code": "B", "label": "Education" }
    // ... 26 NTEE major groups, A–Z
  ] }