# Get club dashboard

`GET /api/club/{clubNumber}`

Retrieve dashboard data for a single club by club number. data.historical_health_analysis is always present and returns a deterministic no_history DTO when no eligible completed DCP-history rows exist. Its configuration-2.0 class reflects recent Distinguished outcomes independently of its diagnostic composite score.

**Path parameters**

- `clubNumber` (string, required): Club number (e.g. 8-digit identifier)

**Query parameters**

- `fiscalYear` (string, optional): Fiscal year (YYYY-YYYY); defaults to the current fiscal year
- `startDate` (date, optional): First report date to include (YYYY-MM-DD)
- `endDate` (date, optional): Last report date to include (YYYY-MM-DD); on or after startDate
- `includeHistory` (enum, optional, default true): false leaves out the club's history of earlier snapshots One of: `true`, `false`.
- `latest` (enum, optional): true skips the cached response and sends Cache-Control: no-store One of: `true`, `false`.

**Returns**

- `success` (boolean)
- `club_number` (string)
- `fiscal_year` (string)
- `fiscal_month` (nullable integer): Fiscal month (1 = July) the figures are for: the requested month, else the month of the club's latest performance record. Early in a month this is still last month while Toastmasters processes it. Null when the club has no record for the fiscal year.
- `data` (object): Dashboard payload, including historical_health_analysis for completed DCP history.
  - `club_number` (string): Club number
  - `insights` (nullable object): Toastmasters rules evaluated for the club as of the report date (src/domain): good standing, the Club Success Plan deadline, Distinguished progress and ranked next actions. Null when the club has no performance record or no report date.
    - `as_of` (date): Report date the rules were evaluated for: the newest daily report or performance snapshot, capped at 30 June of a past fiscal year.
    - `good_standing` (nullable object): Null when there is neither a club status nor a dues report to go on.
      - `state` (enum) One of: `good`, `low`, `ineligible`, `suspended`.
      - `period` (enum): Renewal period the state is for. One of: `October`, `April`.
      - `paid_members` (integer)
      - `members_needed` (integer): Paid members still needed for the 8-member minimum.
      - `in_club_base` (boolean): Whether the club started the year in good standing.
      - `suspend_date` (nullable string): Present only for a suspended club.
      - `charter` (object): Present for a club chartered in the last 12 months with charter payments.
        - `date` (date)
        - `members` (integer)
    - `success_plan` (nullable object): The 90-day Club Success Plan deadline for a new club or one that started outside the club base.
      - `reason` (enum) One of: `new-club`, `outside-base`.
      - `deadline` (date)
      - `status` (enum) One of: `submitted`, `due`, `missed`.
    - `distinguished_progress` (object)
      - `achieved` (nullable string): Highest level whose goal and member requirements are met.
      - `achieved_standing` (nullable enum): How far the achieved level is. A club can only become Distinguished from April: before then it's "ready" once April renewals are paid, otherwise "potential". Null when no level is achieved. One of: `meets`, `ready`, `potential`, `null`.
      - `next` (nullable object)
        - `level` (string)
        - `goals_needed` (integer)
        - `members_needed` (object)
          - `needed` (integer)
          - `via` (enum) One of: `members`, `netGrowth`.
          - `target` (integer)
    - `next_actions` (nullable object): Null when the club has no DCP goal progress.
      - `month` (string)
      - `month_target` (integer): Goals a club should have met by this month.
      - `goals_met` (integer)
      - `goals_behind` (integer)
      - `next_level` (nullable object)
        - `level` (string)
        - `goals_needed` (integer)
        - `members_needed` (nullable integer)
      - `distinguished_out_of_reach` (boolean)
      - `actions` (array of objects): Every action, most urgent first; the dashboard shows the first three.
        - `code` (string): Stable identifier, e.g. good-standing, membership, dues, success-plan, reinstate or a DCP goal key such as 7_new_members.
        - `goal_number` (integer): DCP goal this action earns.
        - `label` (string): Tag for actions that are not numbered goals.
        - `title` (string)
        - `hint` (string)
        - `owner` (string)
  - `month_change` (object or nullable enum): The club's figures against the fiscal month before; null without a performance record.
    - `fiscal_year` (string)
    - `fiscal_month` (integer): Fiscal month (1 = July) of the figures.
    - `previous_fiscal_month` (nullable integer): The fiscal month compared with; null in July, which starts the fiscal year.
    - `current` (object): A club's figures for one fiscal month.
      - `active_members` (integer)
      - `goals_met` (integer)
      - `educational_awards` (integer)
      - `new_members` (integer)
      - `club_status` (nullable string)
      - `distinguished_status` (nullable enum) One of: `D`, `S`, `P`, `M`, `null`.
      - `division` (nullable string)
      - `area` (nullable string)
    - `previous` (object or nullable enum): Last month's figures; null in July or without a record last month.
      - `active_members` (integer)
      - `goals_met` (integer)
      - `educational_awards` (integer)
      - `new_members` (integer)
      - `club_status` (nullable string)
      - `distinguished_status` (nullable enum) One of: `D`, `S`, `P`, `M`, `null`.
      - `division` (nullable string)
      - `area` (nullable string)
    - `change` (nullable object): This month's figures minus last month's; null when previous is.
      - `active_members` (integer)
      - `goals_met` (integer)
      - `educational_awards` (integer)
      - `new_members` (integer)
    - `club_status_changed` (boolean)
    - `distinguished_status_changed` (boolean): The club reached, lost or changed its Distinguished level.
    - `moved` (boolean): The club moved to another division or area.
  - `historical_health_analysis` (object): Completed-programme-year analysis returned at data.historical_health_analysis, including a no_history DTO when no rows exist.
    - `schema_version` (enum) One of: `1.0`.
    - `config_version` (string): Version of the historical-health calculation configuration. Configuration 2.0 uses a 25-member default sustainability threshold and independent recent-award classification.
    - `status` (enum): `no_history` is the deterministic empty DTO. `insufficient_data` lacks the required scored-component coverage. One of: `available`, `limited_history`, `insufficient_data`, `no_history`.
    - `score` (nullable number): Explainable weighted five-year diagnostic score. It does not determine historical_class and can therefore be lower for a club classified A from recent Distinguished outcomes. Null for no history or insufficient component coverage.
    - `historical_class` (nullable enum): Recent Distinguished-performance class, independent of the weighted score. It is derived from the latest up-to-three completed programme years with recognized award semantics: A is regularly President's/Smedley Distinguished, B is frequently Distinguished or better, C is occasional Distinguished, and D is rare/never Distinguished. Null only when the classification window has insufficient recognized award evidence. One of: `A`, `B`, `C`, `D`.
    - `trajectory` (nullable enum): Membership-risk trajectory. Classification uses actual year-end memberships capped at the configured 25-member sustainability threshold, so changes wholly above that threshold are neutral; raw, uncapped trend metrics remain in trend. Null until at least two observed memberships exist. One of: `Growing`, `Stable`, `Declining`, `Recovering`, `Volatile`.
    - `profile` (nullable enum): Combined independently derived historical class and benchmark-adjusted trajectory; it does not depend on score. Null when either historical_class or trajectory is unavailable. One of: `Healthy & Growing`, `Healthy & Stable`, `Strong but Declining`, `Recovering`, `Volatile`, `Long-Term At Risk`.
    - `years_analyzed` (integer)
    - `period` (object)
      - `requested_max_years` (enum) One of: `5`.
      - `completed_through` (string): Most recent eligible completed fiscal year.
      - `earliest` (nullable string)
      - `latest` (nullable string)
      - `missing_years` (array of strings): Gaps between selected observed fiscal years; no data is inferred for them.
    - `trend` (object)
      - `membership_change_percent_per_year` (nullable number): Raw annualized year-end membership change percentage using actual, uncapped memberships. This metric is context only and is not the trajectory-classification rate.
      - `membership_volatility` (nullable number): Raw coefficient of variation of observed actual, uncapped year-end membership. The benchmark-adjusted volatility used for trajectory classification is exposed in explainability evidence.
      - `latest_year_end_membership` (nullable number): Latest actual, uncapped year-end membership.
    - `yearly` (array of objects)
      - `fiscal_year` (string)
      - `year_end_membership` (nullable number): Actual reported year-end membership; this value is never capped.
      - `membership_change` (nullable number): Actual year-end minus membership base; this raw value is never benchmark-adjusted.
      - `membership_change_percent` (nullable number): Actual raw membership change percentage; this value is never benchmark-adjusted.
      - `at_or_above_20` (nullable boolean, deprecated): Legacy compatibility flag for the former 20-member threshold. Use at_or_above_healthy_membership for the configured sustainability threshold.
      - `at_or_above_healthy_membership` (nullable boolean): Sustainability flag: whether actual year-end membership meets the configured healthy-membership threshold (25 by default in configuration 2.0).
      - `dcp_goals` (nullable number)
      - `distinguished_status` (nullable string)
      - `officer_training_round_1` (nullable number)
      - `officer_training_round_2` (nullable number)
      - `score` (nullable number): Per-year score when at least three scored components including membership sustainability are available.
    - `explainability` (object)
      - `components` (array of objects): Stable component-key detail supporting the diagnostic score. Recent-award classification and benchmark-adjusted trajectory evidence are top-level explainability fields.
        - `key` (enum) One of: `membership_sustainability`, `growth`, `dcp_goals`, `distinguished_status`, `officer_training`.
        - `configured_weight` (number): Configured percentage weight.
        - `effective_weight` (number): Percentage weight after redistribution across observed components.
        - `score` (nullable number): Component score from 0 through 100; null when no usable observations exist.
        - `contribution` (number): Weighted contribution to the historical score, or zero when missing.
        - `observations` (integer)
        - `status` (enum) One of: `scored`, `missing`.
        - `formula` (string)
        - `evidence` (object): Component-specific primitive evidence used by the diagnostic-score calculation, such as the configured sustainability threshold and safe membership declines neutralized for growth scoring. Each value is a number, string, boolean, or null. Recent-award classification and benchmark-adjusted trajectory evidence are separate top-level explainability fields.
      - `recent_award_classification` (object): Top-level evidence for the independent historical_class calculation from recent recognized awards.
        - `classification_window_fiscal_years` (array of strings): Fiscal years in the most recent up-to-three completed-programme-year classification window, ordered oldest to newest.
        - `window_size` (integer): Number of completed programme years in the classification window.
        - `required_frequency` (integer): Recognized award values required to classify the window: ceil(window_size * 2 / 3).
        - `known_years` (integer): Years in the classification window with recognized award semantics, including explicit no-award values.
        - `high_distinguished_years` (integer): Recognized President's Distinguished or Smedley Distinguished years in the classification window.
        - `distinguished_years` (integer): Recognized Distinguished-or-better years in the classification window.
        - `selected_class_rule` (nullable string): Rule that selected the A-D historical class; null when recognized award evidence is insufficient.
      - `benchmark_adjusted_trajectory` (object): Top-level evidence for membership-risk trajectory classification using the benchmark-adjusted membership series.
        - `healthy_membership_threshold` (number): Configured healthy-membership threshold used to cap memberships for trajectory classification.
        - `benchmark_adjusted_membership_series` (array of objects): Observed completed-year memberships after capping each value at healthy_membership_threshold, ordered oldest to newest.
          - `fiscal_year` (string): Completed programme year for this trajectory observation.
          - `membership` (number): Year-end membership capped at healthy_membership_threshold for trajectory classification.
        - `benchmark_adjusted_change_percent_per_year` (nullable number): Average gap-aware annualized change percentage calculated from the benchmark-adjusted membership series; null when no valid transition exists.
        - `benchmark_adjusted_membership_volatility` (nullable number): Coefficient of variation of the benchmark-adjusted membership series; null when it cannot be calculated.
        - `above_threshold_movements_neutralized` (integer): Count of adjacent observed movements whose actual endpoints both met the healthy-membership threshold and therefore become neutral after capping.
      - `reasons` (array of strings): Human-readable calculation disclosures, including why score and historical class may differ, benchmark-adjusted trajectory inputs, and safe declines neutralized at or above the sustainability threshold.
    - `data_quality` (object)
      - `confidence` (enum) One of: `high`, `medium`, `low`, `none`.
      - `excluded_years` (array of objects)
        - `fiscal_year` (string)
        - `reason` (string)
      - `missing_metrics` (array of strings)
      - `warnings` (array of strings)
  - `club_outlook` (object): Which of five groups the club is in: doing_well, improving, steady, declining or definite_worry. From October the current paid count decides first: under 8 paid members is definite_worry, and keeping under 60% of last June's members is declining. Otherwise the 0-100 health score for the last completed programme year decides: 70+ is doing_well; a score up 10+ on the two years before, or more paid members than last June, is improving; anything else is steady. Before October, a score under 40 is definite_worry. Back-tested on October 2024 and 2025: closed or under 8 members by the next June was 1% for doing_well, 8% improving, 8% steady, 6% declining (median -6 members) and 55% definite_worry.
    - `version` (enum) One of: `1`.
    - `category` (nullable enum): Null when the club has no completed year and isn't under 8 paid members after October. One of: `doing_well`, `improving`, `steady`, `declining`, `definite_worry`, `null`.
    - `label` (nullable string)
    - `basis` (enum): renewals once October renewals are in; history before that. One of: `renewals`, `history`.
    - `health_score` (nullable number): 100 minus points for the last completed programme year.
    - `health_score_change` (nullable number): Health score minus the average of the two programme years before it.
    - `scored_year` (nullable string)
    - `paid_members` (nullable number)
    - `last_year_end_members` (nullable number)
    - `retention` (nullable number): Paid members now as a share of last year end's, from October.
    - `reasons` (array of strings): Why the club is in its group, most important first.
    - `points` (array of objects): Points taken off 100 for the scored year, largest first.
      - `key` (enum) One of: `members`, `dcp_goals`, `new_members`, `officer_training`, `renewals`, `members_lost`, `distinguished`.
      - `points` (number)
      - `reason` (string)
  - `systems` (array of objects): Third-party systems the club is enrolled on now (first: Podium), read once a day from each system's own list of clubs. Empty when the club is on none.
    - `system` (string): The system's key
    - `name` (string): The system's name
    - `url` (string): The club's own page on the system
    - `enrolled_since` (nullable string): YYYY-MM-DD the club was first seen on the system's list
  - `division_context` (nullable object): Division-scoped context for this club
    - `division` (string)
    - `division_name` (string)
    - `area` (string)
    - `club_name` (string)
    - `october_renewals` (integer)
    - `april_renewals` (integer)
    - `active_members` (integer)
    - `educational_ratio` (number): Educational awards ratio for the club (awards/base membership)
    - `average_goals_met` (number): Average goals met metric used in division context
    - `goals_met` (integer)
    - `distinguished_status` (string)
    - `area_visits` (object)
      - `nov_visit_award` (nullable string)
      - `may_visit_award` (nullable string)
    - `last_updated` (nullable string)
  - `area_context` (nullable object): Area-scoped context for this club
    - `area` (string)
    - `area_name` (string)
    - `division` (string)
    - `district` (string)
    - `club_name` (string)
    - `october_renewals` (integer)
    - `april_renewals` (integer)
    - `active_members` (integer)
    - `educational_ratio` (number): Educational awards ratio for the club (awards/base membership)
    - `average_goals_met` (number): Average goals met metric used in area context
    - `goals_met` (integer)
    - `distinguished_status` (string)
    - `area_visits` (object)
      - `nov_visit_award` (nullable string)
      - `may_visit_award` (nullable string)
    - `last_updated` (nullable string)
