Create or Update Users in Bulk with the User Import Tool

New or existing users can be created or updated at the same time through the User Import Tool. Quickly update employee work email addresses in bulk or create multiple new user accounts after an acquisition. The import process is separated into two separate stages, creating a CSV spreadsheet of user data and uploading your file into the system. 

In this article:
User Import with the ADP Bi-Directional Connector
User Data Available for Bulk Import
Create your CSV File of User Data
Import your User CSV File
Troubleshooting User Import Errors
FAQs

  In order to utilize the User Import Tool, you must have the User Admin permission. Please contact your ClearCompany Administrator if you are unsure of your permission levels.

User Import with the ADP Bi-Directional Connector

If your organization uses the ADP Bi-Directional Connector, ADP is considered your System of Record for user information. You will be unable to update System of Record-controlled user fields (like email address or role) within ClearCompany and manually created users will not be connected to an employee record in ADP.

Therefore, it is recommended that the creation of new users and updates to employee fields controlled by ADP System of Record be conducted within the ADP system. Once these actions are completed within ADP, your Bi-Directional Connector will automatically create or update the corresponding user record within ClearCompany in the next hourly sync. 

Non-System of Record-controlled fields, like usernames or user permissions, can be updated in bulk through the use of the User Import Tool. Each organization can view and customize the set of employee data controlled by ADP through the Connector Configuration settings. Open the menu below to learn more.

ADP Employee Data Sync Configuration

The employee data controlled by ADP is determined by the Connector Configuration settings enabled on your ADP integration.

To review the ADP-managed employee fields, navigate to Tools > Setup > ADP Integration Management and select the Connector Configuration tab. Click the Select Which Employee Data is Synced button. 

Fields that are toggled On are controlled by ADP and are unable to be editd via the User Import tool. Instead, updates must be made to the employee record in ADP.

See below for the full list of available fields, specifically the ADP Clients column, and continue reading for a step-by-step walkthrough of the user import process.

User Data Available for Bulk Import

The following table outlines the user data points that can be included in the user import CSV file which you'll use to create or update users through the User Import Tool.

  Note, the Column Headers in your CSV file must be titled exactly as the field name is listed below. For this reason, when creating new users, use our CSV template as a base.

Available User Fields

  Tip: Click on the images below to expand the view and zoom in.

