Bulk Import

Bulk Import creates many user accounts in a single operation using a CSV file. It is intended for large account migrations or situations where creating users individually would be slow or error-prone. During the import process you can assign authentication methods, group membership or partner assignments, folder permissions, and SFTP/SSH public keys while creating each user.

Bulk Import is commonly used when migrating accounts from another system or when onboarding many users at once. If your organization uses Single Sign-On with automated provisioning, use SCIM or Just-in-Time provisioning instead so that users are created automatically when they authenticate.

Bulk Import is available only in the web interface. Files.com validates the file and shows warnings and errors before it creates any users.

When to Use Bulk Import

Bulk Import is used when you need to create a large number of accounts at once or migrate users from another platform. It is often used when transferring user accounts from a legacy system while preserving existing credentials.

Alternatives to Bulk Import

When onboarding external organizations or partner companies, consider using Partners instead of importing partner users directly. Partner management allows user lifecycle management to be delegated safely to partner administrators.

When only a small number of users are required or when each user requires significantly different configuration, creating users individually is usually simpler than preparing a CSV file.

CSV File Format

Bulk Import uses a CSV (Comma-Separated Values) file to describe the users that should be created.

In the web interface, you can download the CSV template from the Bulk Create Users page.

Each CSV file contains a single header row followed by one row per user. The header row defines which columns appear in the file. Every data row must follow the same column order as the header.

During import, Files.com analyzes the CSV file before creating any accounts. This validation step ensures the file structure and user records are valid before changes are made to the site.

CSV Requirements

The CSV file must follow these structural requirements.

The first (header) row must contain column names. Every subsequent row must contain user data matching those columns.

Each data row represents a single user account. The column order in each data row must match the order defined in the header row.

Blank rows are ignored during import.

Columns that are left blank or omitted use default values.

The username column must always be present.

Bulk Import reads only supported column names. Columns that are not recognized are ignored and reported during validation.

