Skip to main content

Keep Your Org Updated with SFTP

Liz
  • Updated

How to set up an SFTP integration to send employee data to Lattice

Jump to Section

  1. About SFTP with Lattice
  2. Before You Begin
  3. Initiating Setup & Overall Process
  4. File Format
  5. Headers
  6. Employee Population
  7. Data
  8. Connection / Authentication
  9. Scheduling
  10. Import Results
  11. Step-by-Step Guides

About SFTP with Lattice

If your HRIS provider does not have a one-click direct integration with Lattice, you can still automatically send employee data from your HRIS to Lattice by sending a CSV file via SFTP (SSH File Transfer Protocol). SFTP can be used to create new users, deactivate former employees, and update fields for existing users.

Using SFTP is similar to uploading your employee information via CSV, but happens on an automated schedule. Many HRIS providers can generate a CSV file of your employee data and send it to our SFTP server.

Before You Begin

  1. If you're not sure whether your HRIS has SFTP capability, contact your HRIS representative directly. They can help you confirm if this is possible and begin the setup. Otherwise, if you have an engineering or IT team, they may be able to write a script to upload CSV files to Lattice’s SFTP server.
  2. Confirm with your HRIS representative if there are any fees associated with setting up a custom report sent via SFTP. While Lattice does not charge additional fees for SFTP, your HRIS provider may. 

Note: Lattice does not offer an SFTP integration with Paycom.

Initiating Setup & Overall Process

  1. To begin the process and generate SFTP account credentials, contact Customer Care by emailing customercare@lattice.com and CC your Customer Account Manager (CAM). In the email outreach, please include:
    • The name of the external system that will be transferring files to Lattice.
    • Your Lattice subdomain. The Lattice subdomain is the URL portion that precedes the latticehq.com domain. For example, if your organization's Lattice URL is "https://bigco.latticehq.com," "bigco" would be your subdomain.
    • The email address of a technical contact who has superadmin or Integrations Admin permissions in Lattice and the external system.
  2. You’ll then build a report in your external system of record (usually an HRIS) and send it to Lattice. File formatting requirements are listed below. Some systems have a team that builds the report for you, while others are self-serve.
  3. Customer Care can review the file manually and suggest any changes needed before a successful import. 
  4. SFTP credentials will be provisioned securely by Lattice.
  5. You will input those SFTP credentials into your external system of record and set a schedule. As with building the report, some systems will set up the SFTP automation on your behalf, while others allow admins to self-serve this setup.

File Format

The files that Lattice receives must be in the following format to process successfully:

  • Files should be sent in comma-separated values format and use UTF-8 encoding.
  • The file extension must be “.csv” (case-sensitive)
  • Filename does not matter as long as the extension is “.csv”. It’s recommended to include a datestamp in the file name if that is an option in your system of record, but this is not required. 
  • For example, lattice-file.csv or lattice-file-20260101.csv will both import successfully. 
  • Headers should not be enclosed in double quotes. Data rows may be enclosed in double quotes. Any data containing a comma in the value (for example a Job Title of “Director, Customer Support”) must be enclosed in double quotes to ensure successful import. 

Headers

  • All files sent via SFTP must include headers in row 1.
  • Column order does not matter; data is matched to Lattice fields based on the matching header value.
  • All files must include the following columns at a minimum:
    • Status
    • at least one Name field*
    • Work Email
    • Job Title
    • Manager Email or Manager ID
  • *See Column Headers Accepted for SFTP for a full list of accepted column headers.
  • Headers are not case sensitive. The column header "Work Email" or "work email" will both update the work email field successfully. 
  • For columns with more than one word, Lattice will accept a space or an underscore in between (Ex, Preferred_First_Name).
  • Custom fields may be included and must be created in Lattice prior to SFTP import. See how to Create a Custom Field. 
  • Headers should not be enclosed in double quotes. When opened in a text editor, a valid set of headers will look like this:
    Preferred First Name,Preferred Last Name,Job Title,Work Email,Manager Email,Status
    In comparison, this is an invalid format for headers and will result in an error on the first row on each sync:
    "Preferred First Name","Preferred Last Name","Job Title","Work Email","Manager Email","Status"

Employee Population

The employees included in your SFTP report will be controlled within the external system where the report is built. Most tools offer filters in their report builder, allowing you to select a subset of employees to bring into Lattice.

Requirements: 

  • Lattice expects one row per employee.
  • All active employees who need a Lattice account should be included. 
  • Terminated employees must be included with a status of “Terminated” or “Deactivated” at least once in order for Lattice to deactivate the account. 
  • Terminated employees can remain on the file indefinitely or be dropped off after a period of time.
  • If someone is already terminated in the report and never had a Lattice account, no account will be created for them.
  • Re-hired employees can only be reactivated if their inactive Lattice account and the SFTP file both include a matching External User ID value.
  • Best practice is to send a full file of all employees with each sync, rather than a file of only changes. 

Unique Identifiers

Employees are uniquely identified by their External User ID (also labeled Employee ID) or, if an External User ID is not included or not yet present in the user’s Lattice profile, by Email. It is recommended to include an External User ID, if possible, to prevent duplicate accounts from being created if an employee’s email address ever changes. 

Data

  • Any cells left blank will overwrite the current value in Lattice with NULL. 
  • If a Lattice field does not have a column in the SFTP file, its data in Lattice will remain unchanged.
  • When syncing data to multiple-choice fields, new values will be added automatically. If you’re creating a new custom field in Lattice, you only need to add one possible value to the dropdown, and the SFTP sync will populate the rest. 
  • Dates should be in YYYY-MM-DD format
  • The CEO or anyone who should be at the top of the org chart should have no manager listed. This is required to build the org chart. Anyone reporting to themself will get an error in the import log.
  • The Manager Email column should contain an email address. If the header “Manager ID” is used instead, the column should include an Employee ID. You do not need to include any manager names; Lattice will associate the matching user profile. 
  • Any Relationship type fields should contain a user email address. 

Connection / Authentication

Lattice provides secure SFTP endpoints for automated data transfer. Connection details including hostname, credentials, and configuration requirements are provided securely by Customer Care during setup. If you have questions about an existing integration, please reach out for support.

WinSCP

If you are using the FTP client WinSCP, disable the setting that enables transfer resume/transfer to a temporary filename to guarantee successful uploads.

Scheduling

The time and frequency of SFTP file syncs are controlled entirely in the external system. Lattice processes imported files as soon as they are received. Most organizations choose to send a file once daily. 

To run an ad-hoc data sync, you’ll need to confirm whether your external system allows you to trigger a sync outside the schedule you configured. You can also download a copy of the report as a .csv file from your external system and upload it manually to Lattice. 

To temporarily stop Lattice from processing any files, you can pause your SFTP sync. 

Import Results

To check whether the file imported successfully, see the import log.

Step-by-Step Guides

Here are step-by-step guides for some common HRIS platforms that support an SFTP file sync to Lattice:

Related articles