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, 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 Overview

Bulk Import uses a CSV (Comma-Separated Values) file to describe the users that should be created. CSV files represent tabular data in plain text and can be produced by spreadsheet applications or text editors.

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.

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

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 row must match the order defined in the header row.

Blank rows are ignored during import.

Columns that are omitted or left blank 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.

CSV Header Row

The first row of the CSV must be a header containing the names of the columns included in the CSV. The columns can be included in any order, but the order must be the same for every row of the CSV.

The downloadable template includes a header with all supported column names.

The username column must be included in the header row because it is always required. Other columns become required when their value impacts how the remaining columns are processed.

When a column is omitted, the default value for that column is applied to every imported user. See the table in the Supported CSV Columns section for the default values assigned when a column is not included in the file.

Bulk Import only reads the supported column names. Any unrecognized columns are not processed. Check the import validation warnings to guard against misspelled column names.

CSV Data Rows

Every row after the header row in your CSV import file represents 1 user to add to your site.

Do not include duplicates in your CSV. When the same username appears on multiple rows, each of those rows is treated as an error, and the user is not imported.

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.

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 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 CSV Validation Errors

The error message Your CSV has been examined, but it contains errors as listed below indicates that there are problems with the file you uploaded.

Refer to the following sections for more detail about common types of errors.

Missing Header Row

The CSV file must begin with a header row containing column names. If the header row is missing, every record fails validation.

Unrecognized Column Names

Columns that are not recognized are ignored. This typically indicates a misspelled column name.

When you include a column in your header row that is not one of the supported columns, a warning message Some column headers in this CSV are not recognized. is show. The unexpected columns are listed for your review.

The importer ignores columns it does not recognize so that the import file can be processed even when extra data has been included. A typical reason for this is when your import file begins by manually exporting from an existing system. It is often helpful to include the legacy internal ID number of an exported user to QA the export process.

A typical reason for the unrecognized columns warning is misspelling column names. Any column displayed in the warning message is ignored by the importer. When a column is ignored, the default value for the column is applied to every user.

Applying a default value requires a tedious manual update to fix those columns. For example, if you misspell the restapi_permission column as restapi_permision , all of your newly created users cannot access the web interface, Desktop App, Mobile app until you edit each user to enable their access.

If the list of columns includes one that has been misspelled, edit your CSV to fix the spelling and start the import process again. Re-upload the edited CSV file.

When you see user data listed as the un-recognized column header names, this indicates the first row of the input file does not contain a correct header row. Edit your input CSV to add the missing headers.

Correct the column name and repeat the import process.

Invalid Record Length

Each data row must contain the same number of columns as the header row. Missing commas or missing quotation marks often cause this error.

When 0 valid records are found in your file, make sure your import file starts with the header row. The first row of your import file must always contain the list of columns you are importing, and the username column must be included in the list.

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.

Invalid Record Length

When the number of columns of any data row does not match the number of columns in your header row, the validation shows a message starting with Invalid Record Length: columns length.

The error will indicate which row does not have correct same number of columns. Examine the data row to determine why the number of columns does not match.

When you want to leave column blank for a record, you must still supply the comma , character to indicate the column. If the number of columns found for the row is less than the columns length part of the message, look for missing commas in your CSV file.

When a column value contains a comma, you must enclose that value in quotes. Use either single or double-quotes; the import automatically detects which is used. If the number of columns found for a row is more than the columns length part of the message, look for missing quotes in your CSV file.

Edit your CSV import file to fix the errors before processing.

Empty Row Warnings

The validation step of the import lists the number of blank lines found in the file as Empty Rows. This is not an error, and you can continue the process as long as at least 1 valid record will be imported.

If you did not expect any blank rows, review your CSV file before importing.