API reference

The API behind Devins Dashboards. It serves the same Toastmasters club, area, division, district and region figures the site shows, as JSON.

On this page

Introduction

View as Markdown

The API is organised around the Toastmasters hierarchy: regions contain districts, districts contain divisions, divisions contain areas, and areas contain clubs. Requests are plain HTTPS, and every response is JSON.

No API key or sign-in is needed. Requests from a browser on another site are allowed.

The figures come from the reports Toastmasters International publishes on its public dashboards, collected once a day. This is an independent, unofficial service: where a figure disagrees with Toastmasters International, theirs is the official one.

The whole API is also described by an OpenAPI document, and you can try requests in the Swagger UI.

Base URL
https://tm-api.devinpearson.me
Your first request
curl "https://tm-api.devinpearson.me/api/club/search?q=toast"

Conventions

View as Markdown
  • Fiscal years run from 1 July to 30 June and are written YYYY-YYYY, for example 2026-2027.
  • Fiscal months count from July: 1 is July and 12 is June.
  • Dates are YYYY-MM-DD. A report date is the date Toastmasters gives a report, which can be a day or two behind today.
  • Club numbers are returned without leading zeros. 00000113 and 113 are the same club, and either works in a request.
  • Districts are numbers, except F for Founders District and U for clubs that belong to no district.
The same club, two ways
curl "https://tm-api.devinpearson.me/api/club/113?fiscalYear=2025-2026"
curl "https://tm-api.devinpearson.me/api/club/00000113?fiscalYear=2025-2026"

Errors

View as Markdown

The HTTP status tells you what happened: 2xx for success, 422 for a request with a value the API can't accept, 404 when there is nothing at that address or no data for it, and 5xx when the API itself failed. 400 is only for a request the API couldn't read at all, such as a body that isn't valid JSON.

Errors follow RFC 9457, Problem Details for HTTP APIs, and are sent as application/problem+json.

  • status is the HTTP status and title its standard phrase. type is always about:blank.
  • detail says what went wrong with this request, and instance is the path and query that was requested.
  • error is a short name for the problem. message is the same text as detail, and success is always false.
  • When a parameter is rejected, details lists each problem with where it was found (query, params or body) and the name of the parameter.

The health endpoints are the exception: they report a status word such as unhealthy, in plain JSON.

A rejected request
{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Invalid request parameters",
  "instance": "/api/club/search?q=a",
  "success": false,
  "error": "Validation failed",
  "message": "Invalid request parameters",
  "details": [
    {
      "location": "query",
      "path": "q",
      "message": "must be at least 2 characters",
      "code": "too_small"
    }
  ],
  "timestamp": "2026-11-20T06:55:30.344Z"
}

Caching

View as Markdown

The data changes once a day, so responses are cached for a few minutes and can be cached by anything between you and the API. That is nearly always what you want.

Add latest=true to a request to skip the cached copy. The response is then sent with Cache-Control: no-store.

Skip the cache
curl "https://tm-api.devinpearson.me/api/district/74?latest=true"

Club

A Toastmasters club, identified by its club number. Club numbers are returned without leading zeros, and a request may send them either way.

A club belongs to an area, which belongs to a division, which belongs to a district. The club dashboard reports the club's membership, its progress on the 10 Distinguished Club Program goals, dues renewals, officer training and recognition status as of a report date, with insights such as good standing and the next actions for its officers. The changelog lists what changed in the club's figures from one report to the next.

View as Markdown

List club numbers

GET/api/club/numbers

View as Markdown

Every club with a performance row in the current fiscal year, as canonical club numbers (no leading zeros), sorted. For building the dashboard's sitemap.

Returns

  • successboolean
  • fiscal_yearstring
  • dataarray of strings
  • totalinteger
  • timestamptimestamp

Errors

  • 422A path or query parameter has an invalid value
  • 500Internal server error
GET /api/club/numbers
curl "https://tm-api.devinpearson.me/api/club/numbers"
Response
{
  "success": true,
  "fiscal_year": "2026-2027",
  "data": [
    "113",
    "1150",
    "28675613"
  ],
  "total": 0,
  "timestamp": "2026-11-19T04:30:00.000Z"
}

Get club changelog events

GET/api/club/{clubNumber}/changelog

View as Markdown

Retrieve normalized, paginated metric changes for a club. Events are ordered by comparison date and metric.

Path parameters

  • clubNumberstringRequired

    Club number (e.g. 8-digit identifier)

Query parameters

  • fiscalYearstringoptional

    Toastmasters fiscal year (July-June). Defaults to the current fiscal year.

  • fiscalMonthintegeroptional
  • datedateoptional
  • startDatedateoptional
  • endDatedateoptional
  • categoryenumoptional

    Possible valueslifecyclemembershipeducationstatusrenewals

  • metricstringoptional
  • limitintegeroptional

    Maximum number of records to return

    Default1000

  • offsetintegeroptional

    Number of records to skip

    Default0

  • sortOrderenumoptional

    Possible valuesascdesc

    Defaultdesc

  • viewenumoptional

    day: also return days, this page's events grouped by day with report glitches removed (a year-to-date count falling, or members falling outside the October/April removals) and memberRemoval on removal days.

    Possible valuesday

Returns

  • successboolean
  • club_numberstring
  • dataarray of objects
    17 child attributes
  • daysarray of objects

    view=day only: the page's events without report glitches, grouped by day.

    3 child attributes
  • paginationobject

    Pagination returned by member-payments endpoints. total is the total matching records.

    4 child attributes
  • filtersobject
  • timestamptimestamp

Errors

  • 422Invalid changelog query
  • 500Internal server error
GET /api/club/{clubNumber}/changelog
curl "https://tm-api.devinpearson.me/api/club/113/changelog"
Response
{
  "success": true,
  "club_number": "113",
  "data": [
    {
      "club_number": "113",
      "club_name": "Example Toastmasters Club",
      "district": "74",
      "division": "A",
      "area": "01",
      "comparison_date": "2026-11-19",
      "previous_date": "2026-11-19",
      "fiscal_year": "2026-2027",
      "fiscal_month": 5,
      "category": "lifecycle",
      "metric": "string",
      "change_type": "increased",
      "old_value": "string",
      "new_value": "string",
      "old_value_numeric": 0,
      "new_value_numeric": 0,
      "delta_numeric": 0
    }
  ],
  "days": [
    {
      "date": "2026-11-19",
      "events": [
        {
          "club_number": "113",
          "club_name": "Example Toastmasters Club",
          "district": "74",
          "division": "A",
          "area": "01",
          "comparison_date": "2026-11-19",
          "previous_date": "2026-11-19",
          "fiscal_year": "2026-2027",
          "fiscal_month": 5,
          "category": "lifecycle",
          "metric": "string",
          "change_type": "increased",
          "old_value": "string",
          "new_value": "string",
          "old_value_numeric": 0,
          "new_value_numeric": 0,
          "delta_numeric": 0
        }
      ],
      "memberRemoval": {
        "period": "October",
        "removed": 0,
        "from": 0,
        "to": 0
      }
    }
  ],
  "pagination": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "has_more": true
  },
  "filters": {},
  "timestamp": "2026-11-19T04:30:00.000Z"
}

Get club dashboard

GET/api/club/{clubNumber}

View as Markdown

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

  • clubNumberstringRequired

    Club number (e.g. 8-digit identifier)

Query parameters

  • fiscalYearstringoptional

    Fiscal year (YYYY-YYYY); defaults to the current fiscal year

  • startDatedateoptional

    First report date to include (YYYY-MM-DD)

  • endDatedateoptional

    Last report date to include (YYYY-MM-DD); on or after startDate

  • includeHistoryenumoptional

    false leaves out the club's history of earlier snapshots

    Possible valuestruefalse

    Defaulttrue

  • latestenumoptional

    true skips the cached response and sends Cache-Control: no-store

    Possible valuestruefalse

Returns

  • successboolean
  • club_numberstring
  • fiscal_yearstring
  • fiscal_monthnullable 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.

  • dataobject

    Dashboard payload, including historical_health_analysis for completed DCP history.

    8 child attributes
  • timestamptimestamp

Errors

  • 422A path or query parameter has an invalid value
  • 500Internal server error
GET /api/club/{clubNumber}
curl "https://tm-api.devinpearson.me/api/club/113"
Response
{
  "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"
}

Area

An area is a small group of clubs within a division, led by an Area Director. It is identified by its district, its division's letter and its own number, for example district 74, division A, area 01.

The area dashboard reports the area's totals, its clubs, its progress towards Distinguished Area recognition and the Area Director's club visits. The changelog groups what changed across the area's clubs.

View as Markdown

Get aggregated area changelog

GET/api/district/{district}/area/{division}/{area}/changelog

View as Markdown

Groups normalized club changelog events by metric across the selected period. Each metric contains its total numeric delta and affected clubs with names, club totals, and dated source changes. Lifecycle groups are included and use null numeric totals.

Path parameters

  • districtstringRequired
  • divisionstringRequired
  • areastringRequired

Query parameters

  • fiscalYearstringoptional

    Toastmasters fiscal year. Defaults to the current fiscal year.

  • fiscalMonthintegeroptional
  • datedateoptional
  • startDatedateoptional
  • endDatedateoptional
  • categoryenumoptional

    Possible valueslifecyclemembershipeducationstatusrenewals

  • metricstringoptional
  • limitintegeroptional

    Maximum number of records to return

    Default1000

  • offsetintegeroptional

    Number of records to skip

    Default0

  • sortOrderenumoptional

    Possible valuesascdesc

    Defaultdesc

  • viewenumoptional

    day: the daily timeline. Each group is one metric on one day, payment totals that a more specific change explains are left out, each group has member_removal (the October/April removal of unpaid members, or null), and pages count day groups.

    Possible valuesday

Returns

  • successboolean
  • areaobject
    3 child attributes
  • dataarray of objects
    9 child attributes
  • paginationobject

    Pagination returned by member-payments endpoints. total is the total matching records.

    4 child attributes
  • filtersobject
  • timestamptimestamp

Errors

  • 422Invalid area changelog query
  • 500Internal server error
GET /api/district/{district}/area/{division}/{area}/changelog
curl "https://tm-api.devinpearson.me/api/district/74/area/A/01/changelog"
Response
{
  "success": true,
  "area": {
    "district": "74",
    "division": "A",
    "area": "01"
  },
  "data": [
    {
      "category": "lifecycle",
      "metric": "string",
      "event_count": 1,
      "clubs_affected": 1,
      "total_delta": 0,
      "first_comparison_date": "2026-11-19",
      "last_comparison_date": "2026-11-19",
      "clubs": [
        {
          "club_number": "113",
          "club_name": "Example Toastmasters Club",
          "division": "A",
          "area": "01",
          "event_count": 1,
          "total_delta": 0,
          "first_comparison_date": "2026-11-19",
          "last_comparison_date": "2026-11-19",
          "changes": [
            {}
          ]
        }
      ],
      "member_removal": {
        "period": "October",
        "removed": 0,
        "clubs": 0
      }
    }
  ],
  "pagination": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "has_more": true
  },
  "filters": {},
  "timestamp": "2026-11-19T04:30:00.000Z"
}

