# 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.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.pushpulse.com/users-and-permissions/bulk-user-import.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.