# Evaluate a hypothetical division

`POST /api/tools/hypothetical-division`

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 (JSON)**

- `areas` (array of objects, required): The new areas; a club listed in two areas stays in the first.
  - `area` (string, required)
  - `club_numbers` (array of strings, required): Club numbers; leading zeros are ignored and repeats are dropped.

**Returns**

- `success` (boolean)
- `data` (object)
  - `as_of` (date): The newest of the clubs' report dates.
  - `month` (string)
  - `month_target` (integer): Goals a club should have met by this month.
  - `clubs` (array of objects)
    - `club_number` (string)
    - `club_name` (string)
    - `district` (string)
    - `division` (string)
    - `area` (string): The club's current area.
    - `assigned_area` (string): Hypothetical division only: the new area the club was assigned to.
    - `club_status` (string)
    - `suspended` (boolean): Suspended clubs are listed but left out of every total.
    - `charter_date` (nullable string)
    - `active_members` (integer)
    - `member_base` (integer)
    - `goals_met` (integer)
    - `educational_awards` (integer)
    - `educational_ratio` (nullable number)
    - `officers_trained_round_1` (integer)
    - `officers_trained_round_2` (integer)
    - `october_renewals` (boolean)
    - `april_renewals` (boolean)
    - `nov_visit` (boolean)
    - `may_visit` (boolean)
    - `coaches` (integer)
    - `distinguished_status` (nullable enum) One of: `D`, `S`, `P`, `M`, `null`.
    - `member_payments` (object)
      - `late` (integer)
      - `oct_ren` (integer)
      - `apr_ren` (integer)
      - `total_ren` (integer)
      - `new` (integer)
      - `charter` (integer)
      - `total_new` (integer)
    - `latitude` (nullable number)
    - `longitude` (nullable number)
    - `location` (nullable string)
    - `address` (nullable string)
    - `feedback` (object): What the club still needs as of the report date.
      - `needs_attention` (boolean): Fewer than 20 members or fewer than 5 goals.
      - `members_needed` (integer): Members still needed to reach 20.
      - `needs_coach` (boolean): Fewer than 10 members and no coach assigned.
      - `officers_round_1_needed` (boolean)
      - `officers_round_2_needed` (boolean)
      - `nov_visit_needed` (boolean)
      - `may_visit_needed` (boolean)
  - `areas` (array of objects)
    - `area` (string)
    - `paid_clubs` (integer)
    - `total_members` (integer)
    - `distinguished_clubs` (integer)
    - `twenty_plus_member_clubs` (integer)
    - `five_plus_goal_clubs` (integer)
    - `officers_round_1_clubs` (integer): Clubs with 4+ officers trained in round 1.
    - `officers_round_2_clubs` (integer)
    - `average_goals` (number)
  - `summary` (object)
    - `paid_clubs` (integer): Clubs that aren't suspended.
    - `total_members` (integer)
    - `member_base` (integer)
    - `distinguished_clubs` (integer)
    - `twenty_plus_member_clubs` (integer)
    - `on_track_clubs` (integer): Clubs with 20+ members and at least this month's target of goals.
    - `average_goals` (number)
    - `member_payments` (object)
      - `late` (integer)
      - `oct_ren` (integer)
      - `apr_ren` (integer)
      - `total_ren` (integer)
      - `new` (integer)
      - `charter` (integer)
      - `total_new` (integer)
  - `recognition_goals` (object): The standard recognition goals: paid clubs and Distinguished clubs for each level.
    - `distinguished` (object)
      - `paid_clubs` (integer)
      - `distinguished_clubs` (integer)
    - `select_distinguished` (object)
      - `paid_clubs` (integer)
      - `distinguished_clubs` (integer)
    - `presidents_distinguished` (object)
      - `paid_clubs` (integer)
      - `distinguished_clubs` (integer)
  - `not_found` (array of strings)
- `timestamp` (timestamp)

**Errors**

- `400`: The request body is not valid JSON
- `422`: The body was read but a value in it is invalid
- `500`: Internal server error

**Example request**

```bash
curl -X POST "https://tm-api.devinpearson.me/api/tools/hypothetical-division" \
  -H "Content-Type: application/json" \
  -d '{"areas":[{"area":"01","club_numbers":["113"]}]}'
```

**Example response**

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