Import Students from CSV

Purpose#

Create or match many student records from one CSV file, add program assignments, import custom-field values, and automatically assign grade-based programs where configured.

Permissions#

• Organization admins can import into any active program in the organization.
• Editors can open the import and import into programs where they have editor access.
• Volunteers cannot use Import students.
• An active 14-day trial or paid subscription is required.

Prerequisites#

• At least one active program must exist. Without one, Import students is disabled.
• Prepare a CSV file no larger than 1 MB. Files with a .csv name and common CSV MIME types are accepted.
• Include a header row and at least one nonblank student row.
• Every student row must contain first name, last name, and birthday values.
• Include every required custom field that applies to the programs each student will receive.
• Decide whether every imported student should also be assigned to one or more programs selected in the form.

Recommended Steps#

1. Open Students from the main navigation.
2. Select Import students.
3. Select Download CSV template. This creates student-import-template.csv with the standard headers and the currently required custom-field headers available to you.
4. Open the template in a spreadsheet or text editor without changing the required custom-field identifiers in its headers.
5. Add one student per row. Complete at least firstName, lastName, and birthday for every row.
6. Save or export the file as CSV. Keep it at or below 1 MB.
7. Return to Import students and choose the file under Student roster CSV.
8. Under Also assign every imported student to these programs, select any programs that every row should receive. This selection may be left empty only when every row has a grade that matches at least one eligible grade-based program.
9. Select Import students and wait for the operation to finish. Do not close the drawer while Importing... is shown.

Required Columns and Accepted Headers#

Header matching ignores capitalization, spaces, punctuation, and a leading byte-order mark. For example, firstName, First Name, and first-name normalize to the same header.

Birthday values must use YYYY-MM-DD or MM/DD/YYYY and must be real calendar dates. Grade values should be K, KG, kindergarten, or a whole-number grade from 0 through 20. Email values, when present, must be valid email addresses.

The downloaded template uses these standard headers:

firstName,lastName,birthday,gender,phoneNumber,email,school,grade,photoUrl

Program Assignment#

• Programs selected under Also assign every imported student to these programs are added to every consolidated student in the file.
• The importer also checks active programs with automatic grade transitions enabled where you have edit access.
• If a row has a grade within an eligible program's minimum and maximum grade range, that program is added automatically.
• Selected programs and matching grade-based programs are combined without duplicates.
• Every row must end with at least one program. If a row has no selected program and does not match a grade-based program, the entire import is rejected with its line number.
• Importing only adds missing program assignments to a matched student. It does not remove existing program assignments.
• A program selected in the form is recorded as a manual assignment. A program added from the grade range is recorded as a grade-automation assignment, unless that same program was also selected manually.

Matching and Duplicate Rows#

• A row matches an existing student only when first name, last name, and birthday all match within the same organization.
• Name matching ignores capitalization, leading and trailing spaces, repeated internal spaces, and compatible Unicode formatting differences.
• Birthday matching uses the calendar date.
• When more than one existing record has the same identity, the importer prefers an active student with ACTIVE status, then another active match, then an inactive match.
• A matched student is reused rather than duplicated.
• If the match is inactive, alumni, or both, import changes it to active with ACTIVE status. Existing program assignments and the existing photo are retained.
• Import does not replace a matched student's name, birthday, gender, phone number, email, school, grade, photo, or notes from the CSV. It adds missing program assignments and saves nonblank imported custom-field values.
• Repeated CSV rows with the same normalized name and birthday are consolidated into one import result. The first row supplies the standard profile values; program assignments and non-conflicting custom-field values are combined.
• If repeated rows provide different nonblank values for the same custom field, the entire import is rejected and the error identifies both lines.

Custom Fields#

The template includes active required custom fields using a header such as:

Emergency contact (customField_field-id-here)

The customField_... identifier is what links the column to the configured field. Keep it unchanged. Text before the identifier is for readability and may vary.

• Organization-wide required fields apply to every imported student.
• Program-specific required fields apply when that program is assigned by the form or by grade automation.
• A blank custom-field cell is ignored. For a matched student, a blank cell does not erase an existing value.
• A nonblank custom-field value on a matched student creates or replaces that field's existing value.
• Invalid values and missing required values reject the entire import with a line-specific message.

Atomic, All-or-Nothing Behavior#

The import is atomic. The app validates all rows and program plans before writing records, then performs all creates, matches, reactivations, assignments, and custom-field updates in one database transaction.

If any row fails validation or any operation fails, none of the file's changes are kept. No students from that attempt are created, reactivated, assigned, or updated. Correct the reported line or configuration and import the whole file again.

Concurrent imports of the same student are serialized so one request creates the record and the other matches it instead of creating two records.

Expected Result#

The drawer closes and a message such as Student import complete: 12 created, 3 matched, 1 reactivated, 2 duplicate CSV rows consolidated. appears. Imported or matched students are added to the current Students list, and the overview counts refresh.

New records receive the note Imported student. A blank or missing photo URL gives a new student the standard placeholder. A supplied photoUrl is stored as a URL reference; the importer does not upload or copy that image into managed photo storage.

Troubleshooting and Important Notes#

• Choose a CSV file to import means no nonempty file was selected under Student roster CSV.
• CSV file has no student rows means the file has no nonblank data rows after the header.
• A message beginning with a line number identifies the CSV row to correct. The header is line 1, so the first student is line 2.
• If the upload is rejected before row validation, confirm that the file is CSV and no larger than 1 MB.
• If access is denied for a selected program, select only programs where you have editor access or ask an organization admin to run the import.
• Extra columns are ignored unless their normalized header is a supported standard header or ends with a valid customField_... identifier.
• Empty rows are ignored. Values containing commas should be enclosed in double quotes by your spreadsheet or CSV editor.
• Because matching can reactivate an alumnus or deleted student, review the matched and reactivated counts in the completion message.