CauseComp

Return the **board packet**: the same board-ready §4958 PDF the CauseComp website generates — the modeled benchmark, the comparables set with its own P10–P90 ladder, the composition sentence, and the disclaimer. The result is a text summary (``composition``, ``disclaimer``, ``sha256``, ``size``) that carries ``download_url``: a link to the PDF, valid for 24 hours (``download_expires_at``) and only for the CauseComp account that ran the report. The PDF the link opens is the deliverable, for the user. With attach_pdf set to true the PDF is instead embedded in the result as an ``application/pdf`` resource. The ``disclaimer`` is for the user, and the ``composition`` line states how many of the peers listed are in the requested sector and state, and the national pool they were drawn from. Composition is neutral context, not a warning. With organizations, the comparables section, its P10-P90 ladder and composition come from what those organizations filed; composition then carries no national pool, and supplied lists any organization that could not be listed, with the reason. Requires a CauseComp account with connector access. Without connector access the tool returns a short explanation. An unrecognised role, sector or state returns a correction carrying the valid vocabulary. A cohort with no comparable filings, with none in the requested sector, or with fewer than three organizations to list is refused rather than rendered; each such refusal offers the report without a comparables section.

get_board_report

Return the §4958 **comparables set** for the same inputs as an executive benchmark — peer nonprofits with their reported compensation, drawn separately from the modeled figure, which they do not produce. The comparables set is the comparability-data prong of a §4958 review. The presumption also requires advance approval by an independent board body and contemporaneous documentation; the ``disclaimer`` states this. Returns a ``comparables`` list, a ``composition`` block, a ``disclaimer``, and, for a set CauseComp selects, a ``note`` for the user on how to read ``composition``. Each row also carries the organization's mission as it filed it on its Form 990 (mission) and mission_display: that text, or, where the filer wrote only a pointer such as "See Schedule O", the text it pointed to, with mission_display_source naming where it came from. Requires a CauseComp account with connector access. Without connector access the tool returns a short explanation. This tool returns structured numbers only; the board-ready PDF comes from get_board_report. ``composition`` carries ``n``, ``in_state``, ``in_sector``, ``in_sector_n`` and ``n_national``; ``in_state`` counts the listed peers in the requested state, out of ``n``, and ``n_national`` is the national pool they were drawn from. ``n_national`` is the number of ORGANIZATIONS the peer query can draw from nationally for this role and size: the roster's own revenue fence and filing window with the limit removed. It is not a count of filings and it does not narrow by sector. ``in_sector_n`` is how many of the listed organizations are in the benchmark's own sector, which is the number a board checks first. With ``peer_sectors`` given, ``composition.sectors`` echoes the set the peers were ranked toward and ``in_sector`` counts membership in it; the benchmark itself is still for ``ntee_sector`` alone. Composition is neutral context, not a warning. State and sector favor organizations rather than restrict the set to them, so a peer set legitimately includes organizations from other states where in-state filings are few. When ``composition.local_mix_kept`` is true, the set was drawn up to half from the same NTEE subsector nationwide and the rest from the same NTEE major group, organizations in the requested state first. An out-of-state filing in the same role, sector and revenue band is a valid comparable, and a set drawn from a deep national pool is sound comparability evidence. A low ``in_state`` read without ``n_national`` suggests the opposite; confidence keys on the national cohort, not the in-state share. A set can list fewer than three organizations; ``composition.below_three`` is then true. Unless the result also carries ``widened``, the ``note`` then says so, and a board report for the same inputs is refused and offers the benchmark-only report.

get_comparables_set

