Adding & Updating Users: CSV Upload


Build Out the User CSV File

Note: To update users individually, see this article. To update users via our HRIS integration, see this article.

We've provided templates below. The basic template includes our recommended fields while the advanced template includes additional predetermined fields as well as 5 custom fields. If you need more custom fields, see this article

1. Ensure that your file contains the required fields. We strongly recommend downloading our explanation of fields to learn more about each field in our templates.

2. Save.

Upload the User CSV File

1. Go to Admin → User Management → Departments and users → Users → CSV upload:


2. Upload CSV file.

3. Check for and correct any errors.

4. Save.

Deactivate An Existing User

To deactivate an existing user, simply enter a value in their "deactivation_date" field. If the deactivation date is in the past, the user will be deactivated immediately. If the date is in the future, our platform will deactivate the user on the date specified.

When a user is deactivated:

  • They can no longer log into Betterworks.
  • They will no longer be counted towards licenses (aka "seats").
  • Their goals and milestones will remain active and searchable, but their manager or an administrator can delete or re-assign the goals and milestones as they see fit
  • The user themselves (i.e. their profile) will not be searchable
  • They will no longer display in some administrator reports unless the report was generated with that option selected (i.e. "include deactivated users")
  • Their manager will be notified via an automated email
  • The owner of any goals that the deactivated user is associated with (i.e. they owned a related milestone or had an aligned goal) will be notified via automated email

Build Out the Department CSV File

If you include new departments in your user CSV file, they will automatically be created in Betterworks. If your organization has a parent/child department structure (i.e. Accounts Payable rolls up to Finance), use the departments template so that you can easily filter during reporting. 

1. Create a CSV file with 2 fields: "Name" and "Parent". 

2. Ensure that any "Parent" entries align with departments in the "Name" field:


3. Save.

Uploading the Department CSV File

1. Go to Admin → User Management → Departments and Users → Departments → CSV Upload:


2. Upload CSV file.

3. Save.



Why am I not seeing the new departments I uploaded in Betterworks?

When first uploading a CSV with new users and new departments, the data may take up to 2 hours to process.

What should happen when I upload a department CSV? 

  • If you upload a department CSV file and the department and parent department already exist, it will not allow you to complete the upload.
  • If you upload a department CSV file and the department exists, but the parent department is different, the file will push the update through.
  • If you upload a file and the department is new, it will create the new department along with the parent relationship.

How do I remove departments?

You can deactivate a department manually by going to:

Admin module → Departments and users → Departments → Individual update

You can deactivate departments en masse by using the department CSV file, adding the departments that you'd like to deactivate, and setting the value under "is_active" to FALSE.