Bulk User Import
Overview
The Bulk User Import feature allows you to add, update, or delete multiple users at once by uploading a CSV or Excel file. This is perfect for onboarding new teams, updating user information in bulk, or managing your user base efficiently.
Quick Start
Navigate to the Users page
Click the Import button in the top right
Follow the 5-step import wizard:
Upload
Options
Map
Validate
Confirm
File Requirements
Supported File Formats
CSV (
.csv)Excel (
.xls,.xlsx)
File Limitations
Maximum file size: 2MB
Maximum rows: 1,000 rows of data (excluding header row)
Empty rows are automatically skipped
Download Example Template
Click "Download Example File" on the Upload step to get a template with the correct column headers.
Step-by-Step Guide
Step 1: Upload Your File
Drag and drop your file into the upload area, or click to browse.
The system will automatically validate:
File size (must be under 2MB)
Row count (must be 1,000 rows or fewer)
File format (CSV, XLS, or XLSX)
You'll see a success message showing how many rows were detected.
The uploaded file appears below the upload area with a remove option.
Step 2: Choose Import Behavior
Select how you want the system to handle your imported data:
Update or Add New Users (Recommended)
Adds new users from your file
Updates information for existing users (matched by email)
Existing users not in your file remain unchanged
Use when: You want to safely add new users or update existing ones without affecting others
Replace All Users ⚠️
Adds new users from your file
Updates existing users (matched by email)
Permanently removes any users not included in your file
Use when: You want your file to be the single source of truth for all users
Warning: This will delete users not in your file!
Delete Users 🚨
Permanently removes users listed in your file (matched by email)
All other users remain unchanged
Use when: You need to remove specific users in bulk
Warning: This action cannot be undone!
Step 3: Map Your Columns
Match the columns from your file to the user fields in the system.
For Update/Replace Imports
Required Fields (marked with *):
First Name *
Last Name *
Email *
Optional Fields:
Phone
Role
Primary Location
Default Values Column:
For Role and Primary Location, you can set default values.
Defaults are used when your file doesn't include data for these fields.
Select from the dropdown in the "Default Value" column.
For Delete Imports
Only Email is required. This is the field used to identify which users to delete.
Smart Features
Auto-Mapping: The system automatically tries to match your column headers to the correct fields. For example: "First Name" → First Name, "Email" → Email, "Location" → Primary Location
Unique Column Selection: Each column from your file can only be mapped once. If you select a column that's already mapped to another field, the previous mapping will automatically clear.
Step 4: Validate Your Data
The system automatically scans your data for issues and displays:
Summary Metrics
✅ Valid Rows: Rows with no issues
❌ Errors: Critical issues that must be fixed
⚠️ Warnings: Non-critical issues (defaults will be applied)
Validation Rules
Errors (Must be Fixed or Skipped)
Empty required fields (First Name, Last Name, Email)
Invalid email format (e.g., missing @, no domain)
Warnings (Won't Block Import)
Invalid phone number format (will be saved as empty)
Unknown role (will use default role)
Location not found in system (will use default location)
Issues Table
View detailed issues in a table format showing:
Row #: The row number in your file
Type: Error or Warning
Field: Which field has the issue
Issue: Description of the problem
Value: The problematic value from your file
Two Ways to Proceed
Option 1: Fix All Errors
Download your file
Correct the errors
Re-upload
The "Next" button will be enabled once all errors are fixed
Option 2: Skip Error Rows
Click "Skip X Error Rows & Continue"
Only valid rows will be imported
Rows with errors will be completely skipped
You'll see a warning on the next step confirming how many rows will be skipped
Important: Warnings don't block import. The system will automatically apply default values where needed.
Step 5: Confirm and Import
Review Your Import
Preview Table:
Shows the first 5 rows of data
Displays how the data will be imported after mapping and defaults are applied
For delete imports: only shows email addresses
Import Options (Update/Replace only)
Send Invite Now
Toggle on/off
When enabled: Users receive an email invitation to set their password
When disabled: Users are created but no invitation is sent
Add Users to Groups (Optional)
Select one or more groups
All imported users will be automatically added to the selected groups
Shows current member count for each group
Final Confirmation
Check the box: "I confirm the data is accurate and authorized for import"
This ensures you've reviewed the data and have authorization to import these users.
Results Screen
After import completes, you'll see:
Summary Cards
✅ Successfully Imported: Count of users added/updated/deleted
❌ Failed: Count of users that couldn't be processed
Detailed Results
A list showing each user with:
✅ Green checkmark for success
❌ Red X for failure
Name and row number
Error message (if failed)
Click "Done" to close the modal and refresh the user list.
Best Practices
Preparing Your File
Use the template: Download the example file and use it as a starting point
Clean your data: Remove completely empty rows (though the system will skip them)
Verify emails: Double-check all email addresses are valid and formatted correctly
Standardize formats: Use consistent formatting for phone numbers
Check locations: Ensure location names match exactly with locations in your system
Validate roles: Use only valid role values:
user,reporter,responder,location-admin,admin
Import Behavior Selection
Regular updates? Use "Update or Add New Users"
Complete refresh? Use "Replace All Users" (but be careful!)
Removing users? Use "Delete Users" (cannot be undone)
Field Mapping Tips
The system auto-maps common column names, but always verify the mappings
Use the preview column to confirm data is mapping correctly
Set appropriate defaults for Role and Location before proceeding
Handling Validation Issues
For Small Numbers of Errors (1-5 rows):
Fix the errors in your file and re-upload
Ensures complete data integrity
For Large Numbers of Errors (many rows):
Use "Skip Error Rows & Continue" to import valid data immediately
Fix error rows separately through the UI later
More efficient for large imports
Phone Number Formats
The system accepts various phone formats and will attempt to standardize them:
555-0100(555) 010-0101+1 555 010 01025550100103
Invalid formats will result in warnings and the phone field will be left empty.
Common Issues and Solutions
"File size exceeds 2MB limit"
Solution: Split your file into smaller batches or remove unnecessary columns.
"File contains more than 1,000 rows"
Solution: Split your import into multiple files of 1,000 rows or fewer.
"Please map all required fields"
Solution: Ensure First Name, Last Name, and Email are all mapped to columns from your file.
"Invalid email format" errors
Solution:
Check for typos in email addresses (missing @, wrong domain, etc.)
Ensure no extra spaces before or after email addresses
Use "Skip Error Rows" if only a few emails are invalid
"Location not found" warnings
Solution:
Verify location names match exactly (case-insensitive)
Let the system use the default location you selected
Or update location names in your file to match existing locations
"Role not valid" warnings
Solution: Valid roles are: user, reporter, responder, location-admin, admin
Fix role values in your file, or
Let the system use your default role
Advanced Tips
Matching Users
Users are matched by email address only
Email matching is case-insensitive
Make sure emails are unique in your file (duplicates may cause issues)
Empty Values vs. Default Values
If a cell is empty in your file, the default value is used
If a cell has an invalid value, the default is also used (with a warning)
To explicitly clear a value, you may need to update the user individually after import
Location Matching
The system matches locations by:
Location name (case-insensitive)
Location ID (if you include it)
Partial Imports
If you're importing 100 users and 5 have errors:
Using "Skip Error Rows": 95 users import immediately
The 5 error rows can be fixed and imported in a second batch
More efficient than fixing everything upfront for large files
Frequently Asked Questions
Last updated