Bulk import students (CSV)

This guide covers the complete CSV import workflow for adding multiple students simultaneously. The import drawer validates data in real-time, shows previews with error details, and provides clear feedback on import results.

What this guide covers

• CSV file requirements and format specifications
• Complete field reference (required and optional)
• Data validation rules and accepted values
• Import preview and error resolution
• Processing and verifying imported records

---

Before you start

Required setup

Requirement	Location	Purpose
Academic year	Foundation → Academic Years	Year for enrollment
Grade levels	Foundation → Grade Levels	Target grade levels
Class divisions	Foundation → Class Divisions	Classes for assignment

Required permissions

Permission	Description
students.create	Create student records
students.bulk_import	Perform bulk import operations

File requirements

Requirement	Specification
File format	CSV (.csv extension)
File size	Maximum 10 MB
Encoding	UTF-8 recommended
Line endings	Windows (CRLF) or Unix (LF)

Excel files not supported

The importer only accepts .csv files. If using Excel, export to CSV format first: File → Save As → CSV (Comma delimited)

---

Navigation path

People → Students → Import (button)

Direct URL pattern: /{tenant}/workspace/people/students then click Import

---

Required fields

These columns must be present and contain valid data for every row:

Column name	Description	Validation
student_number	Unique student identifier	Required, must be unique
first_name	Student's first name	Required, non-empty
last_name	Student's last name	Required, non-empty
gender	Gender	Required: male, female, other, prefer_not_to_say
date_of_birth	Date of birth	Required, format: YYYY-MM-DD
nationality	Country of citizenship	Required, non-empty
enrollment_date	Date of enrollment	Required, format: YYYY-MM-DD
student_type	Student classification	Required: regular, transfer, repeating, special_needs
boarding_status	Day or boarding	Required: day, boarding, half_boarding
language_of_instruction	Primary language	Required: english, shona, ndebele

---

Optional fields

Personal information

Column name	Description	Notes
middle_name	Middle name
preferred_name	Preferred/nickname
admission_number	Admission reference	School-specific format
national_id	National ID number
birth_certificate_number	Birth certificate ref
passport_number	Passport number
place_of_birth	Birthplace
citizenship_status	Citizenship category

Contact information

Column name	Description	Notes
email	Student email	Valid email format
phone	Student phone
alternative_phone	Secondary phone
residential_address	Home address

Academic information

Column name	Description	Notes
current_grade_level_id	Grade level UUID	Must match existing grade
current_class_id	Class division UUID	Must match existing class
academic_year_id	Academic year UUID	Must match existing year
house	School house
dormitory	Dormitory assignment	For boarding students
bed_number	Bed number	For boarding students
stream	Academic stream	e.g., Sciences, Arts, Commercial
specialization	Specialization area

Previous school

Column name	Description	Notes
previous_school	Name of previous school
previous_grade_level	Last grade completed
transfer_date	Date of transfer	Format: YYYY-MM-DD
transfer_reason	Reason for transfer

Guardian information

Column name	Description	Notes
primary_guardian_id	Guardian UUID	Must match existing guardian
emergency_contact_name	Emergency contact
emergency_contact_phone	Emergency phone
emergency_contact_relationship	Relationship
guardian_relationship	Primary guardian relation
lives_with_guardian	Living arrangement	true/false or yes/no

Scholarship information

Column name	Description	Notes
is_scholarship_student	Has scholarship	true/false or yes/no
scholarship_type	Type of scholarship
scholarship_provider	Scholarship provider
scholarship_amount	Scholarship value	Numeric

Special needs

Column name	Description	Notes
is_special_needs	Has special needs	true/false or yes/no
special_needs_category	Category of needs
special_needs_details	Detailed description
requires_accommodation	Needs accommodation	true/false or yes/no
accommodation_details	Accommodation specifics

Health information

Column name	Description	Notes
blood_type	Blood type	e.g., A+, O-, B+
requires_medication_at_school	Takes medication	true/false or yes/no
immunization_up_to_date	Vaccinations current	true/false or yes/no
last_medical_checkup	Last checkup date	Format: YYYY-MM-DD

Transport

Column name	Description	Notes
requires_transport	Uses school transport	true/false or yes/no
transport_route	Transport route
transport_pickup_point	Pickup location
transport_dropoff_point	Dropoff location

Financial

Column name	Description	Notes
fee_payment_plan	Payment plan type
fee_category	Fee category
payment_responsibility	Who pays fees
sponsor_organization	Sponsor name
outstanding_balance	Balance owed	Numeric

System

Column name	Description	Notes
portal_access_enabled	Portal access	true/false or yes/no
tags	Labels/categories	Comma-separated
notes	General notes

---

Validation rules

Date formats

Dates must be in YYYY-MM-DD format:

Valid	Invalid
2010-05-15	15/05/2010
2023-01-01	01-01-2023
2015-12-25	25 Dec 2015

Gender values

Case-insensitive, must be one of:

• male
• female
• other
• prefer_not_to_say

Student type values

Must be one of:

Value	Description
regular	Standard enrollment
transfer	Transferring from another school
repeating	Repeating a grade
special_needs	Has special educational needs

Boarding status values

Must be one of:

Value	Description
day	Day scholar
boarding	Full boarding student
half_boarding	Partial boarding

Language values

Must be one of:

• english
• shona
• ndebele

Boolean values

Accept either format:

True values	False values
true	false
yes	no
1	0

Email validation

Must be valid email format if provided:

• Contains @ symbol
• Has domain portion
• No spaces

---

Step-by-step import process

Step 1: Prepare your CSV file

1. Create a spreadsheet with required columns
2. Add student data row by row
3. Verify all required fields have values
4. Check date formats are YYYY-MM-DD
5. Ensure gender/type/boarding values match exactly
6. Save as CSV (not Excel format)

