Import Students
The student import tool lets you create or update many student records at once by uploading a CSV file. The import runs a two-phase process: a preview that shows exactly what will happen for each row before any data is changed, and an execute step that applies the changes. You can roll back an import run at any time if something went wrong.
Before You Import
To import students you need the student.create, student.edit, or
student.manage permission. To change student statuses through the import you additionally
need student.status.change. The import will skip any row that requires a permission you
do not hold.
Before importing, make sure the programs, intakes, and curricula referenced in your file have been created in the Academic module. The import resolves these by code — a row with an unresolvable program code or curriculum version will be flagged as an error in the preview.
Note: The import respects your organisation's student limit. If the number of new students in the file would exceed the plan limit, the import preview will flag those rows as errors and they will not be created.
Prepare Your File
The import file must be a CSV with a header row. You can download the official import template from Students → Import → Download Template. The template includes all supported columns with example values.
For update imports — where you are modifying existing students rather than creating new ones — use the update template, which is available from the same screen. The update template requires either a Student Number or a Primary Email in every row so the system can match each row to an existing record.
General file rules:
- The file must have a header row. Column order does not matter.
- The file must contain at least one data row.
- Column headers are matched case-insensitively and common aliases are recognised automatically (e.g. "email" maps to Primary Email, "surname" maps to Last Name).
- Empty cells are treated as absent — the field will not be set for that row.
- All text values are trimmed of leading and trailing whitespace before processing.
Column Reference
The table below lists every supported column. Required columns must be present for create rows; for update rows only the match key columns are required, and all other fields are optional.
| Column | Required for create | Notes |
|---|---|---|
| Student Number | No | Used as the primary match key when updating existing students. If automatic numbering is active, leave blank for new students. Example: STU-26-0001. |
| First Name | Yes | Aliases: given name, firstname. |
| Middle Name | No | |
| Last Name | Yes | Aliases: surname, lastname. |
| Title | No | Accepted values: Mr, Mrs, Ms, Miss, Dr, Rev, Prof, Other. |
| Preferred Name | No | |
| Date Of Birth | No | Aliases: dob, birth date. Must be in YYYY-MM-DD format. Example: 2004-01-25. |
| Gender | No | Free-text field. |
| Nationality Code | No | ISO 3166-1 alpha-2 country code. Aliases: country code. Example: LK. |
| Primary Email | No | Alias: email. Used as a fallback match key when no student number is provided. Must be unique across all students. |
| Primary Phone | No | Aliases: phone, mobile. Include the international dialling prefix. Example: +94771234567. |
| Status | Yes | Must be one of: draft, active, suspended, left, alumni. Changing status through import requires the student.status.change permission. |
| Status Reason | No | Free-text explanation of the current status. |
| Residency Status | No | Must be local or international. If not provided for a new student, the system attempts to infer it from the nationality code. |
| Program Code | No | Aliases: program. The code of an existing program. Example: BSC-CS. |
| Curriculum Version | No | Aliases: curriculum. The version string of a curriculum belonging to the program. Requires Program Code to be present. Example: 2026.1. |
| Intake Code | No | Aliases: intake. The code of an existing intake. If the code matches more than one intake, you must also provide Intake Name and Intake Start Date to disambiguate. Example: 2026-JAN. |
| Intake Name | No | Used with Intake Code when the code is ambiguous. Example: January 2026. |
| Intake Start Date | No | Used with Intake Code when the code is ambiguous. Must be in YYYY-MM-DD format. Example: 2026-01-15. |
Run the Import
- Go to Students in the main navigation.
- Click Import.
- Click Upload File and select your CSV.
- The system reads the headers and automatically suggests a column mapping. Review the mapping — each column in your file should be mapped to the corresponding field. Unmapped columns are ignored.
- Click Preview Import.
- The preview shows every row with its proposed action (Create, Update, or Skip), any validation errors, and any warnings. Rows with errors will not be processed.
- Review the preview carefully. If there are errors, correct them in the original file and re-upload.
- When you are satisfied, click Execute Import to apply all valid rows.
Note: Rows marked Skip in the preview were matched to an existing student but no field changes were detected. These rows are not updated and do not count against any limit.
Pro Tip: After the import completes, the system generates a result CSV you can download. It contains the student number, primary email, and primary phone for every student that was created or updated — useful for sharing with enrolment teams or for a follow-up upload to another system.
How Students Are Matched
When a row in the import file could refer to an existing student, the system uses the following match strategy to decide whether to create a new record or update an existing one:
- If a Student Number is provided, the system looks for a student with that exact number. If found, the row updates that student.
- If no student number is provided but a Primary Email is present, the system looks for a student with that email. If exactly one match is found, the row updates that student. If more than one student shares the email, the row is flagged as an error.
- If neither a student number nor an email is provided, the row is treated as a new student and a create action is proposed.
Important: If the student number and primary email in a row each resolve to different existing students, the row is flagged as an error and will not be processed. Correct the file before re-running the import.
Roll Back an Import
Each import run is recorded and can be rolled back if you discover a problem after execution. Rolling back reverses the changes: students created by the import are deleted, and students updated by the import are restored to the values they held before the import ran.
- Go to Students → Import History.
- Find the import run you want to reverse.
- Click Roll Back.
- Confirm the rollback when prompted.
Important: Rollback only reverses changes made by the import. Any manual edits made to a student after the import ran will be overwritten by the rollback. Review the affected students after the rollback completes to confirm their data is correct.
Next: Export Students