Get area data

GET/api/district/{district}/area/{division}/{area}

View as Markdown

Retrieve area-level data. Club ratios use authoritative award totals divided by mem_base. Area goal and educational benchmarks are unweighted arithmetic club means; undefined ratios and empty averages are null.

Path parameters

  • districtstringRequired
  • divisionstringRequired
  • areastringRequired

Query parameters

  • fiscalYearstringoptional

    Fiscal year (YYYY-YYYY); defaults to the current fiscal year

  • datedateoptional

    Specific date to filter by (YYYY-MM-DD)

  • startDatedateoptional

    First report date to include (YYYY-MM-DD)

  • endDatedateoptional

    Last report date to include (YYYY-MM-DD); on or after startDate

  • latestenumoptional

    true skips the cached response and sends Cache-Control: no-store

    Possible valuestruefalse

  • limitintegeroptional

    Maximum number of records to return

    Default1000

  • offsetintegeroptional

    Number of records to skip

    Default0

Returns

  • successboolean
  • dataobject
    5 child attributes

Errors

  • 422A path or query parameter has an invalid value
  • 500Internal server error
GET /api/district/{district}/area/{division}/{area}
curl "https://tm-api.devinpearson.me/api/district/74/area/A/01"
Response
{
  "success": true,
  "data": {
    "area": {
      "area_average_goals_met": 0,
      "area_educational_ratio": 0
    },
    "division_metrics": {
      "area_average_goals_met": 0,
      "area_educational_ratio": 0
    },
    "clubs": [
      {
        "club_number": "113",
        "club_name": "Example Toastmasters Club",
        "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": [
            {}
          ]
        },
        "educational_awards": 0,
        "educational_ratio": 0,
        "average_goals_met": 0,
        "nov_visit_award": 0,
        "may_visit_award": 0,
        "area_average_goals_met": 0,
        "area_average_educational_ratio": 0,
        "goals_vs_area_average": "above",
        "educational_ratio_vs_area_average": "above",
        "july_officer_list": [
          {
            "list_status": "string",
            "election_type": "string",
            "date": "2026-11-19"
          }
        ],
        "july_officer_list_status": true
      }
    ],
    "insights": {
      "as_of": "2026-11-19",
      "month": "string",
      "month_target": 0,
      "distinguished_status": "D",
      "next_actions": [
        {
          "code": "string",
          "key": "string",
          "title": "string",
          "hint": "string",
          "when": "string"
        }
      ],
      "on_track_clubs": 0,
      "visits": {
        "nov": {
          "clubs_visited": 0,
          "clubs_required": 0,
          "visited_pct": 0,
          "status": {
            "state": "met",
            "dueLabel": "string"
          },
          "window_open": true
        },
        "may": {
          "clubs_visited": 0,
          "clubs_required": 0,
          "visited_pct": 0,
          "status": {
            "state": "met",
            "dueLabel": "string"
          },
          "window_open": true
        }
      },
      "officer_training": {
        "round_1": {
          "clubs_counted": 0,
          "officers_trained": 0,
          "officers_possible": 0,
          "trained_pct": 0,
          "window_open": true
        },
        "round_2": {
          "clubs_counted": 0,
          "officers_trained": 0,
          "officers_possible": 0,
          "trained_pct": 0,
          "window_open": true
        }
      },
      "clubs": [
        {
          "club_number": "113",
          "club_name": "Example Toastmasters Club",
          "progress": {},
          "milestone": {
            "achieved": "string",
            "next": "string"
          },
          "below_month_target": true,
          "needs": {
            "officers_round_1": true,
            "officers_round_2": true,
            "nov_visit": true,
            "may_visit": true,
            "club_success_plan": true,
            "club_coach": true
          },
          "officers_round_2_due": {
            "state": "met",
            "dueLabel": "string"
          },
          "nov_visit_due": {
            "state": "met",
            "dueLabel": "string"
          },
          "may_visit_due": {
            "state": "met",
            "dueLabel": "string"
          }
        }
      ]
    },
    "month_change": {
      "fiscal_year": "2026-2027",
      "fiscal_month": 5,
      "previous_fiscal_month": 1,
      "current": {
        "clubs": 0,
        "suspended_clubs": 0,
        "paid_clubs": 0,
        "distinguished_clubs": 0,
        "active_members": 0,
        "goals_met": 0,
        "educational_awards": 0,
        "new_members": 0
      },
      "previous": {
        "clubs": 0,
        "suspended_clubs": 0,
        "paid_clubs": 0,
        "distinguished_clubs": 0,
        "active_members": 0,
        "goals_met": 0,
        "educational_awards": 0,
        "new_members": 0
      },
      "change": {
        "clubs": 0,
        "suspended_clubs": 0,
        "paid_clubs": 0,
        "distinguished_clubs": 0,
        "active_members": 0,
        "goals_met": 0,
        "educational_awards": 0,
        "new_members": 0
      },
      "clubs_added": [
        "string"
      ],
      "clubs_removed": [
        "string"
      ],
      "parts": [
        {
          "key": "string",
          "current": {
            "clubs": 0,
            "suspended_clubs": 0,
            "paid_clubs": 0,
            "distinguished_clubs": 0,
            "active_members": 0,
            "goals_met": 0,
            "educational_awards": 0,
            "new_members": 0
          },
          "previous": {
            "clubs": 0,
            "suspended_clubs": 0,
            "paid_clubs": 0,
            "distinguished_clubs": 0,
            "active_members": 0,
            "goals_met": 0,
            "educational_awards": 0,
            "new_members": 0
          },
          "change": {
            "clubs": 0,
            "suspended_clubs": 0,
            "paid_clubs": 0,
            "distinguished_clubs": 0,
            "active_members": 0,
            "goals_met": 0,
            "educational_awards": 0,
            "new_members": 0
          },
          "clubs_added": [
            "string"
          ],
          "clubs_removed": [
            "string"
          ]
        }
      ]
    }
  }
}

Division

A division is a group of areas within a district, led by a Division Director. It is identified by its district and a letter, for example district 74, division A.

The division dashboard reports the division's totals, its areas and their clubs, and its progress towards Distinguished Division recognition. The changelog groups what changed across every area in the division.

View as Markdown

Get division data

GET/api/district/{district}/division/{division}

View as Markdown

Retrieve division-level data. Area average_goals_met is the arithmetic club mean; area and division educational_ratio values are total awards divided by total mem_base. Division average_goals_met is club-weighted. Undefined ratios and empty averages are null.

Path parameters

  • districtstringRequired

    District number/code

  • divisionstringRequired

    Division identifier

Query parameters

  • fiscalYearstringoptional

    Fiscal year (YYYY-YYYY); defaults to the current fiscal year

  • includestringoptional

    Comma-separated extra blocks to include

  • latestenumoptional

    true skips the cached response and sends Cache-Control: no-store

    Possible valuestruefalse

Returns

  • successboolean
  • metadataobject

    Payment targets are optional enrichment. partial_data is true when they are unavailable.

    3 child attributes
  • dataobject
    9 child attributes

Errors

  • 422A path or query parameter has an invalid value
  • 500Internal server error
GET /api/district/{district}/division/{division}
curl "https://tm-api.devinpearson.me/api/district/74/division/A"
Response
{
  "success": true,
  "metadata": {
    "partial_data": true,
    "partial_data_reasons": [
      "string"
    ],
    "payment_targets": {
      "available": true,
      "reason": "string"
    }
  },
  "data": {
    "insights": {
      "as_of": "2026-11-19",
      "month": "string",
      "month_target": 0,
      "show_potential_metrics": true,
      "distinguished_status": "D",
      "on_track_clubs": 0,
      "visits": {
        "areaCount": 0,
        "julyOct": {
          "clubsVisited": 0,
          "clubsRequired": 0,
          "areasMet": 0
        },
        "janMay": {
          "clubsVisited": 0,
          "clubsRequired": 0,
          "areasMet": 0
        }
      },
      "officer_training": {
        "round_1": {
          "clubs_counted": 0,
          "officers_trained": 0,
          "officers_possible": 0,
          "trained_pct": 0,
          "window_open": true
        },
        "round_2": {
          "clubs_counted": 0,
          "officers_trained": 0,
          "officers_possible": 0,
          "trained_pct": 0,
          "window_open": true
        }
      },
      "areas": [
        {
          "area": "01",
          "distinguished_status": "D",
          "officers_round_1_pct": 0,
          "officers_round_2_pct": 0
        }
      ]
    },
    "month_change": {
      "fiscal_year": "2026-2027",
      "fiscal_month": 5,
      "previous_fiscal_month": 1,
      "current": {
        "clubs": 0,
        "suspended_clubs": 0,
        "paid_clubs": 0,
        "distinguished_clubs": 0,
        "active_members": 0,
        "goals_met": 0,
        "educational_awards": 0,
        "new_members": 0
      },
      "previous": {
        "clubs": 0,
        "suspended_clubs": 0,
        "paid_clubs": 0,
        "distinguished_clubs": 0,
        "active_members": 0,
        "goals_met": 0,
        "educational_awards": 0,
        "new_members": 0
      },
      "change": {
        "clubs": 0,
        "suspended_clubs": 0,
        "paid_clubs": 0,
        "distinguished_clubs": 0,
        "active_members": 0,
        "goals_met": 0,
        "educational_awards": 0,
        "new_members": 0
      },
      "clubs_added": [
        "string"
      ],
      "clubs_removed": [
        "string"
      ],
      "parts": [
        {
          "key": "string",
          "current": {
            "clubs": 0,
            "suspended_clubs": 0,
            "paid_clubs": 0,
            "distinguished_clubs": 0,
            "active_members": 0,
            "goals_met": 0,
            "educational_awards": 0,
            "new_members": 0
          },
          "previous": {
            "clubs": 0,
            "suspended_clubs": 0,
            "paid_clubs": 0,
            "distinguished_clubs": 0,
            "active_members": 0,
            "goals_met": 0,
            "educational_awards": 0,
            "new_members": 0
          },
          "change": {
            "clubs": 0,
            "suspended_clubs": 0,
            "paid_clubs": 0,
            "distinguished_clubs": 0,
            "active_members": 0,
            "goals_met": 0,
            "educational_awards": 0,
            "new_members": 0
          },
          "clubs_added": [
            "string"
          ],
          "clubs_removed": [
            "string"
          ]
        }
      ]
    },
    "district": "74",
    "division": "A",
    "average_goals_met": 0,
    "educational_ratio": 0,
    "division_context": {},
    "district_context": {},
    "areas": [
      {
        "average_goals_met": 0,
        "educational_ratio": 0,
        "clubs": [
          {
            "club_number": "113",
            "club_name": "Example Toastmasters Club",
            "club_outlook": {},
            "educational_awards": 0,
            "educational_ratio": 0,
            "average_goals_met": 0,
            "nov_visit_award": 0,
            "may_visit_award": 0,
            "area_average_goals_met": 0,
            "area_average_educational_ratio": 0,
            "goals_vs_area_average": "above",
            "educational_ratio_vs_area_average": "above",
            "july_officer_list": [],
            "july_officer_list_status": true
          }
        ]
      }
    ]
  }
}