Benchmark total compensation for a nonprofit **executive/leadership** role from IRS Form 990 data (Schedule J + Part VII, incl. 990-EZ filers), sourced directly from IRS e-file disclosures. The served benchmark is fit on the full corpus of filing years (2016 onward today; the bundle manifest records the vintage), unadjusted for filing year. Returns a ``benchmark`` object with P25 / median (P50) / P75 (and P10/P90, and base / bonus / other reportable / retirement & deferred / nontaxable rows that are MODELLED SHARES of that total - each at or under its total. Components may not sum exactly to the total. Figures based on fewer than 10 filings are noted: ``components_under_10_filings`` lists those rows; ``components_basis`` says what the rows are; on an aged request every component is projected by the total's factor and ``components_aged`` is true), ``bonus_label`` / ``bonus_prevalence_pct`` / ``bonus_typical_pct`` - of executives paid about the median, across all roles and sectors, the share who received a bonus and the typical bonus as a share of pay among them (null below 150,000 USD), ``geographic_basis`` - the geography the figure rests on, ``metro`` / ``state`` / ``national``, derived from what the engine applied - with ``geographic_fallback_reason`` (``unknown_msa``, ``metro_cell_unmeasured``, or ``msa_not_applicable`` on a BLS-served role, which has no metro layer) whenever an ``msa`` was passed and is not the basis, the data vintage, and a ``disclaimer`` for the user. The ``input`` block echoes every parameter as interpreted, ``msa`` and ``ntee_subsector`` included. ``role_filings_note`` is set when this role has few or no filings at this revenue (fewer than 45 filings within about 24% of it), as a sentence that goes with the figures. At a revenue of 0 there is no modeled figure: ``modelled_figure`` is false, every percentile is null, and ``no_modelled_figure_reason`` says why. There is no mean on the wire. ``predicted_mean`` is computed and then removed before the response is built, so the response has no mean field. ``confidence`` is a DEPTH-OF-EVIDENCE label, not a statistical confidence interval, and no interval is published around the figure. It is set by the number of Form 990 filings for this role within a one-third to three-times revenue window; sector and state do not enter that count, and it is counted separately from the comparables set. ``confidence_basis`` carries that statement in full on every response — the same bytes the board PDF and the Excel workbook print — as the explanation that goes with the label. It is empty on BLS-primary roles, where ``confidence`` is set from the number of states reporting OEWS wage data rather than from a filing count. Optional projection: with ``age_to_year`` (and optionally ``aging_rate``) the figures are projected forward — the same code path as the site's 'Project to'. The response then carries ``filings_aged``, ``aged_to_year``, ``money_aging_factor``, ``money_aging_source`` and ``aged_from_year`` (the fiscal year of the Form 990 filings the projection runs from), so a projected response states that it is projected and from which fiscal year. Requires a CauseComp account with connector access. Sector labels are those list_sectors returns and metro codes those list_metros returns. The §4958 comparables set for the same inputs comes from get_comparables_set; it is drawn separately and does not produce this figure.

get_executive_benchmark

Find nonprofit organizations by name in the CauseComp comparables index (IRS Form 990 filers with officer compensation on record in the last five years) and get each one's EIN. The EINs it returns are accepted by get_comparables_set's `organizations` input. Every word of three or more letters in the name given appears in each match's name (case does not matter); `state` narrows a common name. Returns up to 20 matches -- name, EIN, city, state, NTEE sector, revenue band and latest filing year -- in alphabetical order, with no ranking. `truncated` is true when more than 20 matched; a longer name or a state narrows the list. An unrecognized state returns the valid codes; no match returns an empty list. Requires a CauseComp account with connector access. Each row also carries the organization's mission as it filed it on its Form 990 (mission) and mission_display: that text, or, where the filer wrote only a pointer such as "See Schedule O", the text it pointed to, with mission_display_source naming where it came from. An organization with no NTEE code on file is returned with ntee_sector null and sector_unclassified true; ask the user which sector it works in before requesting a benchmark.

find_organization

Return rows of Form 990 compensation filings selected by the filters supplied, 20 rows a page in a fixed order. This is a data lookup, not a comparables set: the response states which filters selected the rows. Rows returned count against a limit of 200 rows per account per day, reported in row_meter. The response carries a disclaimer for any answer built from these rows.

lookup_filing_data

List the valid **executive/leadership** role labels get_executive_benchmark (and get_comparables_set) accept. The optional ``search`` matches the role label and the officer titles filers report on Form 990, best match first: exact label, label, reported title. A benchmark call with an unrecognized role is rejected with suggestions; it is not mapped to a nearby label. These are officer/leadership roles from 990 filings; broad workforce roles are listed by list_workforce_roles. Returns ``{"roles": [...]}``, the labels to pass on. A search also returns ``role_details``: per role, what matched (matched_on, matched_term).

list_executive_roles

List the metro areas (MSAs) within a state, largest employment first — the valid ``msa`` values a benchmark call can pass for sub-state geography. Returns ``{"metros": [...]}`` (empty list if the state has none or the code is unrecognized).

list_metros

List the valid NTEE **sector** labels the ``ntee_sector`` benchmark input accepts (e.g. 'Human Services', 'Education', 'Health — Hospitals & Medical'). Returns ``{"sectors": [...]}``. For get_comparables_set, ``peer_sectors`` also accepts a list of these labels, or "all".

list_sectors

List the valid ``state`` codes a benchmark call accepts. A benchmark correction with ``kind: unrecognized_state`` carries the rejected value; the valid codes are this list. Such a correction does not map a misspelling such as 'Califoria' to 'CA', because a silent substitution is indistinguishable from a right answer. ``US`` is a member of the list, not a sentinel -- it means the national benchmark with no state adjustment, and asking for it is answered normally. Returns ``{"states": [...]}``.

list_states

List the valid **workforce** role labels get_workforce_benchmark accepts. The optional ``search`` matches the role label, the BLS SOC code and title, common job titles (for example 'peer support specialist' or 'DSP') and O*NET reported titles, best match first: exact label, label, SOC, job title, O*NET title. Chief Executives are excluded by design (officer fence); leadership roles are covered by get_executive_benchmark. Returns ``{"roles": [...]}``, the labels to pass on. A search also returns ``role_details``: per role, its soc_code and soc_title and what matched (matched_on, matched_term).

list_workforce_roles