Field Name	Definition	Location in System	ADP Clients: Can be updated via User Import?
First Name	The user's Preferred and Legal First Name. *Required		No
Last Name	The user's Preferred and Legal Last Name. *Required		No
Email	The Work Email Address of the user. *Required		No, unless Work Email has been disabled from the employee data sync.
Personal Email	The Personal Email Address of the user.		No, unless Personal Email has been disabled from the employee data sync.
Mobile Phone	The Mobile Phone Number of the user.		No, unless Mobile Phone has been disabled from the employee data sync.
Gender	The Gender of the user.		No, unless Gender has been disabled from the employee data sync.
Race	The Race of the user.		Yes
Ethnicity	The Ethnicity of the user.		Yes
Username (separate from email address)	The Username that the user will use to log in, if set to log in with ClearCompany credentials. (If excluded from the user file, the system will default the Username as the user's Work Email)		Yes
Status (A/D/T)	The account status of the user, either Active, Deleted, or Terminated.		No, user records controlled by ADP must have their status changed in ADP. These changes will reflect in ClearCompany upon the next System of Record Sync.
Reports To [email]	The email address of the user's reporting Supervisor.		No, unless Supervisor has been disabled from the employee data sync.
Job Title	The Job Title of the user.		Yes
Hire Date	The Latest/Most Recent Hire Date of the user.		No
Original Hire Date	The Original Hire Date of the user.		Yes
Employee Id	The custom Employee ID of the user.		Yes
Department	The Department the user is employed in. *Required, unless ADP client.		No, unless Departments have been disabled from ADP System of Record sync.
Office	The Office the user is employed in.		No, unless Offices (ADP Locations) have been disabled from ADP System of Record sync.
Role Name	The Role that the user is employed in.		No, unless Roles (ADP Job Titles) have been disabled from ADP System of Record sync.
Role Start Date	The Start Date of the Role assigned to the user. This will differ from the original hire date if the user has held multiple positions.		No
Termination Type	Acceptable Values: Voluntary or Involuntary.		No
Termination Reason	An optional reason for why the user is being terminated.		No
Termination Date	The Date on which the employee termination takes place. MM/DD/YYYY Format.		No
All User Permissions	In each permission column, enter Y to Add and N to Remove the permission from the user.		Yes
Tags (Up to Three)	Custom Tags that should be assigned to the user.		Yes
Password	The Password that the user will use to log in, if set to log in with ClearCompany credentials.		Yes
Date of Birth	The Date of Birth of the user. MM/DD/YYYY Format.		No, unless Date of Birth has been disabled from the employee data sync.
Annual Earnings	The Annual Earnings (Salary) of the employee.  Must be whole integers, with no special characters (no $ . or , )		No, unless Compensation Information has been disabled from the employee data sync.
Vendor User ID	The ID associated with the employee in a 3rd-party system like ADP or Paylocity. Typically only used for custom SFTP integrations.		Yes, but this field does not provide additional functionality through the ADP Bi-Directional Connector.
Data Group Access One*	*For organizations with Data Walls. The first Data Group the user should have access to.		Yes
Data Group Access Two*	*For organizations with Data Walls. The second Data Group the user should have access to.		Yes
Data Group Access Three*	*For organizations with Data Walls. The third Data Group the user should have access to.		Yes
ManualAuthenticationEnabled	For organizations using the Mixed Mode login method, set a user's sign in method. Enter Y to set the method as ClearCompany credentials and N to set it as using Single-Sign On (SSO).		Yes

Unavailable User Fields

The following employee/user fields are unable to be added/updated via the User Import Tool: 

• Work Phone Number
• Setting the 'Primary' Email
• Employee's Address Information
• Changing User Preferences

 

1. Create your CSV File of User Data

During this stage, you will be creating a spreadsheet of user information, ensuring it meets the expected format and requirements for a successful import. 

1. Use a spreadsheet app, like Excel, to begin creating your file of user data.
   • If you're only creating new users, it is recommended to use the template provided below for ease of use and a higher rate of success during the upload stage.

   • If you're creating new and updating existing users, you must use the system user export file as the base for the spreadsheet. Open the menu below to learn how to obtain the user export file.

     Generate your User Data Export File

     1. Navigate to Tools > Setup, and select Users under Organization Setup.

        

     2. Click the Import data button in the upper right-hand corner and select Users.

        

     3. Open the Export Users To CSV menu and choose which group of users to export.

        

        • All (Active + Inactive) - Commonly used to review the full list of employees in your organization's ClearCompany account, regardless of the user's state.
        • Active Users Only - Commonly used to update the details, like permissions or email addresses, for a large group of active employees.
        • Inactive Users Only - Commonly used to bulk re-activate terminated or deleted employees.
          
          The system will generate a CSV file of your user group and upload the file to your Secure File Center within ClearCompany. You will receive an email notification when the file is ready.

     4. Locate and download the user file, either from the link within the email notification or by accessing the Secure File Center directly via Tools > Setup > Secure File Center.

        

     5. Click on the CSV file to download it to your computer.

        

     6. Open the CSV file in an application such as Microsoft Excel or Google Sheets and follow the best practices listed below to edit your user’s information. 

2. For each user row, enter a value in the column for the following Required Fields: First Name, Last Name, Email, Department.

     Clients with the ADP Bi-Directional Connector must remove any columns that are controlled by ADP as the System of Record. To confirm this list of fields for your organization, check your Connector Configuration by navigating to Tools>Setup>ADP Integration Management.

   

   Continue adding values for the optional user data fields, as needed. Review this table for a list of all fields available to be included in the CSV file.

     While the Office field is not required, it is highly recommended to include an Office value when creating new users in bulk. This will allow you to edit the user accounts in the system later without needing to assign an Office at that time.

   Data Entry Best Practices

   1. Keep the rows of users you need to update within the spreadsheet. You can remove rows for users who are not being edited.

   2. Review the available columns and note which information you will be adding/updating for the users. Delete the columns you are not using.

     The following columns MUST remain in the CSV file in order for a successful import.

   1. User ID* - *Only required if you are including existing users in your spreadsheet. The ID listed in this column is auto-generated by the system as a unique identifier for each user account. To add new users to the same file of existing user data, leave this field blank on the new user rows.

      

        Important: If you are updating existing users, DO NOT edit or clear out this column. Doing so will cause the system to not recognize the current user, thus creating a new user account for the employee. Duplicated user accounts cannot be merged.

   2. First name
   3. Last name
   4. Email address
   5. Department* (must match the existing options set up in your ClearCompany Account)
   6. Office* (must match the existing options set up in your ClearCompany Account)

     *Clients with the ADP Bi-Directional Connector must remove any columns that are controlled by ADP as the System of Record. To confirm this list of fields for your organization, check your Connector Configuration by navigating to Tools>Setup>ADP Integration Management.

3.  To update user permissions in bulk, enter a Y in the corresponding cell to grant the permission to a User. If the user should not have the permission, enter N. If you do not want to update a particular permission for certain users, simply leave that cell blank (do not include either a Y or an N). Note: Some permissions may appear labeled differently from the Edit User page. Review this table to view the permission title matches. 

   

     It is recommended to assign all new employees (except third-party recruiters), the Employee permission. Enabling certain permissions may incur a cost. Review this article for definitions and details of each user permission. 

4. Once you have added or modified the necessary fields, review the full set of data to confirm you have met the minimum field requirements and data best practices. Save your spreadsheet as a CSV file type. 
5. Follow the steps in the Import your User CSV File section below to upload the CSV file.

 

2. Import your User CSV File

1. Navigate to Tools > Setup, and select Users under Organization Setup.

   

2. Click the Import data button in the upper right-hand corner and select Users.

   

3. Click Upload CSV and Process.

   

4. Locate the file from your device and click Open.

   

5. The User Import page will load a preview of the data from your selected file and provide you an opportunity to review and confirm the anticipated results of the import before it occurs.  

   

   Only a subset of the data from your file will be displayed as a guideline for you to review. Click Ok to preview the next set of data.

6. Next is a sequence of pages to confirm the system appropriately matches the data entries on your spreadsheet with the values you have in your account. It will include Offices, Departments, Ethnicity, Races, and Roles. You may edit the assigned values as necessary, then click OK to continue through the next data set.

   

7. After reviewing the final data set (Roles) click Submit to begin the import process or click Start Over to cancel and make changes to your user data file.

   

8. After submitting the import, a success message will appear advising that the system is processing the user import.

   

9. Upon completion, you will receive an email with the subject " ClearCompany User Import Results" which contains the results of the import. If any errors occurred during the import attempt, they will be detailed in the email and you can reference the section below for troubleshooting tips.

Troubleshooting User Import Errors

1. Unknown Column Header:
   • An unknown column is included in your CSV file. To avoid this problem, we recommend using the template attached to this article. It includes each field that can be updated through the import tool.
2. Unable to add a user:
   • You may receive this error if you're missing one of the required fields when creating a new user. Review your CSV for missing or mistyped entries.
   • You may also receive this error if you have empty columns. Remove any columns that you aren't using for the import.

FAQs

Are there common ways the import could fail to process?

• Yes, not including data for required fields or leaving empty columns in the CSV file may result in an inability to process the data file. Please remove any extraneous/empty columns, like Annual Earnings, before uploading the CSV file into ClearCompany.

Will the import tool delete users who are not included in the CSV?

• No, the system will not delete a user unless they are explicitly included in the user CSV file.

Will existing user data be overwritten if I keep the user rows in my CSV file?

• It is recommended to remove the rows of users you are not updating, however, the system will only update an existing user record found in the CSV if it detects a change of values for any included columns. 

Can I bulk set or update the Primary email setting for users using this tool? 

• At this time, the Primary email setting must be set and modified on a per-user basis from within the User Setup page in ClearCompany. Review this table for a list of all fields available to be included in the CSV file.

Do you have a sample CSV file that could be used as a template?

• Yes! Download the CSV file below to fill out with your candidate's information, or use it as a quick comparison of your existing candidate data file.