HRIS Integration

Recommended Reader(s): Super Admins

What is an HRIS Connector?

The Betterworks HRIS Connector allows you to import data from a Human Resources Information System (HRIS) into Betterworks on a regular schedule. You can see updates from your HRIS in Betterworks without manual intervention such as:

  • Creation of new users
  • Updates to user information for changes to department or manager
  • Deactivations of users who have left your organization

If you import data for a user whose department is not in Betterworks yet, the HRIS Connector will create that department for you. For example, if you import users for the Finance department, but don’t have that department established in Betterworks yet, the department will be created based on the “department_name” value specified in the report. 


HRIS data sent to Betterworks via an SFTP upload is stored at rest on an encrypted (AES-256) volume, meaning the file location itself is encrypted.  Data is also encrypted in transit by using the SSH File Transfer Protocol (SFTP).


1. Create a file with user information in .csv (standard UTF-8 encoding) or .json format according to our templates (at the end of this article)

2. Schedule regular file exports to our HRIS connector

We have an open platform so as long as the above requirements are met, you should be able to create an HRIS integration with Betterworks. Below are some common vendors.

Common HRIS Vendors

  • Workday: Contact the Workday Customer Support Team for details. 
  • Oracle: Contact your Oracle Customer Support Team.
    • The level of assistance you'll receive for this process is dependent upon your Oracle Support package.
  • UltimateSoftware (Ultipro): Navigate to your Customer Success portal > Project Center, then open a Service Request for "Technical consulting in web services".
  • SuccessFactors: This document can help get you started, but you will also need to contact your SuccessFactors Support Team. 
  • ADP: Contact your ADP Integrations Specialist Team for details.
    • Depending on your product offering, ADP typically charges $1/user per month for automated services. If this price point seems high, you can always pull a report out of ADP manually, reformat into the .csv template below, then upload it into the Admin panel
  • BambooHR
  • Zenefits

Note: BambooHR and Zenefits integrations are direct-API connections. As a result, they function a bit differently than our standard HRIS integrations.

Basic Setup

1. Build a .json or .csv (standard UTF-8 encoding) report with the following column headers:


In Workday this can be done using the "Compose CSV" action under the "Utilities" application.

1. Schedule the report to be sent to the Betterworks SFTP server regularly. The HRIS Connector uses industry-standard SFTP cryptography to protect your data and a member of the Betterworks Support Team will provide you with unique credentials to access the server.

Note: You can set the interval at which the report is sent to whatever frequency you like, but we recommend once a day. Once your file arrives, the HRIS Connector will sync the data automatically each hour.

2. Once you’ve uploaded the report, the Betterworks HRIS Connector will collect the information and use it to create and update user data in Betterworks. 

Advanced Setup

In certain cases, Betterworks administrators prefer to include additional headers in the HRIS file to keep account management tidy or create more powerful reports in the Admin panel. Please download the .csv attachment at the end of this article to see the template file.

If unique identification numbers are assigned to each person in your company, you may want to consider adding them to the file to ensure Betterworks accounts stay intact even if someone changes their name, email, or other attributes. We strongly recommend providing both the employee ID and manager ID with each record (with the CEO or leader of the company having a blank manager ID since they're at the top of the org chart).


The following fields will only appear in the Admin panel for reporting purposes: 

"custom_01" through "custom_05"

These are not visible on a person's profile, the objective filtering list, or in the org chart.

HRIS Integration Errors

Please refer to our HRIS Integration Errors article for information about how to handle common HRIS integration errors.


If a user is omitted from an upload file, what will happen?

If a user is omitted from a file, this will not cause any change or removal of that user’s account in Betterworks.

If I leave a field blank for a user in the file to be uploaded and the content in the corresponding field in Betterworks has data, what will happen? 

This will depend. The "email" field is required. If it’s for a field like "custom_01" to "custom_05" for example, this will result in an update, meaning that the data in the corresponding field in Betterworks will be removed.

Can I include column headers that are not listed in the HRIS Connector & CSV User Upload Template and if I do, what will happen? 

Including column headers such as "employee id" instead of "employee_id" or column headers that you make up will not be processed by our HRIS connector and will be ignored by it.

If my custom header is being used for a date (i.e. hire_date), will the system recognize this as a date instead of text?

Yes, this date will be added to the user's account record as an attribute, whether by manual upload or HRIS.

If I have an HRIS Connection, can I still do a manual CSV upload through the admin panel? 


When would I need to be worried about deleting data?

If you include the header with no data in the column, then it will wipe out any existing data.
If you remove the header completely, then it will not impact the data already uploaded into the platform.

Are there character limits for any of the text fields?

"first_name" - 30 
"last_name" - 30
"email" - 254

CSV Templates

HRIS Basic Template

HRIS Advanced Template


  • By default, the "email" field will be used as the primary identifier for an account. However, "employee_id" and "manager_id" fields can be included in order to use "employee_id" as the primary identifier instead. This will allow for changes to the email address with which an account is associated and prevent the creation of a new account when an updated email address is imported.
  • "deactivation_date" should be left blank until the employee's last day with the organization. Otherwise, their user profile will be deactivated prematurely. If your HRIS has an "active/deactivated" status that you can map to, it's strongly recommended that you replace the "deactivation_date" header with "is_active" which accepts the inputs of "true" or "false". 
  • Ensure that all files sent end in either .csv or .json.
  • Each file should be uniquely identifiable. We recommend naming each file sent with the current date.