Overview

Flatfile (Beta) is available for users that prefer to receive data from HRIS and payroll systems via an excel file (rather than JSON). Flatfile is available by request to customers on our Scale plan.

Watch a quick demo of Flatfile below, or jump to How to set up Flatfile to get started.

How is Flatfile different from a typical SFTP integration?

SFTP (Secure File Transfer Protocol) is a method for bulk, secure file transfer between systems. It is commonly used to share information from an HRIS or payroll system to third-party applications that require regular updates on employee census, payrolls, and benefits in order to administer or manage services (eg. 401(k), Workers Compensation, HSA/FSA, etc.).

While Flatfile utilizes SFTP, there are a few key differences when compared to a 1:1 SFTP integration with an HRIS or payroll provider. 

In a typical SFTP setup, the provider (HRIS/payroll) would work with an individual client (employer) and third-party application (your app) in order to configure a custom file to transfer routinely. Each provider has different setup requirements, implementation timelines, and costs associated with this process. Generally, each employer must go through implementation individually.

With Flatfile, you can skip the back-and-forth between your clients and their providers while still receiving the data you need. Here's how it works:

1. You provide an SFTP server where files will be delivered regularly
2. Your customer (the employer) connects their HRIS/payroll system via Finch Connect
3. Finch delivers any data retrieved through the API to the provided SFTP server in a standard file format that maps to our API data model 1:1
4. Files are delivered upon first connection, and after each pay run

Once files are delivered, you can set up any automations that help your Operations team action on the data.

How to set up Flatfile

In order to set up Flatfile, please follow the instructions below. Please note, Flatfile is currently only available for our automated integrations.

1. Set up your SFTP server (if needed)
2. Ask Finch to enable Flatfile
3. Provide your SFTP Credentials
4. Create and share a Connect Link
5. Retrieve file(s) from SFTP server

1. Set up your SFTP server

Please note if you already have an SFTP server you would like the files to route to, you can skip this step.

If you don't have an SFTP server you may use a service like Ionos to quickly spin up a destination for the files we'll prepare. Your server will need to be password protected. We recommend specifying a directory for the files we'll deliver; best practice is to have a descriptive name like "/inbox-finch"

2. Ask Finch to enable Flatfile

Please note you will need to be on a Scale plan in order to use Flatfile. Just reach out to your Developer Success Engineer to enable this feature.

3. Provide your SFTP Credentials

In the Dashboard, navigate to the Credentials tab and scroll down to the SFTP module. Here you may specify the SFTP credentials where Finch will deliver files -- you can edit this information at any time.

Configurable SFTP credentials include:

• URL (required)
• Port
• Username (required)
• Password (strongly recommended)
• Target Directory (recommended)
  • Best practice is to have a descriptive directory name like "/inbox-finch"
• Email (required)
  • This email will be notified if a connection needs to reauthenticate.

4. Create and share a Connect Link

Once SFTP is configured, navigate to the Connections tab to 'Create a new Connect Link'. You can share this link with an employer to connect their HRIS/payroll system. When generating a link you'll be able to specify a few details:

• Company Name (required)
  • This is the Company Name you use in your system to identify your customer.
• Customer ID (required)
  • This is the ID you use in your system to identify your customer. This could be the Plan ID or another identifier.
• Provider ID
  • Choosing a provider will direct your customer straight to that provider rather than allowing them to select one. If you don't want to specify a provider, skip this field.

Once authorization is successfully completed, you can monitor the connection in the Dashboard as usual.

5. Retrieve file(s) from SFTP server

Once a connection is established, you should be able to find a new file in your SFTP server. Files will be delivered upon each successful connection and after each pay run.

Each data sync will produce a new excel file, named finch-{planId}-{company name}-{providerId}.xlsx

Each file delivered will be sorted into 4 tabs (below), and columns will mirror the standardized data model used in our API. 

• Org Data: Directory + Individual + Employment
• Last Year Pay Data: Payment + Pay Statement
• YTD Pay Data: Payment + Pay Statement
• Last Pay Run: Payment + Pay Statement
• Pay Groups: Get Pay Groups

You can view a sample file here.

FAQ

1. Which providers are compatible with Flatfile?

Flatfile is availabe for our automated integrations. Assisted integrations are not yet supported.

2. Can Flatfile users still take advantage of webhooks?

Yes. Job completion webhooks are available for users that have enabled Flatfile.

3. Can I customize the file format at all?

Custom formats are not currently available. If you need assistance with our file format, please reach out to your Account Manager. 

4. Will the file format change with updates to the API?

New fields will be added to the file format as our API evolves, but we will not remove fields. Please take this into consideration when building any downstream automation based on these files. 

5. Will files be delivered for connections that existed prior to setting up the Flatfile feature in Finch?

No, files will only be delivered for connections established after Flatfile has been configured, and only for connections established following step 4 above: "Create and share a Connect Link".