> ## Documentation Index
> Fetch the complete documentation index at: https://help.hflow.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Students (Manual + CSV)

> Add one student manually or import many students from a CSV file.

This feature allows admins to add student records either one-by-one or in bulk via CSV.

> **Demo data notice**
> Any names, student records, IDs, and examples shown in this documentation section are fictitious sample data for demonstration and training purposes only. Any resemblance to real persons, schools, or records is purely coincidental.

## Choose the right path

* Use **manual add** for a few students
* Use **CSV import** for batches and section/class updates

## How to add one student manually

1. Go to **Students** → **View Students**.
2. Click **+ Add Student**.
3. Enter required fields:
   * First name
   * Last name
   * Grade (`0` to `12`, where `0` is Kindergarten)
   * School year
4. Optional fields:
   * Middle name
   * External student ID (up to 20 characters)
   * Class/section (required when sections exist for that grade)
5. Click **Save** (or **Save & Add Another**).

The student appears in the roster for that school year and grade.

## Add Student fields explained

* **First name (required):** Student's given name.
* **Last name (required):** Student's family/surname.
* **Middle name (optional):** Helps distinguish students with similar first/last names.
* **Grade (required):** Numeric grade level (`0` to `12`), where `0` represents Kindergarten.
* **School year (required):** Academic year context for enrollment and reporting.
* **Class (conditional):** Class/section for that grade and year. If no sections exist, student can be enrolled without a class.
* **External student ID (optional, max 20):** Any ID the school wants to use as a cross-reference in another system (for example, the school's main directory or SIS record ID).

## How to add students via CSV

1. Go to **Students** → **View Students**.
2. Click **Import CSV**.
3. Click the **? help icon** in the import header to review exact format and rules.
4. Upload your CSV and confirm row count.
5. Click **Proceed**.
6. Review import results.
7. Download:
   * **Successes** (includes generated `student_code`)
   * **Failures** (includes `failure_reason`)

If the **wrong file** went through or the whole batch must be reversed, **owners** and **admins** can check **Configuration → CSV Imports** for undo. Undo only works when no one has added or changed data tied to that upload (for example new assessments on imported students, or a class change after the file ran). **Teachers** should contact your hFlow owner or admin immediately and avoid editing affected roster rows until they respond. See [CSV imports and undo](/hflow/configuration/csv-imports).

## CSV format rules (quick reference)

Required columns:

* `first_name`
* `last_name`
* `school_year` (format `YYYY-YYYY`, example `2025-2026`)
* `grade` (integer `0` to `12`)

Optional columns:

* `middle_name`
* `class`
* `external_student_id` (max 20 chars, unique in org when present)

Other constraints:

* CSV only
* Maximum 500 rows
* Headers are case-insensitive and normalized

## Common CSV outcomes

* If class is provided and does not exist, class is created automatically
* If student is already enrolled for same year+grade, row updates class assignment
* Two students with the same first and last name in the same school year but **different grades** import as separate records
* When two different students share the same name in the **same grade and year**, use `middle_name` or `external_student_id` to distinguish them
* Duplicate `external_student_id` values are rejected

## Troubleshooting

* **“Missing required columns”**: verify exact required headers
* **“Invalid year format”**: must be `YYYY-YYYY` and second year = first + 1
* **“Invalid grade”**: must be between `0` and `12`
* **Class required error**: choose a class when that grade is sectioned
* **“Multiple students match this name”**: add `external_student_id` or a distinct `middle_name`

For the full first-time import walkthrough. See [Getting started](/hflow/getting-started).