Example CSV structure:

student_number,first_name,last_name,gender,date_of_birth,nationality,enrollment_date,student_type,boarding_status,language_of_instruction,middle_name,email
STU-2024-001,Tendai,Moyo,male,2010-05-15,Zimbabwean,2024-01-15,regular,day,english,James,tendai.moyo@email.com
STU-2024-002,Rudo,Ncube,female,2009-08-22,Zimbabwean,2024-01-15,transfer,boarding,shona,,rudo.n@email.com
STU-2024-003,Tinashe,Sibanda,male,2010-02-10,Zimbabwean,2024-01-15,regular,half_boarding,ndebele,Peter,

Step 2: Upload the file

1. Navigate to People → Students
2. Click the Import button
3. Click Choose file or drag and drop
4. Select your CSV file

The system validates:

• File type (must be .csv)
• File size (must be ≤ 10 MB)
• Header row (checks for required columns)

Step 3: Review the preview

After upload, the system parses and validates all rows:

Valid rows

Valid rows display with:

• ✅ Green check icon
• Student name and number
• Key attributes preview

Invalid rows

Invalid rows display with:

• ⚠️ Red alert icon
• Student name (if available)
• Specific error messages per field

Common errors:

• "Student number is required"
• "Invalid gender value"
• "Date of birth is required"
• "Invalid student type"

Step 4: Fix validation errors

If rows have errors:

1. Note the specific error messages
2. Open your CSV file in spreadsheet software
3. Correct the invalid data
4. Save the file
5. Re-upload the corrected file

Preview limit

The preview shows the first 10 rows. If your file has more rows, verify the pattern is consistent throughout.

Step 5: Run the import

Once validation passes:

1. Review the summary:
   • Total rows to import
   • Valid rows count
   • Invalid rows count (will be skipped)
2. Click Create X students
3. Wait for processing to complete

Step 6: Verify imported records

After import:

1. Navigate to People → Students
2. Search for imported students
3. Verify data accuracy
4. Check class assignments (if IDs were provided)

---

Sample CSV template

Minimum required columns:

student_number,first_name,last_name,gender,date_of_birth,nationality,enrollment_date,student_type,boarding_status,language_of_instruction
STU-001,John,Smith,male,2010-03-15,Zimbabwean,2024-01-10,regular,day,english
STU-002,Mary,Jones,female,2009-07-22,Zimbabwean,2024-01-10,regular,boarding,shona

Extended template with common optional fields:

student_number,first_name,middle_name,last_name,gender,date_of_birth,nationality,enrollment_date,student_type,boarding_status,language_of_instruction,email,phone,residential_address,previous_school,house,stream,notes
STU-001,John,Peter,Smith,male,2010-03-15,Zimbabwean,2024-01-10,regular,day,english,john.smith@email.com,+263771234567,123 Main St,Previous School Name,Lions,Sciences,New transfer student

---

Error reference

File-level errors

Error	Cause	Solution
"Only CSV files are supported"	Wrong file format	Export as CSV from Excel
"File must be 10MB or smaller"	File too large	Split into smaller files
"Missing required columns"	Headers incorrect	Check column names match exactly

Row-level errors

Error	Cause	Solution
"Student number is required"	Empty student_number	Add unique identifier
"First name is required"	Empty first_name	Add student's first name
"Last name is required"	Empty last_name	Add student's last name
"Invalid gender value"	Wrong gender format	Use: male, female, other, prefer_not_to_say
"Date of birth is required"	Empty date_of_birth	Add date in YYYY-MM-DD format
"Nationality is required"	Empty nationality	Add nationality
"Enrollment date is required"	Empty enrollment_date	Add date in YYYY-MM-DD format
"Invalid student type"	Wrong student_type	Use: regular, transfer, repeating, special_needs
"Invalid boarding status"	Wrong boarding_status	Use: day, boarding, half_boarding
"Invalid language"	Wrong language	Use: english, shona, ndebele

---

Best practices

Before import

• Backup existing data before large imports
• Test with a small sample first (5-10 rows)
• Verify column names match exactly (case-sensitive)
• Check for duplicate student numbers
• Confirm grade level and class IDs exist in the system

During import

• Review all validation errors
• Don't skip the preview step
• Note any skipped rows for manual entry later

After import

• Verify total imported matches expected
• Spot-check several records for accuracy
• Assign classes if not done during import
• Update any missing optional information

---

Common issues

Excel formatting issues

Problem: Dates appear as numbers or wrong format

Solution:

1. Select date column
2. Format cells as Text before entering dates
3. Or use Excel's TEXT function: =TEXT(A1,"YYYY-MM-DD")

Encoding issues

Problem: Special characters appear corrupted

Solution: Save CSV with UTF-8 encoding:

• Excel: Save As → CSV UTF-8 (Comma delimited)
• Google Sheets: File → Download → CSV

Duplicate student numbers

Problem: Import fails due to duplicate identifiers

Solution:

1. Ensure each student_number is unique
2. Check existing students don't have same numbers
3. Use a consistent numbering scheme

Empty columns showing as errors

Problem: Optional columns flagged as errors

Solution: Optional columns should be empty, not contain "N/A" or similar. Leave the cell completely empty.

---

Outcome

After successful import:

• ✅ Student records created in the system
• ✅ Data validated against business rules
• ✅ Students linked to specified grade levels/classes (if IDs provided)
• ✅ Import results available for review
• ✅ Students ready for academic operations

---

Related guides

• Add first student — Manual student registration
• Admit a student — Full admissions workflow
• Initial setup checklist — Prerequisites for student enrollment
• Fee setup and invoicing — Billing imported students