SFTP CSV Set up and Instructions

This article summarizes how your company can automatically synchronize users in Bucketlist via SFTP csv

SFTP General information

  • Bucketlist will provide you with credentials to access our server (username, password, IP address, port). You can use these credentials to either a) set up a an SFTP csv connection within your HRIS (most common) or b) drop the csv file manually to our server (less common).
  • A public key (open ssh style) is an option for the secured connection vs username/password, etc. Please let us know if this is a requirement on your side.
  • Inform your Bucketlist representative if you require our SFTP whitelist location (recommended). This requires Bucketlist to whitelist your IP addresses from where the CSV is going to come from. If this is a requirement on your end, please provide your Bucketlist rep with the necessary IP addresses for whitelisting.
  • CSV file syncs every 24 hours. They sync happens overnight to Bucketlist daily between 3:00AM - 8:00AM EST. You can schedule how often you want to push new file updates to Bucketlist. Most companies do it daily or weekly.
  • The CSV should be cumulative, meaning that all the users should be in the csv file. When a user is removed from the CSV, they are deleted from the platform. When a user is added to the file, they will be added and invited to Bucketlist  
  • It's possible you may need to contact a rep or submit a service request to your HRIS vendor  to help you set up the SFTP csv to Bucketlist (if you are unable to do it on your end). Note: a set up fee may apply from your HRIS vendor (this is outside of Bucketlist).                                                    

SFTP CSV Instructions 

  1. Bucketlist will provide you with our server credentials so you can do the set up on your end.
  2. Important! Review this  SFTP CSV instructions template here. Click on the screenshot below to view the mandatory and optional fields.

  3. Decide on the fields you will bring over to Bucketlist (based on the template above)
  4. Set up the SFTP csv connection within your HRIS (most common) OR drop the csv file manually to our  server using a free file transfer tool like Filezilla (less common). If you're manually sending  the file, reference this article on how to access our SFTP server
  5. Once you have created the csv, please let your Bucketlist rep know. We will access the server  to validate the file formatting and configure on our end so we can read the file. Once we          review formatting and all looks good, we will then conduct a test to ensure the file is working as expected.

SFTP CSV Formatting and Troubleshooting Tips:

Date Format:

Please double check that the date format has not changed when exporting from Excel to CSV:

  • To ensure the date format hasn’t changed, read this article 
  • The issue probably isn’t on the CSV file, it is when  the file is opened in excel. 
  • How to open a CSV with Excel: Excel → Data → Get external data → Select all columns with Shift and choose Text.
  • The date format should be yyyy-mm-dd (for employee start date) and yyyy-mm-dd or mm-dd (for birthdays)

Groups Column Format (see template here, column F):

  • Groups is a container for grouping employees that is meaningful in the context of your HRIS system. Group names will come from one or more categories/fields. For example;  Department, Division, Job Type, Region or Location
  • The group column indicates which groups the user is part of.
  • Groups are used for activity feed filtering or for mapping to Bucketlist roles                              
  • Multiple groups can be delimited (separated) by a pipe '|',  comma ','  or semi colon ';' and wrapped in quotations.    
    • For example:  Group 1|Group ABC|Group 66. If , (comma) character is used to separate groups, the whole set of groups must be enclosed by " (double quotes) , in most cases, when your system generates a csv it inserts quotes in the group field. You do not need to explicitly add quotes in the data itself:  "Group1,Group ABC,Group 66". The group names must be exactly the same (same case, spacing etc) throughout the CSV, otherwise a different case / formatted group name would be considered a different group. 
  • Examples of acceptable Excel format below (click on the image below, see the date format for columns H and I ) :

Examples of acceptable text format below (when opened in a text editor, like Sublime text as an example):

Example #1:

"Mickey","Mouse","mickey@disney.com","02013317","Employee|Business Operations|Florida","2011-12-04","02015886"


Example #2:

"Mickey","Mouse","mickey@disney.com","02013317","Employee,Business Operations,Florida","2011-12-04","02015886"


Example #3:

Mickey,Mouse,mickey@disney.com,02013317,"Employee;Business Operations;Florida",2011-12-04,02015886



UTF-8 format:

  • UTF-8 format is required for SFTP csv synchronization.
  • Troubleshooting tips: A UTF-8 Error message is displayed whenever the csv file that is uploaded to an SFTP server is incorrectly formatted. Usually it’s an accent, or a special apostrophe or a long dash in a data point in the csv file.
  • To find the ‘utf-8’ issue:
      • Download Sublime Text (application)
      • Download the CSV file via Sublime Text
      • In Sublime Text, choose:
        • File -> Reopen with Encoding -> Utf-8
        • Find -> Find
        • Look for interrogation point (?)
      • To see the ‘real’ text, in Sublime Text:
          • File -> Reopen with Encoding -> Western (Windows 1252)
      • Adjust the format if necessary on your end
  • For any further questions, please contact your Bucketlist rep or support@bucketlistrewards.com