Get aggregated division changelog

GET/api/district/{district}/division/{division}/changelog

View as Markdown

Groups normalized club changelog events by metric across every area in the selected division and period. Each metric contains its total numeric delta and affected clubs with names, club totals, and dated source changes. Lifecycle groups are included and use null numeric totals.

Path parameters

  • districtstringRequired
  • divisionstringRequired

Query parameters

  • fiscalYearstringoptional

    Toastmasters fiscal year. Defaults to the current fiscal year.

  • fiscalMonthintegeroptional
  • datedateoptional
  • startDatedateoptional
  • endDatedateoptional
  • categoryenumoptional

    Possible valueslifecyclemembershipeducationstatusrenewals

  • metricstringoptional
  • limitintegeroptional

    Maximum number of records to return

    Default1000

  • offsetintegeroptional

    Number of records to skip

    Default0

  • sortOrderenumoptional

    Possible valuesascdesc

    Defaultdesc

  • viewenumoptional

    day: the daily timeline. Each group is one metric on one day, payment totals that a more specific change explains are left out, each group has member_removal (the October/April removal of unpaid members, or null), and pages count day groups.

    Possible valuesday

Returns

  • successboolean
  • divisionobject
    2 child attributes
  • dataarray of objects
    9 child attributes
  • paginationobject

    Pagination returned by member-payments endpoints. total is the total matching records.

    4 child attributes
  • filtersobject
  • timestamptimestamp

Errors

  • 422Invalid division changelog query
  • 500Internal server error
GET /api/district/{district}/division/{division}/changelog
curl "https://tm-api.devinpearson.me/api/district/74/division/A/changelog"
Response
{
  "success": true,
  "division": {
    "district": "74",
    "division": "A"
  },
  "data": [
    {
      "category": "lifecycle",
      "metric": "string",
      "event_count": 1,
      "clubs_affected": 1,
      "total_delta": 0,
      "first_comparison_date": "2026-11-19",
      "last_comparison_date": "2026-11-19",
      "clubs": [
        {
          "club_number": "113",
          "club_name": "Example Toastmasters Club",
          "division": "A",
          "area": "01",
          "event_count": 1,
          "total_delta": 0,
          "first_comparison_date": "2026-11-19",
          "last_comparison_date": "2026-11-19",
          "changes": [
            {}
          ]
        }
      ],
      "member_removal": {
        "period": "October",
        "removed": 0,
        "clubs": 0
      }
    }
  ],
  "pagination": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "has_more": true
  },
  "filters": {},
  "timestamp": "2026-11-19T04:30:00.000Z"
}

District

A district is a group of divisions, led by a District Director. It is identified by a number, except F for Founders District and U for clubs that belong to no district.

The district dashboard reports the district's totals and recognition goals, its divisions with their areas and clubs, its history month by month and its prospective clubs. Other endpoints compare a district with the same month last year and rank its clubs by their history.

View as Markdown

Compare a district's fiscal month with the same month last year

GET/api/district/{district}/year-comparison

View as Markdown

Returns the district summary figures, totals over the clubs for the district and each division, and every club's figures for a fiscal month and for the same fiscal month of the previous fiscal year. Both sides are monthly snapshots: last year's is that month's final report, this year's the latest report so far.

Path parameters

  • districtstringRequired

    District number/code.

Query parameters

  • fiscalYearstringoptional

    Fiscal year to compare. Defaults to the district's latest reported fiscal year.

  • fiscalMonthintegeroptional

    Fiscal month (1 = July) to compare. Defaults to the latest reported month in the fiscal year.

Returns

  • successenum

    Possible valuestrue

  • dataobject

    A district's reported fiscal month against the same fiscal month last year, from the monthly snapshots. Last year's side is that month's final report; this year's is the latest report so far, so report_date says which day each side reflects.

    10 child attributes
  • timestamptimestamp

Errors

  • 404No clubs reported for the district in that month.
  • 422Invalid district, fiscalYear, fiscalMonth, or an unsupported query parameter.
  • 500Internal server error
GET /api/district/{district}/year-comparison
curl "https://tm-api.devinpearson.me/api/district/74/year-comparison"
Response
{
  "success": true,
  "data": {
    "district": "74",
    "fiscal_year": "2026-2027",
    "fiscal_month": 5,
    "previous_fiscal_year": "2025-2026",
    "report_date": "2026-11-19",
    "previous_report_date": "2026-11-19",
    "summary": {
      "current": {
        "paid_clubs": 0,
        "paid_club_base": 0,
        "active_clubs": 0,
        "payments_to_date": 0,
        "payment_base": 0,
        "october_payments": 0,
        "april_payments": 0,
        "new_payments": 0,
        "late_payments": 0,
        "charter_payments": 0,
        "distinguished_clubs": 0
      },
      "previous": {
        "paid_clubs": 0,
        "paid_club_base": 0,
        "active_clubs": 0,
        "payments_to_date": 0,
        "payment_base": 0,
        "october_payments": 0,
        "april_payments": 0,
        "new_payments": 0,
        "late_payments": 0,
        "charter_payments": 0,
        "distinguished_clubs": 0
      },
      "change": {
        "paid_clubs": 0,
        "paid_club_base": 0,
        "active_clubs": 0,
        "payments_to_date": 0,
        "payment_base": 0,
        "october_payments": 0,
        "april_payments": 0,
        "new_payments": 0,
        "late_payments": 0,
        "charter_payments": 0,
        "distinguished_clubs": 0
      }
    },
    "clubs": {
      "current": {
        "clubs": 0,
        "suspended_clubs": 0,
        "paid_clubs": 0,
        "distinguished_clubs": 0,
        "member_base": 0,
        "active_members": 0,
        "net_growth": 0,
        "clubs_under_8_members": 0,
        "clubs_at_or_above_base": 0,
        "goals_met": 0,
        "clubs_with_no_goals": 0,
        "clubs_with_5_plus_goals": 0,
        "level_1s": 0,
        "level_2s": 0,
        "level_3s": 0,
        "level_4s": 0,
        "educational_awards": 0,
        "new_members": 0,
        "clubs_with_4_officers_trained_round_1": 0,
        "csp_submitted": 0
      },
      "previous": {
        "clubs": 0,
        "suspended_clubs": 0,
        "paid_clubs": 0,
        "distinguished_clubs": 0,
        "member_base": 0,
        "active_members": 0,
        "net_growth": 0,
        "clubs_under_8_members": 0,
        "clubs_at_or_above_base": 0,
        "goals_met": 0,
        "clubs_with_no_goals": 0,
        "clubs_with_5_plus_goals": 0,
        "level_1s": 0,
        "level_2s": 0,
        "level_3s": 0,
        "level_4s": 0,
        "educational_awards": 0,
        "new_members": 0,
        "clubs_with_4_officers_trained_round_1": 0,
        "csp_submitted": 0
      },
      "change": {
        "clubs": 0,
        "suspended_clubs": 0,
        "paid_clubs": 0,
        "distinguished_clubs": 0,
        "member_base": 0,
        "active_members": 0,
        "net_growth": 0,
        "clubs_under_8_members": 0,
        "clubs_at_or_above_base": 0,
        "goals_met": 0,
        "clubs_with_no_goals": 0,
        "clubs_with_5_plus_goals": 0,
        "level_1s": 0,
        "level_2s": 0,
        "level_3s": 0,
        "level_4s": 0,
        "educational_awards": 0,
        "new_members": 0,
        "clubs_with_4_officers_trained_round_1": 0,
        "csp_submitted": 0
      }
    },
    "divisions": [
      {
        "key": "string",
        "current": {
          "clubs": 0,
          "suspended_clubs": 0,
          "paid_clubs": 0,
          "distinguished_clubs": 0,
          "member_base": 0,
          "active_members": 0,
          "net_growth": 0,
          "clubs_under_8_members": 0,
          "clubs_at_or_above_base": 0,
          "goals_met": 0,
          "clubs_with_no_goals": 0,
          "clubs_with_5_plus_goals": 0,
          "level_1s": 0,
          "level_2s": 0,
          "level_3s": 0,
          "level_4s": 0,
          "educational_awards": 0,
          "new_members": 0,
          "clubs_with_4_officers_trained_round_1": 0,
          "csp_submitted": 0
        },
        "previous": {
          "clubs": 0,
          "suspended_clubs": 0,
          "paid_clubs": 0,
          "distinguished_clubs": 0,
          "member_base": 0,
          "active_members": 0,
          "net_growth": 0,
          "clubs_under_8_members": 0,
          "clubs_at_or_above_base": 0,
          "goals_met": 0,
          "clubs_with_no_goals": 0,
          "clubs_with_5_plus_goals": 0,
          "level_1s": 0,
          "level_2s": 0,
          "level_3s": 0,
          "level_4s": 0,
          "educational_awards": 0,
          "new_members": 0,
          "clubs_with_4_officers_trained_round_1": 0,
          "csp_submitted": 0
        },
        "change": {
          "clubs": 0,
          "suspended_clubs": 0,
          "paid_clubs": 0,
          "distinguished_clubs": 0,
          "member_base": 0,
          "active_members": 0,
          "net_growth": 0,
          "clubs_under_8_members": 0,
          "clubs_at_or_above_base": 0,
          "goals_met": 0,
          "clubs_with_no_goals": 0,
          "clubs_with_5_plus_goals": 0,
          "level_1s": 0,
          "level_2s": 0,
          "level_3s": 0,
          "level_4s": 0,
          "educational_awards": 0,
          "new_members": 0,
          "clubs_with_4_officers_trained_round_1": 0,
          "csp_submitted": 0
        }
      }
    ],
    "club_list": [
      {
        "club_number": "113",
        "club_name": "Example Toastmasters Club",
        "current": {
          "division": "A",
          "area": "01",
          "club_status": "string",
          "member_base": 0,
          "active_members": 0,
          "goals_met": 0,
          "educational_awards": 0
        },
        "previous": {
          "division": "A",
          "area": "01",
          "club_status": "string",
          "member_base": 0,
          "active_members": 0,
          "goals_met": 0,
          "educational_awards": 0
        }
      }
    ]
  },
  "timestamp": "2026-11-19T04:30:00.000Z"
}

