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.

Where to find it

Top nav → Admin → Company Users → Import users (CSV). Available to administrators only.

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