# 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
{% stepper %}
{% step %}
### 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.
{% hint style="info" %}
Pro Tip: The system automatically skips completely empty rows, so you don't need to clean up your spreadsheet before uploading.
{% endhint %}
{% endstep %}
{% step %}
### 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!
{% hint style="info" %}
Email Matching: All import behaviors use email addresses to match users. The system will display an info box reminding you to ensure email addresses are accurate and properly formatted.
{% endhint %}
{% endstep %}
{% step %}
### 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.
{% endstep %}
{% step %}
### 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.
{% endstep %}
{% step %}
### 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.
{% endstep %}
{% endstepper %}
***
## 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
1. Use the template: Download the example file and use it as a starting point
2. Clean your data: Remove completely empty rows (though the system will skip them)
3. Verify emails: Double-check all email addresses are valid and formatted correctly
4. Standardize formats: Use consistent formatting for phone numbers
5. Check locations: Ensure location names match exactly with locations in your system
6. 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 0102`
* `5550100103`
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:
1. Location name (case-insensitive)
2. 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
Q: Can I import the same user twice?
A: No. Users are matched by email. The second occurrence will update the first based on your import behavior.
Q: What happens if I import without sending invites?
A: Users are created in the system but won't receive login credentials. You'll need to send invites manually later.
Q: Can I undo an import?
A: No. Imports are permanent. Always review your data carefully before confirming.
Q: How do I update just one field for all users?
A: Include only the Email column (to match users) and the column you want to update. Leave other mappings empty.
Q: Can I import users to specific locations?
A: Yes! Include a Location column in your file and map it to "Primary Location" during the Map step.
Q: What if my file has extra columns I don't need?
A: No problem! Only map the columns you need. Extra columns are ignored.
Q: Can I use this to bulk-delete users?
A: Yes. Choose "Delete Users" behavior and upload a file with just email addresses.