Get ranked district club historical health

GET/api/district/{district}/clubs/historical-health

View as Markdown

Returns one complete, single district club-roster snapshot, ordered by finite historical-health score descending. Equal scores are ordered by canonical club number ascending and receive unique 1-based ordinal ranks; null scores are last and unranked. fiscalYear and fiscalMonth select only the current roster snapshot and never filter, cap, or otherwise alter the completed history selected by each reusable analysis. A known district snapshot with no clubs returns 200 and an empty clubs list. Only fiscalYear and fiscalMonth are supported query parameters; latest and unknown query parameters are rejected.

Path parameters

  • districtstringRequired

    District number/code.

Query parameters

  • fiscalYearstringoptional

    Roster snapshot fiscal year. Defaults using the district fiscal-year selection rules.

  • fiscalMonthintegeroptional

    Roster snapshot fiscal month. When omitted, the latest eligible month in the resolved fiscal year is selected.

Returns

  • successenum

    Possible valuestrue

  • fiscal_yearstring

    Fiscal year of the one resolved district roster snapshot.

  • fiscal_monthinteger

    Fiscal month of the one resolved district roster snapshot.

  • dataobject
    3 child attributes
  • summaryobject
    4 child attributes
  • metadataobject
    2 child attributes
  • filtersobject
    3 child attributes
  • timestamptimestamp

Errors

  • 404No district snapshot exists for the resolved fiscal year and month.
  • 422Invalid district, fiscalYear, fiscalMonth, or unsupported query parameter such as latest.
  • 500Internal server error
GET /api/district/{district}/clubs/historical-health
curl "https://tm-api.devinpearson.me/api/district/74/clubs/historical-health"
Response
{
  "success": true,
  "fiscal_year": "2026-2027",
  "fiscal_month": 5,
  "data": {
    "district": "74",
    "region": "11",
    "clubs": [
      {
        "rank": 1,
        "club_number": "113",
        "club_name": "Example Toastmasters Club",
        "division": "A",
        "area": "01",
        "club_status": "string",
        "active_members": 0,
        "distinguished_status": "string",
        "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": []
          },
          "trend": {
            "membership_change_percent_per_year": 0,
            "membership_volatility": 0,
            "latest_year_end_membership": 0
          },
          "yearly": [
            {}
          ],
          "explainability": {
            "components": [],
            "recent_award_classification": {},
            "benchmark_adjusted_trajectory": {},
            "reasons": []
          },
          "data_quality": {
            "confidence": "high",
            "excluded_years": [],
            "missing_metrics": [],
            "warnings": []
          }
        },
        "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": [
            {}
          ]
        }
      }
    ]
  },
  "summary": {
    "total_clubs": 0,
    "ranked_clubs": 0,
    "unranked_clubs": 0,
    "analysis_status_counts": {
      "available": 0,
      "limited_history": 0,
      "insufficient_data": 0,
      "no_history": 0
    }
  },
  "metadata": {
    "analysis_current_fiscal_year": "string",
    "ranking": {
      "key": "historical_health_analysis.score",
      "direction": "desc",
      "nulls": "last_unranked",
      "tie_breaker": "normalized_club_number_asc",
      "rank_style": "ordinal"
    }
  },
  "filters": {
    "district": "74",
    "fiscalYear": "2026-2027",
    "fiscalMonth": 5
  },
  "timestamp": "2026-11-19T04:30:00.000Z"
}

Get the district dashboard

GET/api/district/{district}

View as Markdown

The district's summary totals and recognition goals, its divisions with their areas and clubs, its monthly history, prospective clubs and insights, for the latest fiscal month of the fiscal year or the one requested. Division, area and district educational_ratio values are total awards divided by total member base; average_goals_met is the mean over clubs.

Path parameters

  • districtstringRequired

    District number/code

Query parameters

  • fiscalYearstringoptional

    Fiscal year (YYYY-YYYY); defaults to the latest fiscal year with dashboard data

  • fiscalMonthintegeroptional

    Fiscal month (1 = July); defaults to the latest month with data

  • latestbooleanoptional

    Use each record's latest snapshot

    Defaulttrue

Returns

  • successenum

    Possible valuestrue

  • fiscal_yearstring
  • fiscal_monthinteger
  • dataobject
    8 child attributes
  • summaryobject

    The district's totals, programme status and recognition goals for the fiscal month.

    50 child attributes
  • prospective_clubsarray of objects
    6 child attributes
  • monthly_historyarray of objects

    The same as data.monthly_history.

    13 child attributes
  • filtersobject
    4 child attributes
  • timestamptimestamp

Errors

  • 404No data for the district in the fiscal year
  • 422Invalid fiscal year or fiscal month
  • 500Internal server error
GET /api/district/{district}
curl "https://tm-api.devinpearson.me/api/district/74"
Response
{
  "success": true,
  "fiscal_year": "2026-2027",
  "fiscal_month": 5,
  "data": {
    "district": "74",
    "region": "11",
    "fiscal_year": "2026-2027",
    "district_context": {
      "district": "74",
      "region": "11",
      "fiscal_year": "2026-2027",
      "fiscal_month": 5,
      "educational_awards": 0,
      "member_base": 0,
      "educational_ratio": 0,
      "average_goals_met": 0
    },
    "divisions": [
      {
        "district": "74",
        "division": "A",
        "fiscal_year": "2026-2027",
        "fiscal_month": 5,
        "distinguished": "string",
        "club_base": 0,
        "total_dist_clubs": 0,
        "total_paid_clubs": 0,
        "dist_club_goal_for_dist": 0,
        "dist_club_goal_for_select_dist": 0,
        "dist_club_goal_for_pres_dist": 0,
        "paid_club_goal_for_dist": 0,
        "paid_club_goal_for_select_dist": 0,
        "paid_club_goal_for_pres_dist": 0,
        "total_members": 0,
        "clubs_5plus_goals": 0,
        "clubs_20plus_members": 0,
        "clubs_with_officers_trained_round_1": 0,
        "clubs_with_officers_trained_round_2": 0,
        "member_base": 0,
        "educational_awards": 0,
        "levels_completed": 0,
        "payments_to_date": 0,
        "educational_ratio": 0,
        "average_goals_met": 0,
        "member_payments": {
          "october_renewals": 0,
          "april_renewals": 0,
          "late_renewals": 0,
          "total_renewals": 0,
          "new_payments": 0,
          "charter_payments": 0,
          "total_to_date": 0
        },
        "payment_base": 0,
        "payment_goals": {
          "distinguished": 0,
          "select_distinguished": 0,
          "presidents_distinguished": 0,
          "smedley_distinguished": 0
        },
        "areas": [
          {
            "district": "74",
            "division": "A",
            "area": "01",
            "fiscal_year": "2026-2027",
            "fiscal_month": 5,
            "distinguished": "string",
            "total_dist_clubs": 0,
            "total_paid_clubs": 0,
            "dist_club_goal_for_dist": 0,
            "dist_club_goal_for_select_dist": 0,
            "dist_club_goal_for_pres_dist": 0,
            "paid_club_goal_for_dist": 0,
            "paid_club_goal_for_select_dist": 0,
            "paid_club_goal_for_pres_dist": 0,
            "total_members": 0,
            "clubs_5plus_goals": 0,
            "clubs_20plus_members": 0,
            "clubs_with_officers_trained_round_1": 0,
            "clubs_with_officers_trained_round_2": 0,
            "member_base": 0,
            "educational_awards": 0,
            "levels_completed": 0,
            "payments_to_date": 0,
            "educational_ratio": 0,
            "average_goals_met": 0,
            "member_payments": {},
            "clubs": []
          }
        ]
      }
    ],
    "monthly_history": [
      {
        "fiscal_year": "2026-2027",
        "fiscal_month": 5,
        "paid_clubs": 0,
        "active_clubs": 0,
        "payments_to_date": 0,
        "payment_base": 0,
        "new_payments": 0,
        "april_renewals": 0,
        "late_renewals": 0,
        "charter_payments": 0,
        "total_distinguished_clubs": 0,
        "select_distinguished_clubs": 0,
        "presidents_distinguished_clubs": 0
      }
    ],
    "insights": {
      "as_of": "2026-11-19",
      "month": "string",
      "month_target": 0,
      "show_potential_metrics": true,
      "divisions": [
        {
          "division": "A",
          "distinguished_status": "D",
          "areas": [
            {}
          ]
        }
      ]
    },
    "month_change": {
      "fiscal_year": "2026-2027",
      "fiscal_month": 5,
      "previous_fiscal_month": 1,
      "current": {
        "clubs": 0,
        "suspended_clubs": 0,
        "paid_clubs": 0,
        "distinguished_clubs": 0,
        "active_members": 0,
        "goals_met": 0,
        "educational_awards": 0,
        "new_members": 0
      },
      "previous": {
        "clubs": 0,
        "suspended_clubs": 0,
        "paid_clubs": 0,
        "distinguished_clubs": 0,
        "active_members": 0,
        "goals_met": 0,
        "educational_awards": 0,
        "new_members": 0
      },
      "change": {
        "clubs": 0,
        "suspended_clubs": 0,
        "paid_clubs": 0,
        "distinguished_clubs": 0,
        "active_members": 0,
        "goals_met": 0,
        "educational_awards": 0,
        "new_members": 0
      },
      "clubs_added": [
        "string"
      ],
      "clubs_removed": [
        "string"
      ],
      "parts": [
        {
          "key": "string",
          "current": {
            "clubs": 0,
            "suspended_clubs": 0,
            "paid_clubs": 0,
            "distinguished_clubs": 0,
            "active_members": 0,
            "goals_met": 0,
            "educational_awards": 0,
            "new_members": 0
          },
          "previous": {
            "clubs": 0,
            "suspended_clubs": 0,
            "paid_clubs": 0,
            "distinguished_clubs": 0,
            "active_members": 0,
            "goals_met": 0,
            "educational_awards": 0,
            "new_members": 0
          },
          "change": {
            "clubs": 0,
            "suspended_clubs": 0,
            "paid_clubs": 0,
            "distinguished_clubs": 0,
            "active_members": 0,
            "goals_met": 0,
            "educational_awards": 0,
            "new_members": 0
          },
          "clubs_added": [
            "string"
          ],
          "clubs_removed": [
            "string"
          ]
        }
      ]
    }
  },
  "summary": {
    "total_divisions": 0,
    "total_areas": 0,
    "paid_clubs": 0,
    "active_clubs": 0,
    "total_clubs": 0,
    "payment_base": 0,
    "paid_club_base": 0,
    "total_ytd_payments": 0,
    "distinguished_clubs": 0,
    "member_payments": {
      "october_renewals": 0,
      "april_renewals": 0,
      "late_renewals": 0,
      "total_renewals": 0,
      "new_payments": 0,
      "charter_payments": 0,
      "total_to_date": 0
    },
    "new_payments": 0,
    "april_renewals": 0,
    "late_renewals": 0,
    "charter_payments": 0,
    "payment_growth": 0,
    "club_growth": "string",
    "total_distinguished_clubs": 0,
    "total_csps_completed": 0,
    "select_distinguished_clubs": 0,
    "presidents_distinguished_clubs": 0,
    "smedley_distinguished_clubs": 0,
    "dsp": "string",
    "training": "string",
    "market_analysis": "string",
    "region_advisor_meetings": "string",
    "distinguished": "string",
    "fiscal_year": "2026-2027",
    "fiscal_month": 5,
    "member_base": 0,
    "educational_awards": 0,
    "educational_awards_breakdown": {
      "level_1": 0,
      "level_2": 0,
      "level_3": 0,
      "level_4": 0,
      "level_5": 0,
      "dtm": 0,
      "mentor_program": 0
    },
    "educational_awards_by_pathway": {},
    "educational_ratio": 0,
    "average_goals_met": 0,
    "active_members": 0,
    "average_members_per_club": 0,
    "average_new_members_per_club": 0,
    "clubs_5plus_goals": 0,
    "clubs_20plus_members": 0,
    "clubs_trained_r1": 0,
    "clubs_trained_r2": 0,
    "nov_visit_award": 0,
    "may_visit_award": 0,
    "monthly_membership_goals": {
      "distinguished": 0,
      "select_distinguished": 0,
      "presidents_distinguished": 0,
      "smedley_distinguished": 0
    },
    "monthly_membership_goals_fiscal_month": 0,
    "membership_goals": {
      "distinguished": 0,
      "select_distinguished": 0,
      "presidents_distinguished": 0,
      "smedley_distinguished": 0
    },
    "paid_club_goals": {
      "distinguished": 0,
      "select_distinguished": 0,
      "presidents_distinguished": 0,
      "smedley_distinguished": 0
    },
    "distinguished_club_goals": {
      "distinguished": 0,
      "select_distinguished": 0,
      "presidents_distinguished": 0,
      "smedley_distinguished": 0
    },
    "monthly_paid_club_goals": {
      "distinguished": 0,
      "select_distinguished": 0,
      "presidents_distinguished": 0,
      "smedley_distinguished": 0
    },
    "monthly_paid_club_goals_fiscal_month": 0
  },
  "prospective_clubs": [
    {
      "club_number": "113",
      "club_name": "Example Toastmasters Club",
      "division": "A",
      "area": "01",
      "status": "string",
      "date": "2026-11-19T04:30:00.000Z"
    }
  ],
  "monthly_history": [
    {
      "fiscal_year": "2026-2027",
      "fiscal_month": 5,
      "paid_clubs": 0,
      "active_clubs": 0,
      "payments_to_date": 0,
      "payment_base": 0,
      "new_payments": 0,
      "april_renewals": 0,
      "late_renewals": 0,
      "charter_payments": 0,
      "total_distinguished_clubs": 0,
      "select_distinguished_clubs": 0,
      "presidents_distinguished_clubs": 0
    }
  ],
  "filters": {
    "district": "74",
    "fiscalYear": "2026-2027",
    "fiscalMonth": 5,
    "latest": true
  },
  "timestamp": "2026-11-19T04:30:00.000Z"
}

