Realsmart Help

All guides / Data

Import users and cohorts

4 steps 9 min Updated 4 November 2026

Use the Import page to create or update users and group memberships in bulk. The import is a guided wizard that validates everything before anything is queued, so problems are caught while you can still fix them. This is the fastest way to onboard a large number of users at the start of term or to set up cohorts from an MIS export.

This page — the sidebar calls it Advanced user import — sits alongside two other, simpler imports under the same Import group: Password import (set passwords for existing users from a CSV) and Cohort import (add existing users to groups from a CSV). If all you need is one of those, use the simpler page — it's less to fill in.

Before you start

  • You must be an admin with the Import data permission for the school you are importing into.
  • Select the school first. The import always runs against the school you are currently in — switch to it using the school switcher before you start. (You can't import while viewing all schools in MAT mode.)
  • Prepare your data with the correct column headers — see the format below. You can either upload a CSV (.csv or .txt, up to 8 MB) or paste rows copied from a spreadsheet. The wizard reads the first 5,000 rows, so split a bigger file and import it in parts.

CSV format

The import understands the following columns. Only type, username, forename and surname are required; everything else is optional. Column names are matched flexibly (for example first_name, email and role are recognised as forename, upn and type), and any columns it doesn't recognise can be mapped by hand in the wizard.

Column Required Description
type Yes Role: admin, mentor, learner, observer or governor (any capitalisation)
username Yes Unique login username for this school (letters, numbers and . _ - @)
forename Yes User's first name — letters, spaces, apostrophes, hyphens and full stops only
surname Yes User's surname — letters, numbers, spaces, apostrophes, hyphens and full stops only
status No ACTIVE, PROTECTED or LOCKED. Leave it blank for the default (see below)
password No Initial password, at least 8 characters (leave blank for the school's default). If the school uses the DfE cyber security standard password policy, the password must meet it for that user's role — at least 12 characters for staff or 8 for learners, and a staff password found in a known data breach is refused (see Password settings)
misId No Internal identifier from your MIS (numeric)
upn No Email / unique pupil number, as a valid email address. This is how the import recognises a person (see below)
title No Title (e.g. Mr, Mrs)
legal_forename / legal_surname No Legal names where they differ from preferred
year No Year group (numeric)
house No House name
admission_number No Admission number (numeric)
registration No Registration group name
groups No Groups to add the user to, separated by ; or ,. A group that exists but is Protected is made Active by the import

How the import recognises people

Each row is matched to a person by their UPN. If a row has no UPN, the import uses, in order: the UPN of the existing user with that username, then the MIS ID, then the username itself. So a file with just usernames and names still works. Importing it again later updates the same people instead of adding duplicates.

If a username already belongs to someone with a different UPN, that row is flagged. Add their UPN to update them, or change the username.

Status, and schools that sync from their MIS

When a school's users come from its MIS, the nightly MIS sync suspends anyone the MIS doesn't know about. On those schools a new user with a blank status is added as protected, so the MIS sync leaves them alone. This suits office, supply, test and shared accounts. Setting a new user to ACTIVE is flagged as a warning, because the next MIS sync would suspend them. Protected users can't be changed by a later import: edit them on their user page instead.

On other schools, a blank status means ACTIVE.

Groups that don't exist yet are flagged as a warning and created during the import. Download a template CSV from the Import page (Download example CSV) to get started. The Users (CSV) download on the Export page uses the same column names, so it's a handy starting point — but remove suspended users first (SUSPENDED isn't an accepted status), and put each user's groups into the single groups column (the export gives each group its own column).

Files saved as CSV UTF-8 from Excel, or with semicolon or tab separators from a non-UK spreadsheet, are read correctly — as is the same data pasted into the box rather than uploaded.

Steps

Step 1: Provide your data

Open Import in the sidebar (under Data) and choose Advanced user import. The page is headed Import users and shows four steps — Provide data, Map columns, Validate and Done. You have two options:

  • Upload a CSV — select Download example CSV, fill it in, then upload your file with CSV file.
  • Paste data — copy rows (including the header row) from a spreadsheet and paste them into the box, then select Use pasted data.

Step 2: Map your columns

The wizard auto-matches your columns to the provisioning fields (— ignore — leaves a field blank). Check the mapping, correct anything that's wrong, and make sure each required field (marked with *) is mapped. Select Validate & continue. Back returns to step 1.

Import wizard Step 2 column mapping screen with auto matched dropdowns

Step 3: Validate

The wizard checks every row and cell: required values, valid roles and statuses, email/UPN format, numbers, names and password length. It also checks for duplicate usernames, UPNs or MIS IDs in your data, and for usernames that already belong to someone else. These are the same rules provisioning applies, so a row that passes here won't be quietly skipped later.

  • Rows to fix lists each problem by row, field and reason. Fix them in your source data (or remap), then select Re-validate (or Back to mapping to change the mapping).
  • Warnings (such as groups that will be created) must be acknowledged with the checkbox (I understand and want to continue) before you can continue.
  • Good to know explains how rows will be sent, such as users who'll use their username as their UPN, or be added as protected. Nothing to acknowledge.
  • When everything is valid you'll see All N rows are valid and a preview of the first 50 rows, and the import becomes submittable.

Import wizard Step 3 rows to fix validation screen with error rows highlighted

Then choose the import options. Both are off by default:

  • Replace group memberships: each imported user ends up in only the groups in your groups column. Protected memberships stay. Leave it off to add those groups and keep the ones people already have.
  • Suspend users who aren't in this file: only for a file that lists every user at the school. Everyone active who isn't in it is suspended after 24 hours. Schools that sync users from their MIS don't get this option — the page says This school's users come from its MIS, so an import only adds or updates the users in your file. It never suspends anyone.

Step 4: Run the import

Select Import users and confirm Import N rows? The import goes to the front of the provisioning queue, ahead of scheduled syncs, and usually finishes within a minute or two. New and changed accounts then reach Google, Entra and the other platforms in the normal way — see How syncing works.

Result

The page waits for provisioning (Waiting for provisioning to start…, then Importing users…), then says Import complete, Import finished with problems or No users were imported and shows how many users were added, updated, already up to date, left alone because they're protected, or not imported. A Row by row table lists problems first, with provisioning's reason for each row it skipped (the first 500 rows are shown). You can leave the page while it runs; the result is also in Logs (View Logs). Note your reference (e.g. IMP-XXXXXXXX) if you need to ask for help. Import more starts again.

If provisioning hasn't finished after 20 minutes, the page says Still waiting for provisioning. Select Check again to keep waiting.

Troubleshooting

  • "Map a column to the required field…" — one of the required fields (type, username, forename, surname) isn't mapped. Pick the matching column on the mapping step.
  • "Duplicate username/UPN/MIS ID in this import" — two rows share the same value. Each must be unique within a single import.
  • "Must be one of…": the type or status value isn't recognised. Use one of the allowed values listed in the format table.
  • "Only letters, numbers and . _ - @ allowed." — the username has a space or another character the import doesn't accept.
  • "Letters, spaces, apostrophes, hyphens and full stops only." (forename) / "Letters, numbers, spaces, apostrophes, hyphens and full stops only." (surname) — remove the other characters from the name.
  • "Must be a number." — misId, admission_number or year holds something other than digits.
  • "Must be a valid email / UPN." — the upn isn't a valid email address.
  • "At least 8 characters, or leave blank for the school default." — the password is too short. Under the DfE password policy the message names the rule (for example a minimum of 12 characters for staff) and ends Or leave blank for the school default.
  • "Required." — a required column is blank on that row.
  • "Already used by…": that username belongs to someone else at the school. Add their UPN to update them, or pick a different username.
  • Rows marked "Not imported": the reason column says why. Fix those rows and import just them again.
  • "The import didn't run": the page gives the reason — Provisioning is paused for this school (freeze window), so nothing was imported. (see Cloud sync is paused), or Provisioning stopped before finishing the import with the error. In the second case check Logs for what was imported before it stopped.
  • "Fix the highlighted problems before submitting." — the file has rows to fix, or warnings you haven't acknowledged.
  • "Need a header row and at least one data row." — the file or pasted text has fewer than two non-blank lines.
  • Users I imported were suspended the next day: on a school that syncs from its MIS, users set to ACTIVE who aren't in the MIS get suspended. Import them with a blank status (or PROTECTED).
  • Groups will be created — this is a warning, not an error. Acknowledge it to continue, or create the groups first via Groups if you'd rather control their settings.
  • The mapping step shows one column holding the whole row — the file's separator wasn't recognised. Comma, semicolon and tab are all handled, so this points at something more unusual (a pipe, or fixed-width columns); re-save it from your spreadsheet as CSV and upload again.
Data API — connect systems to your school's MIS data Data Classroom parents — guardian provisioning Data Cohort import Data Export data