HRIS Integration

2019-12-16 21:01:32 UTC
by Sydney Phelon

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.

Requirements to Integrate

  1. Create a file with user information in CSV (standard UTF-8 encoding) or JSON format according to our HRIS Connector & CSV User Upload Template in the Advanced Setup section of this document
  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.

Some Common Vendors

  • Workday
    Contact the Workday Customer Support Team for details. 
  • Oracle
    Contact your Oracle Customer Support Team. The level of assistance you get is dependent upon your Oracle Support package.
  • UltimateSoftware (Ultipro)
    Navigate to your Customer Success Portal, select Project Center, and 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 to inquire about automation. 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, and upload in the Admin panel
  • BambooHR
  • Zenefits

As a note, the BambooHR and Zenefits integrations are direct-API connections so function a bit differently than our standard HRIS integrations so please see the linked articles for using the BambooHR and Zenefits integrations.

Basic Setup

  1. Build a JSON or CSV (standard UTF-8 encoding) report with the following Headers:

    “deactivation_date” (This value should be blank/empty for current employees)

    Please include .csv or .json in the file name. Each file should also be uniquely identifiable.

    By default, the "email" value 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 of email) for an account. This will allow for changes to the email address with which an account is associated and will prevent the creation of a new account when an updated email address is imported.

    In Workday this can be done using the "Compose CSV" action under the "Utilities" application.
  2. 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 your Customer Success representative 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.

  3. 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. For any issues, please contact to confirm your HRIS Connector is configured and running correctly.

Advanced Setup

In certain cases, betterworks administrators prefer to send additional fields 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 attribute. 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 organizational chart). 


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

“custom_01” through “custom_05”

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

Note: If your system is unable to utilize the "deactivation_date" field, please contact to discuss alternative fields for your file.

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.  If it’s the email field, 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.  If you are unsure how this works for a specific field, please contact

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 I am using a date as a custom field (i.e. hire_date), will the system recognize this as a date instead of a text field?

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?

Departments have a max length of 140 characters. First name has a limit of 30 characters. Last name has a limit of 30 characters. Email address has a limit of 254 characters.


CSV Templates



Was this article helpful?

Related articles


Article is closed for comments.