Region

A region is a group of districts, supported by a Region Advisor. It is identified by its number.

The region endpoint reports each district in the region with its payments, club counts and recognition figures.

View as Markdown

Get region data

GET/api/region/{region}

View as Markdown

Retrieve data for a region by region identifier

Path parameters

  • regionstringRequired

    Region identifier

Query parameters

  • fiscalYearstringoptional

    Fiscal year (YYYY-YYYY); defaults to the current fiscal year

  • fiscalMonthintegeroptional

    Fiscal month (1 = July); defaults to each district's latest month

  • latestenumoptional

    false returns every monthly row instead of each district's latest month. true also skips the cached response.

    Possible valuestruefalse

    Defaulttrue

Returns

  • dataobject
    1 child attribute

Errors

  • 422A path or query parameter has an invalid value
  • 500Internal server error
GET /api/region/{region}
curl "https://tm-api.devinpearson.me/api/region/11"
Response
{
  "data": {
    "districts": [
      {
        "average_members_per_club": 0,
        "average_new_members_per_club": 0,
        "potential_distinguished_clubs": 0
      }
    ]
  }
}

Global

Every district and region together: each district's payments, recognition counts and goals, each region's totals, and the worldwide totals for a fiscal year.

View as Markdown

Get the global district summary

GET/api/global

View as Markdown

Every district's payments, recognition counts and goals, each region's totals, and the global totals and educational awards for the fiscal year. Complete responses are cached for 5 minutes per fiscalYear/fiscalMonth/latest combination; metadata.cached is true when a response is served from the cache.

Query parameters

  • fiscalYearstringoptional

    Fiscal year (YYYY-YYYY); defaults to the current fiscal year

  • fiscalMonthintegeroptional

    Fiscal month (1 = July); defaults to each district's latest month

  • latestbooleanoptional

    Use each district's latest snapshot for the division goals

    Defaulttrue

Returns

  • successenum

    Possible valuestrue

  • fiscal_yearstring
  • fiscal_monthnullable integer

    The requested fiscal month, else the current one for the current fiscal year, else null.

  • dataobject
    24 child attributes
  • metadataobject
    6 child attributes
  • filtersobject

    Always empty; kept for compatibility.

  • timestamptimestamp

Errors

  • 422Invalid fiscal year or fiscal month
  • 500Internal server error
GET /api/global
curl "https://tm-api.devinpearson.me/api/global"
Response
{
  "success": true,
  "fiscal_year": "2026-2027",
  "fiscal_month": 5,
  "data": {
    "total_districts": 0,
    "total_regions": 0,
    "payments_to_date": 0,
    "new_payments": 0,
    "april_payments": 0,
    "late_payments": 0,
    "charter_payments": 0,
    "payments_base": 0,
    "active_clubs": 0,
    "paid_clubs": 0,
    "paid_club_base": 0,
    "distinguished_clubs": 0,
    "total_distinguished_clubs": 0,
    "presidents_distinguished_clubs": 0,
    "select_distinguished_clubs": 0,
    "smedley_distinguished_clubs": 0,
    "total_csps_completed": 0,
    "educational_awards_breakdown": {
      "level_1": 0,
      "level_2": 0,
      "level_3": 0,
      "level_4": 0,
      "level_5": 0,
      "dtm": 0,
      "mentor_program": 0
    },
    "educational_awards_by_pathway": {},
    "distinguished_rate": 0,
    "paid_rate": 0,
    "average_clubs_per_district": 0,
    "districts": [
      {
        "district": "74",
        "region": "11",
        "fiscal_year": "2026-2027",
        "fiscal_month": 5,
        "payments_to_date": 0,
        "new_payments": 0,
        "april_payments": 0,
        "late_payments": 0,
        "charter_payments": 0,
        "payments_base": 0,
        "payment_growth": 0,
        "active_clubs": 0,
        "paid_clubs": 0,
        "paid_club_base": 0,
        "club_growth": "string",
        "distinguished_clubs": 0,
        "total_distinguished_clubs": 0,
        "presidents_distinguished_clubs": 0,
        "select_distinguished_clubs": 0,
        "smedley_distinguished_clubs": 0,
        "distinguished": "President's Distinguished",
        "distinguished_status": "President's Distinguished",
        "dsp": "string",
        "training": "string",
        "market_analysis": "string",
        "region_advisor_meetings": "string",
        "communication_plan": "string",
        "october_payments": 0,
        "distinguished_clubs_percent": 0,
        "clubs_5plus_goals": 0,
        "clubs_20plus_members": 0,
        "inactive_clubs": 0,
        "educational_ratio": 0,
        "average_goals_met": 0,
        "new_clubs_count": 0,
        "total_csps_completed": 0,
        "dist_club_goal_for_dist": 0,
        "dist_club_goal_for_select_dist": 0,
        "dist_club_goal_for_pres_dist": 0,
        "dist_club_goal_for_smed_dist": 0,
        "paid_club_goal_for_dist": 0,
        "paid_club_goal_for_select_dist": 0,
        "paid_club_goal_for_pres_dist": 0,
        "paid_club_goal_for_smed_dist": 0
      }
    ],
    "regions": [
      {
        "region": "11",
        "districts": [
          "string"
        ],
        "payments_to_date": 0,
        "new_payments": 0,
        "april_payments": 0,
        "late_payments": 0,
        "charter_payments": 0,
        "payments_base": 0,
        "active_clubs": 0,
        "paid_clubs": 0,
        "paid_club_base": 0,
        "distinguished_clubs": 0,
        "total_distinguished_clubs": 0,
        "presidents_distinguished_clubs": 0,
        "select_distinguished_clubs": 0,
        "smedley_distinguished_clubs": 0,
        "educational_awards": 0,
        "base_membership": 0,
        "total_goals_met": 0,
        "total_clubs": 0,
        "october_payments": 0,
        "total_districts": 0,
        "distinguished_rate": 0,
        "paid_rate": 0,
        "average_clubs_per_district": 0,
        "educational_ratio": 0,
        "average_goals_met": 0
      }
    ]
  },
  "metadata": {
    "last_updated": "2026-11-19T04:30:00.000Z",
    "cache_ttl": 0,
    "fiscal_year": "2026-2027",
    "response_time_ms": 0,
    "partial_data": true,
    "cached": true
  },
  "filters": {},
  "timestamp": "2026-11-19T04:30:00.000Z"
}

DCP History

A club's Distinguished Club Program results for each completed fiscal year: the goals it met, its membership at the start and end of the year and the recognition it earned. The fiscal year in progress is not included.

View as Markdown

Get DCP history for a club

GET/api/reports/dcp-history

View as Markdown

Retrieve Distinguished Club Program (DCP) historical performance data for a specific club across multiple fiscal years

