CSV User Import

Overview

Import multiple users to your organization at once using a CSV (Comma-Separated Values) file. This feature allows you to efficiently onboard teams and manage user access at scale.

File Format Requirements

Headers (Required)

Your CSV file must include the following headers in the first row:

first_name,last_name,email,role

Important: The headers are case-sensitive and must match exactly.

Maximum File Size

• Maximum users per file: 1000
• Files with more than 1000 users will be rejected

Encoding

• UTF-8 encoding is required
• Standard CSV format with comma (,) as delimiter

Field Specifications

first_name (Required)

• The user's first name
• Must not be empty
• Type: Text

last_name (Required)

• The user's last name
• Must not be empty
• Type: Text

email (Required)

• The user's email address
• Must be a valid email format (contains @ and domain)
• Must be unique within the CSV file (no duplicates)
• Maximum length: 160 characters
• Type: Email

role (Required)

• The role slug for the user's assigned role
• Must match one of the available role slugs in your organization
• Type: Text (slug)

Available Role Slugs

The following role slugs are allowed for CSV user import:

Role Name	Role Slug	Description
Enterprise Admin	enterprise-admin	Manages their enterprise account
Enterprise Collaborator	enterprise-collaborator	Can view, comment, edit one-pagers they are assigned to
Enterprise Viewer	enterprise-viewer	Can only view the SOPs in a hierarchy they are assigned to

Note:

• Use the exact role slug from the "Role Slug" column in your CSV file

Example CSV File

first_name,last_name,email,role
John,Doe,john.doe@example.com,enterprise-admin
Jane,Smith,jane.smith@example.com,enterprise-collaborator
Bob,Johnson,bob.johnson@example.com,enterprise-viewer
Alice,Williams,alice.williams@example.com,enterprise-admin
Charlie,Brown,charlie.brown@example.com,enterprise-collaborator

Validation Rules

Your CSV file will be validated before any users are created. The following validations are performed:

1. Required Fields: All four fields (first_name, last_name, email, role) must be present and non-empty
2. Email Format: Each email must be properly formatted with an @ sign and domain
3. Email Uniqueness: No duplicate email addresses within the CSV file
4. Role Allowed: Role must be one of the allowed enterprise roles (enterprise-admin, enterprise-collaborator, enterprise-viewer)
5. Role Existence: Each role slug must exist in your organization
6. User Limit: Maximum 1000 users per file

All-or-Nothing Import

• If any row fails validation, no users will be created
• You will receive detailed error messages for each validation failure
• Fix all errors and re-upload the corrected CSV file

Existing Users

• If a user with the same email address already exists in the organization, that row will be skipped
• No updates will be performed on existing users
• The import will complete successfully, reporting the count of users created and users skipped
• This allows you to re-upload a CSV file without worrying about duplicate user errors

Error Handling

If your CSV contains validation errors:

1. The first 15 errors will be displayed on screen
2. If there are more than 15 errors, you can download a full error report as a CSV file
3. The error report includes:
   • Row number where the error occurred
   • Column name that failed validation
   • Error message explaining the issue

User Creation Process

Once your CSV is validated and uploaded successfully:

1. All new users are created in a single transaction (existing users are skipped)
2. Each user is assigned to the specified role
3. Users are created with a secure temporary password
4. Users will need to use the "Forgot Password" feature to set their own password before they can log in

Performance

• Import speed: ~2-3 seconds for 1000 users
• Timeout: Maximum 30 seconds for large files
• The system uses an optimized password hashing strategy to ensure fast imports while maintaining security

Important Notes

• Multiple uploads: You can upload CSV files multiple times - existing users will be skipped automatically
• Random passwords: Users are created with random passwords and must use "Forgot Password" to set their own
• Transaction safety: Either all new users are created successfully, or none are created (atomic operation)
• Role restrictions: Only enterprise roles can be assigned - site-admin role is not permitted

Need Help?

If you encounter issues with your CSV upload:

1. Check that all required fields are present
2. Verify email addresses are valid and unique
3. Confirm role slugs match exactly (case-sensitive)
4. Ensure you haven't exceeded the 1000 user limit
5. Download the error report for detailed information about validation failures