The Bulk Import feature does not support comment lines (# comment) in your CSV. Do not include comment lines in your CSV.

Password Policy and Imported Hashes

When importing users with the authentication method of password_with_imported_hash, the value in the password column must contain a supported password hash. Imported hashes bypass the site's password policy validation because the plaintext password is not available during migration.

Files.com verifies the hash during the user's first successful login. After verification, the password is converted to Files.com’s internal storage format (PBKDF2).

If the user later changes their password, the new password must satisfy the site's password policy.

Plaintext passwords provided during import must always meet the site's password policy.

Supported CSV Columns

The table below lists the supported columns that may appear in a Bulk Import CSV file. The web interface also displays a listing of Supported Columns, including the allowed values.

SSO Providers Authentication Methods

Assign new users to an SSO Provider that is configured for your site by providing the corresponding authentication_method value. Only SSO Providers that are configured for your site can be used for a new user authentication_method.

Supported SSO Provider Values

Use these values in the authentication_method column. The web interface lists the valid options for the authentication_method, including your active SSO providers, in the Supported Columns listing.

Multiple SSO Providers of the Same Type

Bulk Import matches an SSO provider by the authentication_method value, not by a provider name or display name.

When your site has multiple instances of the same SSO provider enabled with the same authentication_method value, Bulk Import cannot choose a specific provider for a specific user. Bulk Import assigns the user to the first matching provider of the specified type.

To create users assigned to different providers of the same type, create the users without SSO during Bulk Import, then assign each user to the intended SSO provider after the import.

Importing Partner Users

The partner_id column of the CSV allows you to assign the newly created user to a Partner as a partner user. You can enter either the name or the ID of the Partner in the column.

Partner users have unique restrictions that mean the partner_id column is not compatible with some of the other columns in the table, namely group_ids, site_admin, and folder_permissions.

Partner users can never be part of a group, so a record that includes values in the group_ids column and in the partner_id column cannot be imported.

Similarly, Partner users can never be Site Administrators. Site Administrators have unrestricted access to your entire site, and Partner users only have the folder permissions granted to their Partner. Attempting to import a user record that includes a partner_id value and sets the site_admin column to Y will fail.

All folder permissions for Partner users are assigned to the Partner rather than the user, so values in the folder_permissions column are ignored when the partner_id column is used. Unlike the group_ids and site_admin conflicts, which prevent the record from being imported at all, this does not cause an error; the user is created successfully as a Partner user and the folder_permissions value is silently ignored.

Assigning Folder Permissions

Automatically assign folder permissions to users with the folder_permissions column of the import file. Supply a list of folders and permissions, separated by pipe symbols, to be assigned to the user (see example). Folders that don't already exist are automatically created when the user is added.

If you omit the folder_permissions column or leave it blank for a user, Bulk Import creates the user without any user-level folder permissions.

That user can authenticate, but they will not be able to access any folders or files unless at least 1 of the following is true:

• site_admin is Y. Site Administrators have access to every path in the site.
• You are creating a Partner user by filling in the partner_id column. Partner users always have the permissions granted to their Partner, and cannot have folder permissions assigned to the user directly.
• You enabled Automatically Create New User Folders Here When Users Are Created. That setting grants access to the created folder.
• You use Group Level Permissions, and you assign the user to groups with folder access via group_ids.

Possible Permission Values

Use the permission values from the table below to limit what actions the user can take for each folder.

Example Folder Permissions

Sales=readonly|Engineering=readwrite,history|Home/Adam=admin

This defines 3 permissions: Sales=readonly, Engineering=readwrite,history and Home/Adam=admin. The user will be given Read-Only permission on the Sales folder, Read/Write and History permissions on the Engineering folder, and Admin permission on the Home/Adam folder. If any of those folders do not exist, they are created automatically.

Advanced Usage Notes

Use a slash for the folder name to specify the Root Folder, for example: /=readonly.

If a folder name contains a vertical bar, for example Sales|North-America, the vertical bar must be escaped with a preceding backslash: Sales\|North-America=readonly.

When site_admin is enabled for the user, then the value of folder_permissions for that user is ignored, because site administrators have admin access to all folders.

Folder permissions are applied recursively to all sub-folders by default. To limit a permission to the specified folder name and not its sub-folders, add an asterisk * after the permission value. For example, supplying Home=admin* creates a non-recursive folder admin permission for the "Home" folder.

Import Validation

Before creating any users, Files.com validates the uploaded CSV file. This validation checks file structure, required fields, and data integrity.

The validation process reports errors and warnings so that problems can be corrected before the import runs.

Errors prevent user creation.

Warnings indicate issues that may lead to unexpected configuration results.

Only valid user records are imported.

You can only continue the import process when at least 1 valid record can be imported. If there isn't at least 1 record that can import, there's nothing for the import process to do.

The best practice is to address all warnings and errors from the validation step before processing a file so that your import file is directly comparable to the results you obtained. This reduces complexity and makes it easier to follow up on issues with new user accounts.

Common User CSV Validation Errors

The pre-validation step of the import notifies you of problems that prevent importing your records. The most common types of failures are listed below.

Errors in User CSV Structure

Errors related to file structure, column formatting, and other general CSV issues, are listed with the discussion of CSV Import Files.

• Missing Header Row
• Unrecognized Column Names
• Invalid Record Length
• Empty Row Warnings

Username is Required

The username column must be included in your import header row, and it must not be blank in any of your data rows.

When every row of your import file reports the error Username is required. , check that the first row of your import file contains a correct header row. Failing to include the header row means that every record is invalid because no column is identified as containing the username. When you see this error, edit the import file to fix the problem.

When only some of your user records display the Username is required error, look for missing commas or quotes. Edit your input CSV and start the import process again.

Duplicate Usernames

Each username may appear only once in the CSV file. Duplicate usernames cause the affected rows to fail validation.

When a username appears on more than one data row of your import file, the import validation lists each row of your import file that contains the username along with the message Username (USERNAME) occurs more than once. All of the rows with that username are not processed by the import.

To fix the error, edit your CSV to remove duplicate rows before processing it.