Query parameters

  • clubNumberstringRequired

    Club number (required). Leading zeros are automatically trimmed (e.g., "0113" becomes "113")

  • fiscalYearstringoptional

    Filter by fiscal year in legacy YY-YY (e.g., "24-25") or normalized YYYY-YYYY form.

  • districtstringoptional

    District to filter by: a district number, U (undistricted) or F (Founders)

  • areastringoptional

    Filter by area

  • divisionstringoptional

    Filter by division

  • awardstringoptional

    Filter by award received (e.g., "Distinguished", "Select Distinguished", "President's Distinguished")

  • sortByenumoptional

    Field to sort by (default: "fiscal_year")

    Possible valuesfiscal_yeartotal_goalsretention_ratememb_base_7_1year_end_memb

    Defaultfiscal_year

  • sortOrderenumoptional

    Sort order (default: "desc" for most recent first)

    Possible valuesascdesc

    Defaultdesc

  • limitintegeroptional

    Maximum number of records to return

    Default1000

  • offsetintegeroptional

    Number of records to skip

    Default0

Returns

  • successboolean
  • dataarray of objects
    31 child attributes
  • summaryobject
    10 child attributes
  • paginationobject

    Pagination retained by specialized report endpoints. total_records is the total matching records.

    3 child attributes
  • sortingobject
    3 child attributes
  • filtersobject

Errors

  • 422clubNumber is missing or invalid
  • 500Internal server error
GET /api/reports/dcp-history
curl "https://tm-api.devinpearson.me/api/reports/dcp-history?clubNumber=113"
Response
{
  "success": true,
  "data": [
    {
      "club_number": "113",
      "club_name": "Example Toastmasters Club",
      "district": "74",
      "area": "01",
      "division": "A",
      "fiscal_year": "2026-2027",
      "memb_base_7_1": 0,
      "year_end_memb": 0,
      "traditional_goal_1": 0,
      "traditional_goal_2": 0,
      "traditional_goal_3": 0,
      "traditional_goal_4": 0,
      "traditional_goal_5": 0,
      "traditional_goal_6": 0,
      "pathways_goal_1": 0,
      "pathways_goal_2": 0,
      "pathways_goal_3": 0,
      "pathways_goal_4": 0,
      "pathways_goal_5": 0,
      "pathways_goal_6": 0,
      "goal_7_new_members": 0,
      "goal_8_add_new_members": 0,
      "goal_9_jun_aug_training": 0,
      "goal_9_dec_feb_training": 0,
      "goal_10_renewals": 0,
      "goal_10_officer_lists": 0,
      "total_goals": 0,
      "retention_rate": 0,
      "award": "string",
      "scraped_date": "2026-11-19",
      "data_source": "string"
    }
  ],
  "summary": {
    "total_records": 0,
    "fiscal_years_covered": 0,
    "average_goals_achieved": 0,
    "average_retention_rate": 0,
    "awards_received": 0,
    "best_year": {
      "fiscal_year": "2026-2027",
      "total_goals": 0,
      "retention_rate": 0,
      "award": "string"
    },
    "worst_year": {
      "fiscal_year": "2026-2027",
      "total_goals": 0,
      "retention_rate": 0,
      "award": "string"
    },
    "goal_achievement_by_category": {
      "traditional_goals": 0,
      "pathways_goals": 0,
      "general_goals": 0,
      "total_goals": 0
    },
    "membership_trends": [
      {
        "fiscal_year": "2026-2027",
        "memb_base_7_1": 0,
        "year_end_memb": 0,
        "retention_rate": 0
      }
    ],
    "club_info": {
      "club_number": "113",
      "club_name": "Example Toastmasters Club",
      "district": "74",
      "area": "01",
      "division": "A"
    }
  },
  "pagination": {
    "total_records": 0,
    "limit": 0,
    "offset": 0
  },
  "sorting": {
    "sort_by": "fiscal_year",
    "sort_order": "asc",
    "fiscal_years_in_result": [
      "string"
    ]
  },
  "filters": {}
}

Get detailed DCP history analysis for a club

GET/api/reports/dcp-history/analysis

View as Markdown

Retrieve comprehensive DCP performance analysis plus reusable completed-programme-year historical health analysis. Configuration 2.0 separates recent Distinguished-history class, benchmark-adjusted membership-risk trajectory, and diagnostic composite score. The existing 404 is retained when the club has no DCP-history rows.

Query parameters

  • clubNumberstringRequired

    Club number (required). Leading zeros are automatically trimmed (e.g., "0113" becomes "113")

Returns

  • successboolean
  • dataarray of objects
    31 child attributes
  • analysisobject
    6 child attributes
  • historical_health_analysisobject

    Completed-programme-year historical health analysis. Unlike the dashboard, this endpoint returns 404 instead of a no_history DTO when no DCP-history rows exist.

    13 child attributes
  • club_infoobject
    5 child attributes

Errors

  • 404Not found - No DCP history found for the specified club
  • 422clubNumber is missing or invalid
  • 500Internal server error
GET /api/reports/dcp-history/analysis
curl "https://tm-api.devinpearson.me/api/reports/dcp-history/analysis?clubNumber=113"
Response
{
  "success": true,
  "data": [
    {
      "club_number": "113",
      "club_name": "Example Toastmasters Club",
      "district": "74",
      "area": "01",
      "division": "A",
      "fiscal_year": "2026-2027",
      "memb_base_7_1": 0,
      "year_end_memb": 0,
      "traditional_goal_1": 0,
      "traditional_goal_2": 0,
      "traditional_goal_3": 0,
      "traditional_goal_4": 0,
      "traditional_goal_5": 0,
      "traditional_goal_6": 0,
      "pathways_goal_1": 0,
      "pathways_goal_2": 0,
      "pathways_goal_3": 0,
      "pathways_goal_4": 0,
      "pathways_goal_5": 0,
      "pathways_goal_6": 0,
      "goal_7_new_members": 0,
      "goal_8_add_new_members": 0,
      "goal_9_jun_aug_training": 0,
      "goal_9_dec_feb_training": 0,
      "goal_10_renewals": 0,
      "goal_10_officer_lists": 0,
      "total_goals": 0,
      "retention_rate": 0,
      "award": "string",
      "scraped_date": "2026-11-19",
      "data_source": "string"
    }
  ],
  "analysis": {
    "performance_trends": [
      {
        "fiscal_year": "2026-2027",
        "total_goals": 0,
        "retention_rate": 0,
        "award": "string",
        "membership_change": 0
      }
    ],
    "goal_patterns": {
      "traditional": {
        "total_achieved": 0,
        "average_per_year": 0
      },
      "pathways": {
        "total_achieved": 0,
        "average_per_year": 0
      },
      "general": {
        "total_achieved": 0,
        "average_per_year": 0
      }
    },
    "award_history": [
      {
        "fiscal_year": "2026-2027",
        "award": "string",
        "total_goals": 0,
        "retention_rate": 0
      }
    ],
    "membership_stability": {
      "average_retention": 0,
      "highest_retention": 0,
      "lowest_retention": 0,
      "average_membership": 0,
      "membership_volatility": 0
    },
    "years_analyzed": 0,
    "date_range": {
      "earliest": "string",
      "latest": "string"
    }
  },
  "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": [
          {
            "fiscal_year": "2026-2027",
            "membership": 0
          }
        ],
        "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_info": {
    "club_number": "113",
    "club_name": "Example Toastmasters Club",
    "district": "74",
    "area": "01",
    "division": "A"
  }
}

Club Performance

Rankings of clubs across a district, such as the clubs with the most educational awards for their size.

View as Markdown

Get top clubs by educational awards ratio

GET/api/reports/top-educational-awards-ratio

View as Markdown

Retrieve clubs with the highest ratio of educational awards to members

Query parameters

  • districtstringoptional

    District to rank; defaults to 74

    Default74

  • fiscalYearstringoptional

    Fiscal year (YYYY-YYYY); defaults to the current fiscal year

  • datedateoptional

    Rank as of the fiscal month this date falls in (YYYY-MM-DD)

  • divisionstringoptional

    Only clubs in this division

  • areastringoptional

    Only clubs in this area

  • minBaseintegeroptional

    Smallest July 1 member base a club needs to be ranked

    Default1

  • minAwardsintegeroptional

    Fewest educational awards a club needs to be ranked

    Default1

  • limitintegeroptional

    Number of top clubs to return (default: 10)

    Default10

Returns

  • dataarray of objects
    9 child attributes
  • summaryobject
    6 child attributes
  • filtersobject
  • timestamptimestamp

Errors

  • 422A path or query parameter has an invalid value
  • 500Internal server error
GET /api/reports/top-educational-awards-ratio
curl "https://tm-api.devinpearson.me/api/reports/top-educational-awards-ratio"
Response
{
  "data": [
    {
      "rank": 0,
      "club_number": "113",
      "club_name": "Example Toastmasters Club",
      "division": "A",
      "area": "01",
      "educational_awards": 0,
      "july_1_base": 0,
      "ratio": 0,
      "awards_breakdown": {
        "level_1s": 0,
        "level_2s": 0,
        "additional_level_2s": 0,
        "level_3s": 0,
        "level_4s": 0,
        "additional_level_4s": 0
      }
    }
  ],
  "summary": {
    "total_clubs_analyzed": 0,
    "total_clubs_returned": 0,
    "analysis_date": "2026-11-19",
    "overall_statistics": {},
    "top_performer": {},
    "division_summary": [
      {}
    ]
  },
  "filters": {},
  "timestamp": "2026-11-19T04:30:00.000Z"
}

Get dashboard filters

GET/api/dropdown/dashboard-filters

View as Markdown

Filter options for dashboard (districts, fiscal years, dates, etc.). Successful reads are shared-cacheable for approximately 60 seconds. Cache keys include the complete request URL and query string, and responses vary by Origin. Requests with latest=true and error responses use Cache-Control: no-store.

Query parameters

  • fiscalYearstringoptional

    Fiscal year (YYYY-YYYY) whose months to list; defaults to the current fiscal year

  • fiscalMonthintegeroptional

    Fiscal month (1 = July). With fiscalYear, adds that month's report dates. Takes precedence over month.

  • monthintegeroptional

    Calendar month (1 = January), as an alternative to fiscalMonth

Returns

  • successenum

    Possible valuestrue

  • dataobject
    4 child attributes
  • metadataobject
    5 child attributes

Errors

  • 422fiscalMonth is not between 1 and 12
  • 500Internal server error
