# 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.

Base URL: `https://tm-api.devinpearson.me`

## Get division data

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

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**

- `district` (string, required): District number/code
- `division` (string, required): Division identifier

**Query parameters**

- `fiscalYear` (string, optional): Fiscal year (YYYY-YYYY); defaults to the current fiscal year
- `include` (string, optional): Comma-separated extra blocks to include
- `latest` (enum, optional): true skips the cached response and sends Cache-Control: no-store One of: `true`, `false`.

**Returns**

- `success` (boolean)
- `metadata` (object): Payment targets are optional enrichment. partial_data is true when they are unavailable.
  - `partial_data` (boolean)
  - `partial_data_reasons` (array of strings)
  - `payment_targets` (object)
    - `available` (boolean)
    - `reason` (string)
- `data` (object)
  - `insights` (nullable object): Toastmasters rules evaluated for the division as of the report date (src/domain): its Distinguished status, the area visit summary, officer training for the division and each area, and each area's Distinguished status. Null when the division has no club rows with an import date.
    - `as_of` (date): Report date: when the division's club rows were last imported, no later than the end of their fiscal month.
    - `month` (string)
    - `month_target` (integer): Goals a club should have met by this month.
    - `show_potential_metrics` (boolean): False in April – June, when clubs can become Distinguished outright.
    - `distinguished_status` (nullable enum) One of: `D`, `S`, `P`, `null`.
    - `on_track_clubs` (integer): Clubs with 20+ members and at least this month's target of goals.
    - `visits` (nullable object): Area Director visits across the areas (75% of each area's clubs); null when any club lacks visit data.
      - `areaCount` (integer)
      - `julyOct` (object)
        - `clubsVisited` (integer)
        - `clubsRequired` (integer)
        - `areasMet` (integer)
      - `janMay` (object)
        - `clubsVisited` (integer)
        - `clubsRequired` (integer)
        - `areasMet` (integer)
    - `officer_training` (object)
      - `round_1` (object)
        - `clubs_counted` (integer): Clubs that count for the round: not suspended, and for round 1 chartered by 31 August.
        - `officers_trained` (integer): The division's reported total when there is one, otherwise the counted clubs' sum.
        - `officers_possible` (integer): 7 officers per counted club.
        - `trained_pct` (nullable integer)
        - `window_open` (boolean)
      - `round_2` (object)
        - `clubs_counted` (integer): Clubs that count for the round: not suspended, and for round 1 chartered by 31 August.
        - `officers_trained` (integer): The division's reported total when there is one, otherwise the counted clubs' sum.
        - `officers_possible` (integer): 7 officers per counted club.
        - `trained_pct` (nullable integer)
        - `window_open` (boolean)
    - `areas` (array of objects)
      - `area` (string)
      - `distinguished_status` (nullable enum) One of: `D`, `S`, `P`, `null`.
      - `officers_round_1_pct` (integer)
      - `officers_round_2_pct` (integer)
  - `month_change` (object or nullable enum): The division's totals against the fiscal month before, with each area's change in parts; null when no clubs were reported for the month.
    - `fiscal_year` (string)
    - `fiscal_month` (integer): Fiscal month (1 = July) of the figures.
    - `previous_fiscal_month` (nullable integer): The fiscal month compared with; null in July, which starts the fiscal year.
    - `current` (object): A scope's totals over its clubs for one fiscal month. Suspended clubs count only as suspended.
      - `clubs` (integer): Clubs that aren't suspended.
      - `suspended_clubs` (integer)
      - `paid_clubs` (integer): Clubs that aren't suspended with an October or April renewal on record.
      - `distinguished_clubs` (integer)
      - `active_members` (integer)
      - `goals_met` (integer): DCP goals met, summed over the clubs.
      - `educational_awards` (integer)
      - `new_members` (integer): New and additional new members counted for the DCP.
    - `previous` (object or nullable enum): Last month's totals; null in July or when no clubs were reported last month.
      - `clubs` (integer): Clubs that aren't suspended.
      - `suspended_clubs` (integer)
      - `paid_clubs` (integer): Clubs that aren't suspended with an October or April renewal on record.
      - `distinguished_clubs` (integer)
      - `active_members` (integer)
      - `goals_met` (integer): DCP goals met, summed over the clubs.
      - `educational_awards` (integer)
      - `new_members` (integer): New and additional new members counted for the DCP.
    - `change` (object or nullable enum): This month's totals minus last month's; null when previous is.
      - `clubs` (integer): Clubs that aren't suspended.
      - `suspended_clubs` (integer)
      - `paid_clubs` (integer): Clubs that aren't suspended with an October or April renewal on record.
      - `distinguished_clubs` (integer)
      - `active_members` (integer)
      - `goals_met` (integer): DCP goals met, summed over the clubs.
      - `educational_awards` (integer)
      - `new_members` (integer): New and additional new members counted for the DCP.
    - `clubs_added` (array of strings): Clubs here this month but not last month: chartered or moved in.
    - `clubs_removed` (array of strings): Clubs here last month but not this month: moved out or no longer reported.
    - `parts` (array of objects)
      - `key` (string): The division letter, area number or club number.
      - `current` (object): A scope's totals over its clubs for one fiscal month. Suspended clubs count only as suspended.
        - `clubs` (integer): Clubs that aren't suspended.
        - `suspended_clubs` (integer)
        - `paid_clubs` (integer): Clubs that aren't suspended with an October or April renewal on record.
        - `distinguished_clubs` (integer)
        - `active_members` (integer)
        - `goals_met` (integer): DCP goals met, summed over the clubs.
        - `educational_awards` (integer)
        - `new_members` (integer): New and additional new members counted for the DCP.
      - `previous` (object or nullable enum): Last month's totals; null in July or when no clubs were reported last month.
        - `clubs` (integer): Clubs that aren't suspended.
        - `suspended_clubs` (integer)
        - `paid_clubs` (integer): Clubs that aren't suspended with an October or April renewal on record.
        - `distinguished_clubs` (integer)
        - `active_members` (integer)
        - `goals_met` (integer): DCP goals met, summed over the clubs.
        - `educational_awards` (integer)
        - `new_members` (integer): New and additional new members counted for the DCP.
      - `change` (object or nullable enum): This month's totals minus last month's; null when previous is.
        - `clubs` (integer): Clubs that aren't suspended.
        - `suspended_clubs` (integer)
        - `paid_clubs` (integer): Clubs that aren't suspended with an October or April renewal on record.
        - `distinguished_clubs` (integer)
        - `active_members` (integer)
        - `goals_met` (integer): DCP goals met, summed over the clubs.
        - `educational_awards` (integer)
        - `new_members` (integer): New and additional new members counted for the DCP.
      - `clubs_added` (array of strings): Clubs here this month but not last month: chartered or moved in.
      - `clubs_removed` (array of strings): Clubs here last month but not this month: moved out or no longer reported.
  - `district` (string)
  - `division` (string): Division identifier retained for compatibility.
  - `average_goals_met` (nullable number)
  - `educational_ratio` (nullable number)
  - `division_context` (object): Division identifiers and division-wide metric benchmarks.
  - `district_context` (object): Actual district-wide benchmarks for the same fiscal scope.
  - `areas` (array of objects)
    - `average_goals_met` (nullable number)
    - `educational_ratio` (nullable number)
    - `clubs` (array of objects)
      - `club_number` (string)
      - `club_name` (string)
      - `club_outlook` (object): Area responses only: the club's outlook, as on the club dashboard.
        - `version` (enum) One of: `1`.
        - `category` (nullable enum): Null when the club has no completed year and isn't under 8 paid members after October. One of: `doing_well`, `improving`, `steady`, `declining`, `definite_worry`, `null`.
        - `label` (nullable string)
        - `basis` (enum): renewals once October renewals are in; history before that. One of: `renewals`, `history`.
        - `health_score` (nullable number): 100 minus points for the last completed programme year.
        - `health_score_change` (nullable number): Health score minus the average of the two programme years before it.
        - `scored_year` (nullable string)
        - `paid_members` (nullable number)
        - `last_year_end_members` (nullable number)
        - `retention` (nullable number): Paid members now as a share of last year end's, from October.
        - `reasons` (array of strings): Why the club is in its group, most important first.
        - `points` (array of objects): Points taken off 100 for the scored year, largest first.
          - `key` (enum) One of: `members`, `dcp_goals`, `new_members`, `officer_training`, `renewals`, `members_lost`, `distinguished`.
          - `points` (number)
          - `reason` (string)
      - `educational_awards` (number): Sum of level_1s, level_2s, add_level_2s, level_3s, level_4s_path_completions_or_dtm_awards, and add_level_4s_path_completions_or_dtm_award.
      - `educational_ratio` (nullable number): Educational awards divided by mem_base; null when mem_base is zero.
      - `average_goals_met` (nullable number): Compatibility field on division responses containing this club's own goals_met value.
      - `nov_visit_award` (nullable number): 1 when the club's first-round (July–November) area director visit is recorded, otherwise 0.
      - `may_visit_award` (nullable number): 1 when the club's second-round (December–May) area director visit is recorded, otherwise 0.
      - `area_average_goals_met` (nullable number): Arithmetic mean of goals_met across clubs in the selected area.
      - `area_average_educational_ratio` (nullable number): Arithmetic mean of defined club educational ratios in the selected area.
      - `goals_vs_area_average` (nullable enum) One of: `above`, `below`, `at`.
      - `educational_ratio_vs_area_average` (nullable enum) One of: `above`, `below`, `at`.
      - `july_officer_list` (array of objects): July officer list entries for the club in the selected fiscal year
        - `list_status` (nullable string)
        - `election_type` (nullable string)
        - `date` (nullable date)
      - `july_officer_list_status` (boolean): True when latest July officer list status indicates Received, else false

**Errors**

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

**Example request**

```bash
curl "https://tm-api.devinpearson.me/api/district/74/division/A"
```

**Example response**

```json
{
  "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`

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**

- `district` (string, required)
- `division` (string, required)

**Query parameters**

- `fiscalYear` (string, optional): Toastmasters fiscal year. Defaults to the current fiscal year.
- `fiscalMonth` (integer, optional)
- `date` (date, optional)
- `startDate` (date, optional)
- `endDate` (date, optional)
- `category` (enum, optional) One of: `lifecycle`, `membership`, `education`, `status`, `renewals`.
- `metric` (string, optional)
- `limit` (integer, optional, default 1000): Maximum number of records to return
- `offset` (integer, optional, default 0): Number of records to skip
- `sortOrder` (enum, optional, default desc) One of: `asc`, `desc`.
- `view` (enum, optional): 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. One of: `day`.

**Returns**

- `success` (boolean)
- `division` (object)
  - `district` (string)
  - `division` (string)
- `data` (array of objects)
  - `category` (enum) One of: `lifecycle`, `membership`, `education`, `status`, `renewals`.
  - `metric` (string)
  - `event_count` (integer)
  - `clubs_affected` (integer)
  - `total_delta` (nullable number): Sum of numeric deltas across the selected area and period; null when the metric is non-numeric.
  - `first_comparison_date` (date)
  - `last_comparison_date` (date)
  - `clubs` (array of objects)
    - `club_number` (string)
    - `club_name` (nullable string)
    - `division` (nullable string)
    - `area` (nullable string)
    - `event_count` (integer)
    - `total_delta` (nullable number): Sum of numeric event deltas for this club; null for non-numeric metrics such as lifecycle events.
    - `first_comparison_date` (date)
    - `last_comparison_date` (date)
    - `changes` (array of objects)
      - `comparison_date` (date)
      - `previous_date` (date)
      - `change_type` (enum) One of: `increased`, `decreased`, `changed`, `club_added`, `club_removed`.
      - `old_value` (nullable string)
      - `new_value` (nullable string)
      - `old_value_numeric` (nullable number)
      - `new_value_numeric` (nullable number)
      - `delta_numeric` (nullable number)
  - `member_removal` (nullable object): view=day only: members removed for unpaid dues, when this is an October or April active-member drop; otherwise null.
    - `period` (enum) One of: `October`, `April`.
    - `removed` (integer): Members removed (the drop in active members).
    - `clubs` (integer): Clubs whose active members fell.
- `pagination` (object): Pagination returned by member-payments endpoints. total is the total matching records.
  - `total` (integer): Total matching records
  - `limit` (integer): Number of records per page
  - `offset` (integer): Number of records to skip
  - `has_more` (boolean): Whether there are more records available
- `filters` (object)
- `timestamp` (timestamp)

**Errors**

- `422`: Invalid division changelog query
- `500`: Internal server error

**Example request**

```bash
curl "https://tm-api.devinpearson.me/api/district/74/division/A/changelog"
```

**Example response**

```json
{
  "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"
}
```
