Bulk-import users from CSV

CSV import is the fastest way to onboard a team — ten seats, a hundred, whatever the row count. Each row becomes one user with a generated temporary password and password_reset_required=true, so every imported user is forced to set their own password on first login. If SendGrid is configured (D14), every user gets a welcome email with their temporary password; if not, the API returns the passwords inline and you share them manually.

Duplicate detection is by email (case-insensitive). A row whose email already exists in the org is skipped with a duplicate_email error in the import report; nothing is updated. Re-running the import after an edit does not modify existing users.

Caution

The import creates real user accounts with real access the moment it succeeds. Double-check role assignments before you upload — a viewer typo’d as admin gets admin immediately, and revoking mistakenly granted access is a manual cleanup per user.

Procedure

1. Open Admin -> Users from the left nav.
2. Click Bulk import in the page header.

3. Download the CSV template. It has the expected column order and one example row commented out.
4. Fill the CSV. Columns:

Column	Required	Values	Notes
email	yes	valid email	Lowercased on import. Duplicate rows within the same upload are rejected before any user is created.
display_name	yes	1 - 100 chars	What appears in the user list and badges.
role	yes	admin, operator, viewer	Case-insensitive. owner cannot be assigned via import — use Transfer Ownership. platform_admin is a separate tier. See Roles and permissions.
sites	only for viewer	semicolon-separated site names	Viewers only — admins and operators have implicit org-wide access (D78). Ignored for non-viewer rows.

5. Save the file as UTF-8. Excel’s “CSV UTF-8 (comma delimited)” format works.
6. Upload the file via the Bulk import dialog.

7. Review the preview. The dialog shows row-by-row validation: green rows will be created, red rows have errors (bad role name, invalid email, unknown site name, duplicate).
8. Click Import.

9. The result screen shows: count created, count skipped (with reasons), downloadable error CSV for the skipped rows.

Each created user gets an user.created audit log entry. The actor is you; the target_id is the new user’s ID. If SendGrid is configured, welcome emails send asynchronously and you are not blocked on delivery.

Common variations

• Re-run after fixing errors. Download the error CSV, fix the issues, upload only that file. Existing users are skipped with duplicate_email, so you cannot accidentally re-create them.
• Pre-assign site access for viewers. Include site names exactly as they appear on the Sites page (case-sensitive). Multiple sites separated by semicolons. Unknown sites cause the row to fail — create the sites first.
• Dry-run before committing. The preview screen is the dry run. No users are created until you click Import.

If this didn’t work

• Import dialog rejects the file — wrong encoding. Save as UTF-8 CSV, not UTF-16 or Windows-1252.
• All rows fail with invalid_role — role column is administrator instead of admin, or has trailing whitespace. The three valid values are admin, operator, viewer.
• Viewer rows fail with unknown_site — the site name in the sites column does not match any site in the org. Check for typos and create missing sites first.
• Welcome emails do not arrive — SendGrid is not configured. The API response includes the temporary passwords inline; share them out-of-band. See Configure organisation policies for SendGrid setup status.
• Import returns 403 — your role is operator. User CRUD is admin/owner-only per D81. See Roles and permissions.

Related

• Roles and permissions — valid role names and the containment hierarchy
• Audit actions — user.created entries written per imported row
• Configure organisation policies — password policy that applies to every imported user’s first real password