GET /api/dropdown/dashboard-filters
curl "https://tm-api.devinpearson.me/api/dropdown/dashboard-filters"
Response
{
  "success": true,
  "data": {
    "fiscalYears": [
      {
        "value": "string",
        "label": "string"
      }
    ],
    "months": [
      {
        "value": 0,
        "label": "string",
        "month": 0
      }
    ],
    "dates": [
      {
        "value": "string",
        "label": "string",
        "date_value": "string"
      }
    ],
    "districts": [
      {
        "value": "string",
        "label": "string",
        "district": "74"
      }
    ]
  },
  "metadata": {
    "fiscal_year_count": 0,
    "month_count": 0,
    "date_count": 0,
    "district_count": 0,
    "last_updated": "2026-11-19T04:30:00.000Z"
  }
}

Get regions table

GET/api/dropdown/regions/table

View as Markdown

Regions derived from the districts table for dropdown/table display. Successful reads are shared-cacheable for approximately 60 seconds. Cache keys include the complete request URL and query string, and responses vary by Origin. Requests with latest=true and error responses use Cache-Control: no-store.

Returns

  • successenum

    Possible valuestrue

  • dataarray of objects
    3 child attributes
  • metadataobject
    3 child attributes

Errors

  • 422A path or query parameter has an invalid value
  • 500Internal server error
GET /api/dropdown/regions/table
curl "https://tm-api.devinpearson.me/api/dropdown/regions/table"
Response
{
  "success": true,
  "data": [
    {
      "value": "string",
      "label": "string",
      "region": "11"
    }
  ],
  "metadata": {
    "timestamp": "2026-11-19T04:30:00.000Z",
    "count": 0,
    "last_updated": "2026-11-19T04:30:00.000Z"
  }
}

Get districts table

GET/api/dropdown/districts/table

View as Markdown

Districts from the districts table for dropdown/table display. Successful reads are shared-cacheable for approximately 60 seconds. Cache keys include the complete request URL and query string, and responses vary by Origin. Requests with latest=true and error responses use Cache-Control: no-store.

Returns

  • successenum

    Possible valuestrue

  • dataarray of objects
    4 child attributes
  • metadataobject
    3 child attributes

Errors

  • 422A path or query parameter has an invalid value
  • 500Internal server error
GET /api/dropdown/districts/table
curl "https://tm-api.devinpearson.me/api/dropdown/districts/table"
Response
{
  "success": true,
  "data": [
    {
      "value": "string",
      "label": "string",
      "district": "74",
      "region": "11"
    }
  ],
  "metadata": {
    "timestamp": "2026-11-19T04:30:00.000Z",
    "count": 0,
    "last_updated": "2026-11-19T04:30:00.000Z"
  }
}

Get divisions table

GET/api/dropdown/divisions/table

View as Markdown

Divisions from the divisions table for dropdown/table display. Successful reads are shared-cacheable for approximately 60 seconds. Cache keys include the complete request URL and query string, and responses vary by Origin. Requests with latest=true and error responses use Cache-Control: no-store.

Query parameters

  • districtstringoptional

    Only options in this district

Returns

  • successenum

    Possible valuestrue

  • dataarray of objects
    4 child attributes
  • metadataobject
    4 child attributes

Errors

  • 422A path or query parameter has an invalid value
  • 500Internal server error
GET /api/dropdown/divisions/table
curl "https://tm-api.devinpearson.me/api/dropdown/divisions/table"
Response
{
  "success": true,
  "data": [
    {
      "value": "string",
      "label": "string",
      "district": "74",
      "division": "A"
    }
  ],
  "metadata": {
    "timestamp": "2026-11-19T04:30:00.000Z",
    "count": 0,
    "district": "74",
    "last_updated": "2026-11-19T04:30:00.000Z"
  }
}

Get areas table

GET/api/dropdown/areas/table

View as Markdown

Areas from the areas table for dropdown/table display. Successful reads are shared-cacheable for approximately 60 seconds. Cache keys include the complete request URL and query string, and responses vary by Origin. Requests with latest=true and error responses use Cache-Control: no-store.

Query parameters

  • districtstringoptional

    Only options in this district

  • divisionstringoptional

    Only areas in this division

Returns

  • successenum

    Possible valuestrue

  • dataarray of objects
    5 child attributes
  • metadataobject
    5 child attributes

Errors

  • 422A path or query parameter has an invalid value
  • 500Internal server error
GET /api/dropdown/areas/table
curl "https://tm-api.devinpearson.me/api/dropdown/areas/table"
Response
{
  "success": true,
  "data": [
    {
      "value": "string",
      "label": "string",
      "district": "74",
      "division": "A",
      "area": "01"
    }
  ],
  "metadata": {
    "timestamp": "2026-11-19T04:30:00.000Z",
    "count": 0,
    "district": "74",
    "division": "A",
    "last_updated": "2026-11-19T04:30:00.000Z"
  }
}

Tools

Planning tools that evaluate a hypothetical area or division made of existing clubs, to see how a regrouping would stand against the recognition goals.

View as Markdown

Evaluate a hypothetical area

POST/api/tools/hypothetical-area

View as Markdown

Groups existing clubs into one new area and evaluates it as of the clubs' report date: paid, Distinguished and 20+ member clubs, average goals against the month's target, the educational ratio, Area Director visits, member payments, and the area's Distinguished status with the standard goals. Suspended clubs are listed but not counted.

Request body

  • club_numbersarray of stringsRequired

    Club numbers; leading zeros are ignored and repeats are dropped.

Returns

  • successboolean
  • dataobject
    8 child attributes
  • timestamptimestamp

Errors

  • 400The request body is not valid JSON
  • 422The body was read but a value in it is invalid
  • 500Internal server error
POST /api/tools/hypothetical-area
curl -X POST "https://tm-api.devinpearson.me/api/tools/hypothetical-area" \
  -H "Content-Type: application/json" \
  -d '{"club_numbers":["113"]}'
Response
{
  "success": true,
  "data": {
    "as_of": "2026-11-19",
    "month": "string",
    "month_target": 0,
    "clubs": [
      {
        "club_number": "113",
        "club_name": "Example Toastmasters Club",
        "district": "74",
        "division": "A",
        "area": "01",
        "assigned_area": "string",
        "club_status": "string",
        "suspended": true,
        "charter_date": "string",
        "active_members": 0,
        "member_base": 0,
        "goals_met": 0,
        "educational_awards": 0,
        "educational_ratio": 0,
        "officers_trained_round_1": 0,
        "officers_trained_round_2": 0,
        "october_renewals": true,
        "april_renewals": true,
        "nov_visit": true,
        "may_visit": true,
        "coaches": 0,
        "distinguished_status": "D",
        "member_payments": {
          "late": 0,
          "oct_ren": 0,
          "apr_ren": 0,
          "total_ren": 0,
          "new": 0,
          "charter": 0,
          "total_new": 0
        },
        "latitude": 0,
        "longitude": 0,
        "location": "string",
        "address": "string",
        "feedback": {
          "needs_attention": true,
          "members_needed": 0,
          "needs_coach": true,
          "officers_round_1_needed": true,
          "officers_round_2_needed": true,
          "nov_visit_needed": true,
          "may_visit_needed": true
        }
      }
    ],
    "current_areas": [
      {
        "district": "74",
        "division": "A",
        "area": "01",
        "clubs": 0
      }
    ],
    "summary": {
      "paid_clubs": 0,
      "total_members": 0,
      "member_base": 0,
      "distinguished_clubs": 0,
      "twenty_plus_member_clubs": 0,
      "on_track_clubs": 0,
      "average_goals": 0,
      "member_payments": {
        "late": 0,
        "oct_ren": 0,
        "apr_ren": 0,
        "total_ren": 0,
        "new": 0,
        "charter": 0,
        "total_new": 0
      },
      "distinguished_pct": 0,
      "twenty_plus_member_pct": 0,
      "educational_awards": 0,
      "educational_ratio": 0,
      "visits": {
        "goal": 0,
        "nov": {
          "visited": 0,
          "pct": 0
        },
        "may": {
          "visited": 0,
          "pct": 0
        }
      },
      "distinguished_status": "D"
    },
    "recognition_goals": {
      "distinguished": {
        "paid_clubs": 0,
        "distinguished_clubs": 0
      },
      "select_distinguished": {
        "paid_clubs": 0,
        "distinguished_clubs": 0
      },
      "presidents_distinguished": {
        "paid_clubs": 0,
        "distinguished_clubs": 0
      }
    },
    "not_found": [
      "string"
    ]
  },
  "timestamp": "2026-11-19T04:30:00.000Z"
}

Evaluate a hypothetical division

POST/api/tools/hypothetical-division

View as Markdown

Groups existing clubs into new areas of one division and evaluates the division and each area as of the clubs' report date. Suspended clubs are listed but not counted.

Request body

  • areasarray of objectsRequired

    The new areas; a club listed in two areas stays in the first.

    2 child attributes

Returns

  • successboolean
  • dataobject
    8 child attributes
  • timestamptimestamp

Errors

  • 400The request body is not valid JSON
  • 422The body was read but a value in it is invalid
  • 500Internal server error
POST /api/tools/hypothetical-division
curl -X POST "https://tm-api.devinpearson.me/api/tools/hypothetical-division" \
  -H "Content-Type: application/json" \
  -d '{"areas":[{"area":"01","club_numbers":["113"]}]}'
Response
{
  "success": true,
  "data": {
    "as_of": "2026-11-19",
    "month": "string",
    "month_target": 0,
    "clubs": [
      {
        "club_number": "113",
        "club_name": "Example Toastmasters Club",
        "district": "74",
        "division": "A",
        "area": "01",
        "assigned_area": "string",
        "club_status": "string",
        "suspended": true,
        "charter_date": "string",
        "active_members": 0,
        "member_base": 0,
        "goals_met": 0,
        "educational_awards": 0,
        "educational_ratio": 0,
        "officers_trained_round_1": 0,
        "officers_trained_round_2": 0,
        "october_renewals": true,
        "april_renewals": true,
        "nov_visit": true,
        "may_visit": true,
        "coaches": 0,
        "distinguished_status": "D",
        "member_payments": {
          "late": 0,
          "oct_ren": 0,
          "apr_ren": 0,
          "total_ren": 0,
          "new": 0,
          "charter": 0,
          "total_new": 0
        },
        "latitude": 0,
        "longitude": 0,
        "location": "string",
        "address": "string",
        "feedback": {
          "needs_attention": true,
          "members_needed": 0,
          "needs_coach": true,
          "officers_round_1_needed": true,
          "officers_round_2_needed": true,
          "nov_visit_needed": true,
          "may_visit_needed": true
        }
      }
    ],
    "areas": [
      {
        "area": "01",
        "paid_clubs": 0,
        "total_members": 0,
        "distinguished_clubs": 0,
        "twenty_plus_member_clubs": 0,
        "five_plus_goal_clubs": 0,
        "officers_round_1_clubs": 0,
        "officers_round_2_clubs": 0,
        "average_goals": 0
      }
    ],
    "summary": {
      "paid_clubs": 0,
      "total_members": 0,
      "member_base": 0,
      "distinguished_clubs": 0,
      "twenty_plus_member_clubs": 0,
      "on_track_clubs": 0,
      "average_goals": 0,
      "member_payments": {
        "late": 0,
        "oct_ren": 0,
        "apr_ren": 0,
        "total_ren": 0,
        "new": 0,
        "charter": 0,
        "total_new": 0
      }
    },
    "recognition_goals": {
      "distinguished": {
        "paid_clubs": 0,
        "distinguished_clubs": 0
      },
      "select_distinguished": {
        "paid_clubs": 0,
        "distinguished_clubs": 0
      },
      "presidents_distinguished": {
        "paid_clubs": 0,
        "distinguished_clubs": 0
      }
    },
    "not_found": [
      "string"
    ]
  },
  "timestamp": "2026-11-19T04:30:00.000Z"
}

