---
title: "Start Apply"
method: POST
path: "/admin/import-plans/{plan_id}/apply"
tags: ["admin-import-plans"]
---

# Start Apply

`POST /admin/import-plans/{plan_id}/apply`

Create or complete the classes of the ready groups, on the server.
Returns at once; the plan shows the progress and the recap.

## Path parameters

- `plan_id` string, required

## Request body

- ImportPlanApplyStart
  - `group_ids` string[]
  - `options` ApplyOptions
    - `send_student_invitations` boolean
    - `prepare_invited_teacher_classes` boolean
    - `invite_missing_teachers` boolean

## Response `200`

Successful Response

- ImportPlanResponse
  - `id` string, required
  - `school_id` string, required
  - `school_name` string, required
  - `school_year` string, required
  - `revision` integer, required
  - `created_at` string, date-time, required
  - `created_by` PlanAuthor, required — Who did something: an admin, the page assistant or Claude through the MCP (both acting for an admin), the model reading a file, the system.
    - `kind` 'admin' | 'assistant' | 'mcp' | 'system' | 'model', required
    - `email` string, nullable
    - `name` string, nullable
  - `updated_at` string, date-time, required
  - `updated_by` PlanAuthor, required — Who did something: an admin, the page assistant or Claude through the MCP (both acting for an admin), the model reading a file, the system.
    - `kind` 'admin' | 'assistant' | 'mcp' | 'system' | 'model', required
    - `email` string, nullable
    - `name` string, nullable
  - `state` string, required
  - `status_counts` object, required
  - `waiting_for` string, nullable
  - `page_url` string
  - `sources` SourceResponse[], required
    - `id` string, required
    - `file_name` string, required
    - `kind` string, required
    - `size_bytes` integer, required
    - `added_at` string, date-time, required
    - `added_by` PlanAuthor, required — Who did something: an admin, the page assistant or Claude through the MCP (both acting for an admin), the model reading a file, the system.
      - `kind` 'admin' | 'assistant' | 'mcp' | 'system' | 'model', required
      - `email` string, nullable
      - `name` string, nullable
    - `grid` FileGrid — One file: its sheets in workbook order (a CSV, a PDF or pasted text is a single sheet). `limits_hit` lists every cap that cut something, so a partial read is never mistaken for the whole file.
      - `file_name` string, required
      - `kind` 'xlsx' | 'xls' | 'ods' | 'csv' | 'pdf' | 'text', required
      - `size_bytes` integer
      - `sheets` SheetGrid[]
        - `name` string, required
        - `index` integer, required
        - `hidden` boolean
        - `rows` array[]
          - string[]
        - `declared_rows` integer
        - `declared_cols` integer
        - `hidden_rows` integer[]
        - `hidden_cols` string[]
        - `merged` string[]
        - `formulas` object
        - `truncated` string, nullable
      - `warnings` string[]
      - `limits_hit` string[]
      - `error` string, nullable
    - `sheets` SheetSummary[], required
      - `name` string, required
      - `hidden` boolean, required
      - `n_rows` integer, required
      - `n_cols` integer, required
      - `declared_rows` integer, required
      - `non_empty_rows` integer, required
      - `hidden_rows` integer, required
      - `hidden_cols` string[], required
      - `merged` integer, required
      - `formulas` integer, required
      - `formulas_sample` array[]
        - unknown[]
          - unknown
      - `truncated` string, nullable
    - `warnings` string[]
    - `limits_hit` string[]
    - `error` string, nullable
  - `mapping` StructureMapping, required
    - `sheets` SheetMappingOutput[]
      - `source_id` string, required
      - `sheet` string, required
      - `ignored` boolean
      - `regions` SheetRegion[]
        - `role` 'students' | 'teachers' | 'division_teachers', required
        - `header_row` integer, nullable
        - `first_row` integer, required
        - `last_row` integer, nullable
        - `skip_rows` integer[]
        - `columns` ColumnMeaning[]
          - `column` string, required
          - `meaning` 'full_name' | 'last_name' | 'first_name' | 'email' | 'division' | 'group_name' | 'teacher_for_subject' | 'subject_flag' | 'option_codes' | 'population_flag' | 'teacher_full_name' | 'teacher_last_name' | 'teacher_first_name' | 'teacher_email' | 'teacher_subjects' | 'teacher_divisions' | 'ignored', required
          - `subject` 'maths' | 'physique-chimie' | 'maths-complementaires' | 'maths-expertes', nullable
        - `group_name_from` CellSource — Where a value that is not in a column comes from: the sheet's name (a group per tab) or one cell (a title, a `Classe :` form field).
          - `kind` 'sheet_name' | 'cell', required
          - `cell` string, nullable
        - `division_from` CellSource — Where a value that is not in a column comes from: the sheet's name (a group per tab) or one cell (a title, a `Classe :` form field).
          - `kind` 'sheet_name' | 'cell', required
          - `cell` string, nullable
        - `teacher_from` CellSource — Where a value that is not in a column comes from: the sheet's name (a group per tab) or one cell (a title, a `Classe :` form field).
          - `kind` 'sheet_name' | 'cell', required
          - `cell` string, nullable
        - `teacher_subject` 'maths' | 'physique-chimie' | 'maths-complementaires' | 'maths-expertes', nullable
        - `region_subject` 'maths' | 'physique-chimie' | 'maths-complementaires' | 'maths-expertes', nullable
        - `level` 'sixieme' | 'cinquieme' | 'quatrieme' | 'troisieme' | 'seconde' | 'premiere' | 'terminale' | 'prepa', nullable
      - `population_filter` PopulationFilter — Only the rows with one of `values` in `column` enter the plan: "only the students with 1 in column Z" (the school's paid seats).
        - `column` string, required
        - `values` string[], required
      - `option_codes` object
      - `summary` string
      - `origin` 'model' | 'admin' | 'default'
    - `summary` string
  - `students` PlanStudent[], required
    - `id` string, required
    - `last_name` string, required
    - `first_name` string, required
    - `email` string, nullable
    - `division` string, nullable
    - `level` 'sixieme' | 'cinquieme' | 'quatrieme' | 'troisieme' | 'seconde' | 'premiere' | 'terminale' | 'prepa', nullable
    - `group_name` string, nullable
    - `subjects` string[]
    - `teachers_by_subject` object
    - `in_population` boolean
    - `name_ambiguous` boolean
    - `subject_info` boolean
    - `source` SourceRef, required
      - `source_id` string, required
      - `file_name` string, required
      - `sheet` string, required
      - `row` integer, required
    - `raw` string
    - `origin` 'file' | 'admin' | 'school_answer'
    - `edited` boolean
  - `filtered_out_count` integer, required
  - `teachers` PlanTeacher[], required
    - `id` string, required
    - `last_name` string, required
    - `first_name` string
    - `email_in_file` string, nullable
    - `subjects` string[]
    - `divisions` string[]
    - `names_in_file` string[]
    - `origin` 'file' | 'admin'
    - `status` 'account' | 'invitation' | 'to_invite' | 'ambiguous' | 'not_found' | 'out_of_scope'
    - `chosen` TeacherCandidate
      - `id` string, required
      - `kind` 'account' | 'invitation', required
      - `first_name` string, nullable
      - `last_name` string, nullable
      - `email` string
      - `in_school` boolean
      - `reason` string
    - `candidates` TeacherCandidate[]
      - `id` string, required
      - `kind` 'account' | 'invitation', required
      - `first_name` string, nullable
      - `last_name` string, nullable
      - `email` string
      - `in_school` boolean
      - `reason` string
    - `reason` string
    - `invite_email` string, nullable
    - `locked` boolean
  - `groups` PlanGroup[], required
    - `id` string, required
    - `name` string, required
    - `subject` 'maths' | 'physique-chimie' | 'maths-complementaires' | 'maths-expertes', required
    - `grade` 'sixieme' | 'cinquieme' | 'quatrieme' | 'troisieme' | 'seconde' | 'premiere' | 'terminale' | 'prepa', nullable
    - `teacher_ids` string[]
    - `candidate_teacher_ids` string[]
    - `student_ids` string[]
    - `divisions` string[]
    - `origin` 'file' | 'school_answer' | 'admin'
    - `rule` string, nullable
    - `rule_key` string, nullable
    - `readiness` 'ready' | 'probable' | 'waiting' | 'excluded', nullable
    - `status` 'up_to_date' | 'to_create' | 'to_complete' | 'to_confirm' | 'waiting_school' | 'excluded'
    - `reason` string
    - `hint` string, nullable
    - `links` ClassLink[]
      - `class_id` string, required
      - `class_name` string, required
      - `class_code` string, nullable
      - `teacher_ref` string, required
      - `teacher_kind` 'account' | 'invitation'
      - `matched` integer
      - `group_size` integer
      - `by` 'overlap' | 'admin'
    - `applied` AppliedClass[]
      - `teacher_id` string, required
      - `class_id` string, nullable
      - `class_code` string, nullable
      - `class_name` string, nullable
      - `pending_class_id` string, nullable
      - `created` boolean
      - `completed` boolean
      - `students_added` integer
      - `students_skipped` integer
      - `invitations_sent` integer
      - `student_ids_sent` string[]
      - `skipped_reason` string, nullable
      - `error` string, nullable
      - `at` string, date-time, nullable
    - `name_edited` boolean
    - `students_edited` boolean
    - `teachers_edited` boolean
    - `status_locked` boolean
  - `questions` PlanQuestion[], required
    - `id` string, required
    - `text` string, required
    - `detail` string
    - `category` 'groups' | 'teachers' | 'students' | 'file'
    - `group_ids` string[]
    - `teacher_ids` string[]
    - `student_ids` string[]
    - `status` 'open' | 'closed'
    - `answer` string, nullable
    - `origin` 'rule' | 'admin' | 'assistant' | 'mcp'
    - `rule_key` string, nullable
    - `closed_at` string, date-time, nullable
    - `closed_by` PlanAuthor — Who did something: an admin, the page assistant or Claude through the MCP (both acting for an admin), the model reading a file, the system.
      - `kind` 'admin' | 'assistant' | 'mcp' | 'system' | 'model', required
      - `email` string, nullable
      - `name` string, nullable
    - `sent_at` string, date-time, nullable
  - `notes` string[], required
  - `school_contact_name` string, nullable
  - `school_contact_email` string, nullable
  - `message_subject` string, required
  - `message_body` string, required
  - `message_sent_at` string, date-time, nullable
  - `message_sent_by` PlanAuthor — Who did something: an admin, the page assistant or Claude through the MCP (both acting for an admin), the model reading a file, the system.
    - `kind` 'admin' | 'assistant' | 'mcp' | 'system' | 'model', required
    - `email` string, nullable
    - `name` string, nullable
  - `history` HistoryEntry[], required
    - `revision` integer, required
    - `at` string, date-time, required
    - `kind` string, required
    - `summary` string, required
    - `payload` object
    - `author` PlanAuthor, required — Who did something: an admin, the page assistant or Claude through the MCP (both acting for an admin), the model reading a file, the system.
      - `kind` 'admin' | 'assistant' | 'mcp' | 'system' | 'model', required
      - `email` string, nullable
      - `name` string, nullable
    - `proposed_by` PlanAuthor — Who did something: an admin, the page assistant or Claude through the MCP (both acting for an admin), the model reading a file, the system.
      - `kind` 'admin' | 'assistant' | 'mcp' | 'system' | 'model', required
      - `email` string, nullable
      - `name` string, nullable
    - `proposal_id` string, nullable
    - `touched` string[]
  - `proposals` ProposalResponse[], required
    - `id` string, required
    - `title` string, required
    - `message` string
    - `author` PlanAuthor, required — Who did something: an admin, the page assistant or Claude through the MCP (both acting for an admin), the model reading a file, the system.
      - `kind` 'admin' | 'assistant' | 'mcp' | 'system' | 'model', required
      - `email` string, nullable
      - `name` string, nullable
    - `created_at` string, date-time, required
    - `base_revision` integer, required
    - `items` ProposalItem[]
      - `operation` union, required
        - AddSourceOpOutput
          - `kind` 'add_source'
          - `source` PlanSourceOutput, required
            - `id` string, required
            - `file_name` string, required
            - `kind` 'xlsx' | 'xls' | 'ods' | 'csv' | 'pdf' | 'text', required
            - `size_bytes` integer
            - `added_at` string, date-time, required
            - `added_by` PlanAuthor, required — Who did something: an admin, the page assistant or Claude through the MCP (both acting for an admin), the model reading a file, the system.
              - …
            - `grid` FileGrid, required — One file: its sheets in workbook order (a CSV, a PDF or pasted text is a single sheet). `limits_hit` lists every cap that cut something, so a partial read is never mistaken for the whole file.
              - …
        - RemoveSourceOp
          - `kind` 'remove_source'
          - `source_id` string, required
        - SetSheetMappingOpOutput
          - `kind` 'set_sheet_mapping'
          - `mapping` SheetMappingOutput, required
            - `source_id` string, required
            - `sheet` string, required
            - `ignored` boolean
            - `regions` SheetRegion[]
              - …
            - `population_filter` PopulationFilter — Only the rows with one of `values` in `column` enter the plan: "only the students with 1 in column Z" (the school's paid seats).
              - …
            - `option_codes` object
            - `summary` string
            - `origin` 'model' | 'admin' | 'default'
        - SetMappingSummaryOp
          - `kind` 'set_mapping_summary'
          - `summary` string, required
        - SetColumnMeaningOp
          - `kind` 'set_column_meaning'
          - `source_id` string, required
          - `sheet` string, required
          - `column` string, required
          - `meaning` string, required
          - `subject` 'maths' | 'physique-chimie' | 'maths-complementaires' | 'maths-expertes', nullable
          - `region_index` integer
        - SetPopulationFilterOp
          - `kind` 'set_population_filter'
          - `source_id` string, required
          - `sheet` string, required
          - `column` string, nullable
          - `values` string[]
        - SplitGroupOp
          - `kind` 'split_group'
          - `group_id` string, required
          - `parts` GroupPart[], required
            - `name` string, required
            - `student_ids` string[]
            - `divisions` string[]
            - `teacher_ids` string[]
            - `group_id` string, nullable
          - `origin` 'file' | 'school_answer' | 'admin'
        - MergeGroupsOp
          - `kind` 'merge_groups'
          - `group_ids` string[], required
          - `name` string, nullable
          - `group_id` string, nullable
        - MoveStudentsOp
          - `kind` 'move_students'
          - `student_ids` string[], required
          - `from_group_id` string, nullable
          - `to_group_id` string, required
        - AddGroupOp
          - `kind` 'add_group'
          - `name` string, required
          - `subject` 'maths' | 'physique-chimie' | 'maths-complementaires' | 'maths-expertes', required
          - `grade` 'sixieme' | 'cinquieme' | 'quatrieme' | 'troisieme' | 'seconde' | 'premiere' | 'terminale' | 'prepa', nullable
          - `student_ids` string[]
          - `divisions` string[]
          - `teacher_ids` string[]
          - `group_id` string, nullable
          - `origin` 'file' | 'school_answer' | 'admin'
        - RemoveGroupOp
          - `kind` 'remove_group'
          - `group_id` string, required
        - RenameGroupOp
          - `kind` 'rename_group'
          - `group_id` string, required
          - `name` string, required
        - SetTeachersOp
          - `kind` 'set_teachers'
          - `group_id` string, required
          - `teacher_ids` string[], required
        - SetGroupStatusOp
          - `kind` 'set_group_status'
          - `group_id` string, required
          - `status` 'up_to_date' | 'to_create' | 'to_complete' | 'to_confirm' | 'waiting_school' | 'excluded', nullable
          - `reason` string
        - LinkExistingClassOp
          - `kind` 'link_existing_class'
          - `group_id` string, required
          - `class_id` string, nullable
        - ResolveTeacherOp
          - `kind` 'resolve_teacher'
          - `teacher_id` string, required
          - `status` 'account' | 'invitation' | 'to_invite' | 'ambiguous' | 'not_found' | 'out_of_scope', required
          - `candidate_id` string, nullable
        - InviteTeacherOp
          - `kind` 'invite_teacher'
          - `teacher_id` string, required
          - `email` string, required
        - AddTeacherOp
          - `kind` 'add_teacher'
          - `last_name` string, required
          - `first_name` string
          - `email` string, nullable
          - `subjects` string[]
          - `teacher_id` string, nullable
        - AddQuestionOp
          - `kind` 'add_question'
          - `text` string, required
          - `detail` string
          - `category` 'groups' | 'teachers' | 'students' | 'file'
          - `group_ids` string[]
          - `teacher_ids` string[]
          - `student_ids` string[]
          - `question_id` string, nullable
        - CloseQuestionOp
          - `kind` 'close_question'
          - `question_id` string, required
          - `answer` string
        - AddStudentOp
          - `kind` 'add_student'
          - `last_name` string, required
          - `first_name` string, required
          - `email` string, nullable
          - `division` string, nullable
          - `group_ids` string[]
          - `student_id` string, nullable
        - RemoveStudentOp
          - `kind` 'remove_student'
          - `student_id` string, required
        - EditStudentOp
          - `kind` 'edit_student'
          - `student_id` string, required
          - `first_name` string, nullable
          - `last_name` string, nullable
          - `email` string, nullable
          - `division` string, nullable
        - SetSchoolContactOp
          - `kind` 'set_school_contact'
          - `name` string, nullable
          - `email` string, nullable
        - MarkMessageSentOp
          - `kind` 'mark_message_sent'
        - ApplyGroupsOp
          - `kind` 'apply_groups'
          - `group_ids` string[]
          - `options` ApplyOptions
            - `send_student_invitations` boolean
            - `prepare_invited_teacher_classes` boolean
            - `invite_missing_teachers` boolean
          - `run_id` string, nullable
        - RefreshMatchingOpOutput
          - `kind` 'refresh_matching'
          - `context` SchoolContextOutput, required
            - `school_id` string, required
            - `school_name` string
            - `school_year` string
            - `fetched_at` string, date-time, nullable
            - `teachers` DomainImportPlanMatchingSchoolTeacher[]
              - …
            - `classes` SchoolClass[]
              - …
            - `students` SchoolStudent[]
              - …
            - `outside_teachers` DomainImportPlanMatchingSchoolTeacher[]
              - …
        - RecordGroupAppliedOp
          - `kind` 'record_group_applied'
          - `run_id` string, required
          - `group_id` string, required
          - `results` AppliedClass[], required
            - `teacher_id` string, required
            - `class_id` string, nullable
            - `class_code` string, nullable
            - `class_name` string, nullable
            - `pending_class_id` string, nullable
            - `created` boolean
            - `completed` boolean
            - `students_added` integer
            - `students_skipped` integer
            - `invitations_sent` integer
            - `student_ids_sent` string[]
            - `skipped_reason` string, nullable
            - `error` string, nullable
            - `at` string, date-time, nullable
        - FinishApplyOp
          - `kind` 'finish_apply'
          - `run_id` string, required
          - `error` string, nullable
      - `label` LabelPart[]
        - `kind` 'text' | 'strong' | 'del' | 'ins'
        - `value` string, required
      - `status` 'pending' | 'applied' | 'refused' | 'failed'
      - `error` string, nullable
      - `applied_revision` integer, nullable
    - `status` 'pending' | 'applied' | 'partial' | 'refused'
    - `decided_by` PlanAuthor — Who did something: an admin, the page assistant or Claude through the MCP (both acting for an admin), the model reading a file, the system.
      - `kind` 'admin' | 'assistant' | 'mcp' | 'system' | 'model', required
      - `email` string, nullable
      - `name` string, nullable
    - `decided_at` string, date-time, nullable
    - `notes` string[]
    - `stale` object
  - `apply_run` ApplyRun
    - `id` string, required
    - `status` 'running' | 'done' | 'failed'
    - `group_ids` string[]
    - `done_group_ids` string[]
    - `options` ApplyOptions
      - `send_student_invitations` boolean
      - `prepare_invited_teacher_classes` boolean
      - `invite_missing_teachers` boolean
    - `requested_by` PlanAuthor, required — Who did something: an admin, the page assistant or Claude through the MCP (both acting for an admin), the model reading a file, the system.
      - `kind` 'admin' | 'assistant' | 'mcp' | 'system' | 'model', required
      - `email` string, nullable
      - `name` string, nullable
    - `started_at` string, date-time, required
    - `finished_at` string, date-time, nullable
    - `error` string, nullable
  - `school_fetched_at` string, date-time, nullable
  - `school_classes` SchoolClassOption[], required
    - `id` string, required
    - `name` string, required
    - `code` string, nullable
    - `teacher_id` string, required
    - `teacher_kind` string, required
    - `teacher_name` string
    - `roster_size` integer
  - `school_teachers` SchoolTeacherOption[], required
    - `id` string, required
    - `kind` string, required
    - `name` string, required
    - `email` string, required
    - `in_school` boolean
  - `assistant_messages` AssistantMessage[], required
    - `id` string, required
    - `role` 'user' | 'assistant', required
    - `author` PlanAuthor, required — Who did something: an admin, the page assistant or Claude through the MCP (both acting for an admin), the model reading a file, the system.
      - `kind` 'admin' | 'assistant' | 'mcp' | 'system' | 'model', required
      - `email` string, nullable
      - `name` string, nullable
    - `content` string, required
    - `at` string, date-time, required
    - `proposal_id` string, nullable

## Other responses

- `404` — Resource not found
- `409` — Business rule violated
- `422` — Validation Error

## Changes

> 30 revisions in range; 1 not diffed.

- **2026-10-02** `a0b4ce9a0d8f` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/excellence-ai/apis/excellence-learning/changes/admin/import-plans/:plan_id/apply/post.md)

---

[API](https://skmtc.dev/excellence-ai/apis/excellence-learning.md) · [All operations](https://skmtc.dev/excellence-ai/apis/excellence-learning/llms.txt) · [OpenAPI document](https://skmtc.dev/excellence-ai/apis/excellence-learning/revisions/a0b4ce9a0d8f?raw)