Skip to main content

Step 6: Import Students and Families

Before uploading students, review: Username Policy (Detailed)

Goal​

Import students, guardians, families, school-year status, usernames, and custom-field data in one clean bulk upload.

Why this step matters​

  • A good student upload turns setup work into real rosters, family records, billing links, attendance lists, and student access.
  • The template is built from your organization setup, so username policy, custom fields, parent fields, domains, and school years all matter.
  • Clean data here saves hours later. The upload is fast, but it is strict on purpose.

Before you upload​

  1. Confirm your school years are ready.
  2. Confirm student and parent custom fields are final.
  3. Review the student username policy.
  4. Confirm your allowed email domains are configured.
  5. Make sure your staff account has the Upload Students permission.

If any of those settings change, download a fresh template before the next import.

Where to go​

  1. Open Organization Onboarding.
  2. Select Students.
  3. In Student Management, use Upload Students.

The upload flow​

  1. Select the School Year.
  2. Select the Student Status: Enrolled or Waitlist.
  3. Click Download Template.
  4. Fill in the CSV without renaming, deleting, or reordering the header columns.
  5. Upload the completed .csv file.
  6. Review the result message.
  7. If an error file downloads, fix those rows and upload them again.

What the template includes​

The template is generated from your current setup. It is not a generic spreadsheet.

Core student columns:

  • Student First Name and Student Last Name: required.
  • Gender (M/F): use M or F.
  • Grade: use labels such as Pre K, Junior Kindergarten, Senior Kindergarten, Grade 1, Grade 7, or Grade 12. Values like PRE_K and GRADE_1 also work.
  • Student Date of Birth (YYYY-MM-DD): required in year-month-day format, for example 2012-09-04.
  • Student ID (optional): if blank, BassemLabs generates an ID. If you provide one, it must be unique.
  • Student Username (optional): if blank, BassemLabs generates a username from your student username policy.
  • Student Email Domain (optional): if blank, the organization's default domain is used. If provided, it must be one of the organization's allowed domains.
  • Create Directory Account (Yes/No): use Yes when the student should be created in your connected directory provider.

Guardian columns:

  • Guardian 1 Name, Guardian 1 Email, and Guardian 1 Phone Number are the primary family contact details.
  • Guardian phone numbers should include a country code, for example +14165551234.
  • Guardian 2 columns are optional. If you add a second guardian, include at least the guardian name and email.
  • Guardian emails are normalized, so accidental uppercase letters are not a problem. The email still needs to be valid.

Custom fields:

  • Student custom fields appear after the core student columns.
  • Parent custom fields appear under Guardian 1 and Guardian 2.
  • Waitlist templates include waitlist-specific student fields.
  • Enrolled templates include active student fields.
  • Custom-field values are validated using the rules you configured: required fields, dates, checkboxes, select options, phone fields, and regex fields must match their field type.

Username and ID behavior​

  • If Student Username (optional) is blank, the username is generated automatically.
  • If the username policy uses {birth_year}, the student's date of birth must be present and valid.
  • If the username policy uses {enrollment_year}, the selected school year is used during upload.
  • Manual usernames are trimmed, lowercased, checked for allowed characters, and checked for uniqueness.
  • Usernames may contain lowercase letters, numbers, ., _, and -.
  • Usernames can be up to 64 characters.
  • If Student ID (optional) is blank, BassemLabs generates one automatically.
  • If your downloaded template shows more than one Student ID (optional) column, fill the first one and leave the headers exactly as downloaded.

How families are created​

Each row creates or reuses family records using guardian email addresses.

  • If a family already exists with the same guardian email combination, the upload reuses it.
  • If the guardians already exist but the family combination is new, BassemLabs creates the family connection.
  • If the guardians are new, BassemLabs creates guardian records and a family record.
  • Family names are generated from guardian names, such as Sara Ali Family.
  • Bulk upload creates the records; parent invitation emails are handled separately.

If some rows fail​

Uploads can be partially successful. Successful rows are kept, and failed rows are returned in an error CSV.

The error CSV includes:

  • the original row data
  • an Error column with the reason the row failed

You can fix the downloaded error CSV and upload it again. The extra Error column is accepted, so you do not need to remove it.

Common reasons rows fail:

  • The header was changed or the wrong status template was used.
  • A grade, date, gender, email, phone number, domain, username, or custom-field value is invalid.
  • A provided student ID or username is already used.
  • A required student, guardian, or custom-field value is missing.
  • The upload window has expired.

Important notes​

  • Student upload is available during onboarding.
  • After onboarding is completed, bulk upload remains available for 3 days. After that, add students manually.
  • Use the template for the same student status you select during upload.
  • Do not edit the header row, even if a column is not relevant for a specific student.
  • Use one row per student.
  • For a small first run, upload a few rows, review the result, then upload the rest.