Health

Health, readiness and liveness probes for monitoring the service. They report a status word in plain JSON, not problem details.

View as Markdown

Health check

GET/api/health

View as Markdown

Public readiness summary. Detailed diagnostics are available only to authorized operators. The health endpoints report failures in their own format, with a status string, not as problem details.

Returns

  • statusenum

    Possible valuesokunhealthyerror

Errors

  • 500The health check itself failed
  • 503Service unhealthy (e.g. database disconnected)
GET /api/health
curl "https://tm-api.devinpearson.me/api/health"
Response
{
  "status": "ok"
}

Detailed health check

GET/api/health/detailed

View as Markdown

Detailed diagnostics with database, cache, memory, and disk checks. In production, send X-Health-Diagnostics-Token matching HEALTH_DIAGNOSTICS_TOKEN; omitted or invalid tokens intentionally receive 404. Authorization is not required outside production.

Authorization. Send the X-Health-Diagnostics-Token header. Production detailed-health token. Configure the server with HEALTH_DIAGNOSTICS_TOKEN.

Returns

  • statusenum

    Possible valueshealthyunhealthy

  • timestamptimestamp
  • checksobject
    5 child attributes

Errors

  • 404Not found when NODE_ENV is production and X-Health-Diagnostics-Token is missing or invalid
  • 500The health check itself failed
  • 503One or more checks unhealthy
GET /api/health/detailed
curl "https://tm-api.devinpearson.me/api/health/detailed"
Response
{
  "status": "healthy",
  "timestamp": "2026-11-19T04:30:00.000Z",
  "checks": {
    "database": {
      "status": "string",
      "message": "string"
    },
    "cache": {
      "status": "string",
      "message": "string"
    },
    "memory": {
      "status": "string",
      "message": "string"
    },
    "disk": {
      "status": "string",
      "message": "string"
    },
    "uptime": 0
  }
}

Readiness probe

GET/api/health/ready

View as Markdown

Kubernetes/Docker readiness probe; returns 200 when database is connected

Returns

  • statusenum

    Possible valuesreadynot ready

Errors

  • 503Not ready (e.g. database not connected)
GET /api/health/ready
curl "https://tm-api.devinpearson.me/api/health/ready"
Response
{
  "status": "ready"
}

Liveness probe

GET/api/health/live

View as Markdown

Kubernetes/Docker liveness probe; returns 200 if process is alive

Returns

  • statusenum

    Possible valuesalive

GET /api/health/live
curl "https://tm-api.devinpearson.me/api/health/live"
Response
{
  "status": "alive"
}

MCP server

The API also serves a Model Context Protocol (MCP) server, so an LLM client such as Claude can look up Toastmasters data itself. Its tools are read-only and use the same data and rules as the endpoints above.

View as Markdown

Connect

Point any client that speaks the Model Context Protocol at the server URL.

  • The transport is Streamable HTTP: the client sends each request as a POST. The server is stateless, so there is no session to open or keep.
  • No API key or sign-in is needed.
  • Contact details and members' names are left out of every tool.

The server gives a client these instructions when it connects:

Toastmasters club data for the Region → District → Division → Area → Club hierarchy, from Toastmasters' daily reports.

Find a club with search_clubs, then call get_club for its standing, Distinguished progress and next actions, or get_club_history for past years and recent changes.

Call get_area for an area's next actions (for its Area Director), Distinguished status, visit and officer-training rounds, and each club's milestone and outlook.

Call get_division for a division's Distinguished status, area visit summary, officer training and each area's status, and get_district for every division's and area's status.

get_club, get_area, get_division and get_district each include month_change: the figures (members, paid and Distinguished clubs, DCP goals, educational awards, new members) for the reported fiscal month against the month before, with the difference, so a report can show what changed last month. It is null in July, when the fiscal year starts again.

To plan a regrouping, call simulate_area with club numbers, or simulate_division with new areas of club numbers.

Insights are evaluated as of the report date (as_of), not today. Read toastmasters://rules/dcp for the rules behind them and toastmasters://glossary for terms.

Club numbers are canonical without leading zeros ("00000113" and "113" are the same club).

Server URL
https://tm-api.devinpearson.me/mcp
Add the server
claude mcp add --transport http toastmasters https://tm-api.devinpearson.me/mcp

Search clubs

TOOLsearch_clubs

View as Markdown

Find clubs by name (at least 2 characters) in the current fiscal year, optionally within one district.

Arguments

  • namestringRequired

    Part of the club's name, e.g. "sages"

  • districtstring

    District, e.g. "74"; "U" is undistricted, "F" the Founders District

  • limitinteger

    Most results to return (default 20)

tools/call
curl -X POST "https://tm-api.devinpearson.me/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_clubs","arguments":{"name":"sages"}}}'

Get club

TOOLget_club

View as Markdown

A club's status, membership, DCP goals and insights: good standing, its Club Success Plan deadline, Distinguished progress, ranked next actions, its outlook (doing well, improving, steady, declining or definite worry, with the reasons), as of the report date, and month_change: its members, goals, awards, new members and status against the fiscal month before.

Arguments

  • club_numberstringRequired

    Toastmasters club number, e.g. "113" or "00000113"

  • fiscal_yearstring

    Fiscal year as "YYYY-YYYY"; defaults to the current one

tools/call
curl -X POST "https://tm-api.devinpearson.me/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_club","arguments":{"club_number":"113"}}}'

Get club history

TOOLget_club_history

View as Markdown

A club's past fiscal years (goals, Distinguished status, membership) and its recent changes by day, with report glitches removed.

Arguments

  • club_numberstringRequired

    Toastmasters club number, e.g. "113" or "00000113"

  • changesinteger

    Most recent change events to include (default 50)

tools/call
curl -X POST "https://tm-api.devinpearson.me/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_club_history","arguments":{"club_number":"113"}}}'

Get area

TOOLget_area

View as Markdown

An area's totals, its clubs in brief, and insights as of the report date: the Area Director's next actions, the area's Distinguished status, the two visit rounds, officer training rounds, and each club's Distinguished milestone, reminders and outlook (doing well, improving, steady, declining or definite worry, with the reasons). month_change compares the area's totals and each club's with the fiscal month before.

Arguments

  • districtstringRequired

    District, e.g. "74"

  • divisionstringRequired

    Division letter, e.g. "A"

  • areastringRequired

    Area number within the division, e.g. "02"

  • fiscal_yearstring

    Fiscal year as "YYYY-YYYY"; defaults to the current one

tools/call
curl -X POST "https://tm-api.devinpearson.me/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_area","arguments":{"district":"74","division":"A","area":"01"}}}'

Get division

TOOLget_division

View as Markdown

A division's totals, recognition goals and areas in brief, and insights as of the report date: its Distinguished status, the area visit summary, officer training for the division and each area, and each area's Distinguished status. month_change compares the division's totals and each area's with the fiscal month before.

Arguments

  • districtstringRequired

    District, e.g. "74"

  • divisionstringRequired

    Division letter, e.g. "A"

  • fiscal_yearstring

    Fiscal year as "YYYY-YYYY"; defaults to the current one

tools/call
curl -X POST "https://tm-api.devinpearson.me/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_division","arguments":{"district":"74","division":"A"}}}'

Get district

TOOLget_district

View as Markdown

A district's divisions in brief, and insights as of the report date: the month's DCP target and the Distinguished status of every division and area. month_change compares the district's totals and each division's with the fiscal month before.

Arguments

  • districtstringRequired

    District, e.g. "74"; "U" is undistricted, "F" the Founders District

  • fiscal_yearstring

    Fiscal year as "YYYY-YYYY"; defaults to the latest one

tools/call
curl -X POST "https://tm-api.devinpearson.me/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_district","arguments":{"district":"74"}}}'

Get data freshness

TOOLget_data_freshness

View as Markdown

How current the data is: the latest club performance snapshot and the latest day of club changes, optionally for one district.

Arguments

  • districtstring

    District, e.g. "74"

tools/call
curl -X POST "https://tm-api.devinpearson.me/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_data_freshness","arguments":{}}}'

Simulate area

TOOLsimulate_area

View as Markdown

Evaluate a hypothetical area made of existing clubs, as of their report date: paid, Distinguished and 20+ member clubs, average goals against the month's target, Area Director visits, payments, the area's Distinguished status with the standard goals (4 paid and 2 Distinguished clubs, 4 and 3, 5 and 3), and what each club still needs. Suspended clubs are listed but not counted.

Arguments

  • club_numbersarray of stringsRequired

    The clubs in the new area

tools/call
curl -X POST "https://tm-api.devinpearson.me/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"simulate_area","arguments":{"club_numbers":["113"]}}}'

Simulate division

TOOLsimulate_division

View as Markdown

Evaluate a hypothetical division of new areas, each made of existing clubs, as of their report date: the division's totals and on-track clubs, and each area's paid, Distinguished, 20+ member and 5+ goal clubs, officer training and average goals. A club listed in two areas stays in the first.

Arguments

  • areasarray of objectsRequired

    The new areas and their clubs

    2 child attributes
tools/call
curl -X POST "https://tm-api.devinpearson.me/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"simulate_division","arguments":{"areas":[{"area":"01","club_numbers":["113"]}]}}}'

Resources

Documents a client can read from the server, alongside its tools.

Resources

  • toastmasters://rules/dcptext/markdown

    Club rules. Good standing, Distinguished levels, deadlines and membership counting, as the tools apply them.

  • toastmasters://glossarytext/markdown

    Glossary. Toastmasters reporting vocabulary.