Articles in this section

Setup Guide: Universal HRIS Import

ActivTrak Product Team
published
updated

Required: HRIS Integration (Add-on)

The Universal HRIS Import feature requires the HRIS Integration (Add-on). Reach out to our Sales Team for more information.

 

If your HRIS doesn't have a direct API integration with ActivTrak, you can use SFTP (Secure File Transfer Protocol) to securely send time-off data as a CSV file. This is a great option when you need to sync workforce data from systems that support custom report exports.

There are two ways to send your data:

  • Manual CSV upload — Download a report from your HRIS and upload it directly to ActivTrak's HRIS integration services partner's secure AWS data centers. Best for one-time syncs or occasional updates.
  • Automated SFTP transfer — Schedule your HRIS to send reports automatically on a recurring basis. Best for keeping data in sync over time.

Important: Each time data is synced, the system processes the full file, processes updates, and removes any rows that are no longer present. This means every transfer should include your complete, up-to-date dataset — not just changes since the last sync.

Contents

Before you begin

Make sure you have the following ready before starting setup:

  • Your account has the HRIS Integration (Add-on) 
  • Admin access to your HRIS system's reporting or data export module
  • An ActivTrak Admin role to configure the integration in APIs & Integrations > Integrations
  • The list of required employee and time-off fields 
  • If using automated SFTP, confirm that your HRIS supports scheduled CSV exports via SFTP

File requirements

Your CSV file must meet these formatting standards for a successful sync:

  • File format: .csv only (no .xlsx, .tsv, or other formats)
  • File name: HRIS.csv
  • Required columns: See required columns and the expected data formats in the table below
  • File size: 250 MB maximum
  • Clean data only: Do not include summary rows, footer rows (such as "Totals"), or blank rows at the end of the file
  • Column headers: Field names in your CSV must match the expected format exactly
  • Time off fields: Verify that the Time Off Amount and Time Off Unit values are consistent. The Time Off Unit defines how the amount is measured (for example, days or hours). A mismatch — such as an amount of 8 paired with a unit of days when it should be hours — will result in inaccurate data.

 

Field type Required? Header name Type of data
Employee ID Required for
Employee lookup 		employee_id Employee data
Employee Number Required if using Employee ID/number as the primary lookup.
May need to copy values from the Employee ID. 		employee_number Employee data
Work Email Required for
Employee lookup 		work_email Employee data
Time Off Request Date
(e.g., 12-23-2026) 		Required for
Time Off data
Date Format:
MM-DD-YYYY or DD-MM-YYYY 		timeoff_request_date Time Off data
Time Off Start Date
(e.g., 12-23-2026 or 12-23-2026 9:00 AM) 		Required for
Time Off data
Date Format:
MM-DD-YYYY or DD-MM-YYYY 		start_time Time Off data
Time Off Amount
(e.g., 8) 		Required for
Time Off data 		amount Time Off data
Time Off Unit
(e.g., hours, days) 		Required for
Time Off data 		units Time Off data
Time Off Request Type Optional request_type Time Off data
Time Off Status Required for
Time Off data
"approved" displays data in reports. Not case-sensitive 		status Time Off data
Time Off ID Optional but extremely helpful if available timeoff_id Time Off data

Build the report

  1. Log in to your HRIS system
  2. Navigate to the reporting or data export section
  3. Create a new custom report (or modify an existing one)
  4. Add the employee fields you want to sync as columns in the report. At a minimum, include employee_id plus any fields relevant to your use case (for example: first name, last name, email, department, job title, manager, hire date, employment status).
  5. Name the output file HRIS.csv
  6. Run the report and export it in CSV format

Important: Before moving on, open the exported CSV and confirm that the required columns and value formats are present, there are no summary or footer rows, and the data looks correct.

Send the data

Choose one of the following options based on how you want to keep your data up to date.

Option A: Manual CSV upload

Use this option if you need a single sync or only plan to update data occasionally.

  1. Download the CSV report you created
  2. Open the Integrations page (APIs & Integrations > Integrations) in the ActivTrak App
  3. Locate the Universal HRIS Import tile and click + Add Instance, or an existing instance if one was previously added for a prior manual upload
    • If manually re-uploading a CSV, click the Configure instance button
  4. Click Connect to Universal HRIS Import or Connect a different account
  5. Upload the HRIS.csv file directly into the linking modal

Option B: Automated SFTP transfer (recurring)

Use this option if you want your HRIS data to sync automatically on a regular schedule.

  1. Request or configure your HRIS system to schedule periodic CSV exports

  2. Open the Integrations page (APIs & Integrations > Integrations) in the ActivTrak App
  3. Locate the Universal HRIS Import tile and click + Add Instance to enter your SFTP connection details. In this modal, you'll be provided the hostname, port, directory, and username that you can use with your HRIS SFTP configuration.
  4. Request the public key from your HRIS provider (or your IT admin) to enter into the ActivTrak configuration. This is typically the public key of a SSH key pair.
  5. Select the date format that your CSV uses.

Validate and go live

Once your first file has been uploaded or transferred, take these steps to confirm everything is working:

  1. Check for validation errors. After the file is received, the system automatically checks that your CSV has the correct schema, all required fields are present, and there are no formatting issues. If validation fails, you'll see an error message with details about what needs to be fixed.
  2. Confirm data ingestion. Verify that employee records have been successfully synced and that the data in ActivTrak reports looks accurate
  3. Monitor the first few syncs. Keep an eye on the initial transfers to catch any issues early, such as field mismatches, missing required columns, or rows that were unexpectedly removed.

Troubleshooting

If your sync isn't working as expected, check the following:
 

Issue What to check
Sync fails entirely Confirm the file is in .csv format and named HRIS.csv
Missing employee records Verify the employee_id column is present and populated for every row
Unexpected row deletions Remember that each sync replaces the full dataset — make sure your report includes all current employees, not just recent changes
Validation errors on fields Check that column headers exactly match the expected names from the SFTP Report Template
Extra rows causing errors Remove any summary, total, or footer rows from the bottom of the CSV
File too large Reduce the file to under 250 MB, or contact support for guidance
SFTP connection fails Double-check the hostname, port, directory, and credentials from your linking modal

Learn more

Was this article helpful?
1 out of 1 found this helpful