- `timestamp` (timestamp)

**Errors**

- `422`: A path or query parameter has an invalid value
- `500`: Internal server error

**Example request**

```bash
curl "https://tm-api.devinpearson.me/api/club/113"
```

**Example response**

```json
{
  "success": true,
  "club_number": "113",
  "fiscal_year": "2026-2027",
  "fiscal_month": 5,
  "data": {
    "club_number": "113",
    "insights": {
      "as_of": "2026-11-19",
      "good_standing": {
        "state": "good",
        "period": "October",
        "paid_members": 0,
        "members_needed": 0,
        "in_club_base": true,
        "suspend_date": "string",
        "charter": {
          "date": "2026-11-19",
          "members": 0
        }
      },
      "success_plan": {
        "reason": "new-club",
        "deadline": "2026-11-19",
        "status": "submitted"
      },
      "distinguished_progress": {
        "achieved": "string",
        "achieved_standing": "meets",
        "next": {
          "level": "string",
          "goals_needed": 0,
          "members_needed": {
            "needed": 0,
            "via": "members",
            "target": 0
          }
        }
      },
      "next_actions": {
        "month": "string",
        "month_target": 0,
        "goals_met": 0,
        "goals_behind": 0,
        "next_level": {
          "level": "string",
          "goals_needed": 0,
          "members_needed": 0
        },
        "distinguished_out_of_reach": true,
        "actions": [
          {
            "code": "string",
            "goal_number": 0,
            "label": "string",
            "title": "string",
            "hint": "string",
            "owner": "string"
          }
        ]
      }
    },
    "month_change": {
      "fiscal_year": "2026-2027",
      "fiscal_month": 5,
      "previous_fiscal_month": 1,
      "current": {
        "active_members": 0,
        "goals_met": 0,
        "educational_awards": 0,
        "new_members": 0,
        "club_status": "string",
        "distinguished_status": "D",
        "division": "A",
        "area": "01"
      },
      "previous": {
        "active_members": 0,
        "goals_met": 0,
        "educational_awards": 0,
        "new_members": 0,
        "club_status": "string",
        "distinguished_status": "D",
        "division": "A",
        "area": "01"
      },
      "change": {
        "active_members": 0,
        "goals_met": 0,
        "educational_awards": 0,
        "new_members": 0
      },
      "club_status_changed": true,
      "distinguished_status_changed": true,
      "moved": true
    },
    "historical_health_analysis": {
      "schema_version": "1.0",
      "config_version": "string",
      "status": "available",
      "score": 0,
      "historical_class": "A",
      "trajectory": "Growing",
      "profile": "Healthy & Growing",
      "years_analyzed": 0,
      "period": {
        "requested_max_years": 5,
        "completed_through": "string",
        "earliest": "string",
        "latest": "string",
        "missing_years": [
          "string"
        ]
      },
      "trend": {
        "membership_change_percent_per_year": 0,
        "membership_volatility": 0,
        "latest_year_end_membership": 0
      },
      "yearly": [
        {
          "fiscal_year": "2026-2027",
          "year_end_membership": 0,
          "membership_change": 0,
          "membership_change_percent": 0,
          "at_or_above_20": true,
          "at_or_above_healthy_membership": true,
          "dcp_goals": 0,
          "distinguished_status": "string",
          "officer_training_round_1": 0,
          "officer_training_round_2": 0,
          "score": 0
        }
      ],
      "explainability": {
        "components": [
          {
            "key": "membership_sustainability",
            "configured_weight": 0,
            "effective_weight": 0,
            "score": 0,
            "contribution": 0,
            "observations": 0,
            "status": "scored",
            "formula": "string",
            "evidence": {}
          }
        ],
        "recent_award_classification": {
          "classification_window_fiscal_years": [
            "string"
          ],
          "window_size": 0,
          "required_frequency": 0,
          "known_years": 0,
          "high_distinguished_years": 0,
          "distinguished_years": 0,
          "selected_class_rule": "string"
        },
        "benchmark_adjusted_trajectory": {
          "healthy_membership_threshold": 0,
          "benchmark_adjusted_membership_series": [
            {}
          ],
          "benchmark_adjusted_change_percent_per_year": 0,
          "benchmark_adjusted_membership_volatility": 0,
          "above_threshold_movements_neutralized": 0
        },
        "reasons": [
          "string"
        ]
      },
      "data_quality": {
        "confidence": "high",
        "excluded_years": [
          {
            "fiscal_year": "2026-2027",
            "reason": "string"
          }
        ],
        "missing_metrics": [
          "string"
        ],
        "warnings": [
          "string"
        ]
      }
    },
    "club_outlook": {
      "version": "1",
      "category": "doing_well",
      "label": "Definite worry",
      "basis": "renewals",
      "health_score": 0,
      "health_score_change": 0,
      "scored_year": "2025-2026",
      "paid_members": 0,
      "last_year_end_members": 0,
      "retention": 0,
      "reasons": [
        "string"
      ],
      "points": [
        {
          "key": "members",
          "points": 0,
          "reason": "string"
        }
      ]
    },
    "systems": [
      {
        "system": "podium",
        "name": "Podium",
        "url": "https://form-ui.podium-app.cloud/club/Lisbon-Toastmasters-Club",
        "enrolled_since": "2026-11-17"
      }
    ],
    "division_context": {
      "division": "A",
      "division_name": "string",
      "area": "01",
      "club_name": "Example Toastmasters Club",
      "october_renewals": 0,
      "april_renewals": 0,
      "active_members": 0,
      "educational_ratio": 0,
      "average_goals_met": 0,
      "goals_met": 0,
      "distinguished_status": "string",
      "area_visits": {
        "nov_visit_award": "string",
        "may_visit_award": "string"
      },
      "last_updated": "string"
    },
    "area_context": {
      "area": "01",
      "area_name": "string",
      "division": "A",
      "district": "74",
      "club_name": "Example Toastmasters Club",
      "october_renewals": 0,
      "april_renewals": 0,
      "active_members": 0,
      "educational_ratio": 0,
      "average_goals_met": 0,
      "goals_met": 0,
      "distinguished_status": "string",
      "area_visits": {
        "nov_visit_award": "string",
        "may_visit_award": "string"
      },
      "last_updated": "string"
    }
  },
  "timestamp": "2026-11-19T04:30:00.000Z"
}
```
