This feature is only available for Elevated or Enterprise accounts
Pro Tip: Use the menu on the right > to skip to a particular section.
Overview
The SFTP integration is designed to keep Snappy automatically in sync with your HRIS system.
Your HRIS remains the single source of truth for employee data. Instead of managing recipients in Snappy, your system regularly exports a CSV file, and Snappy uses it to keep the recipient list up to date.
This ensures that the Snappy dashboard always reflects the current state of active employees eligible to receive gifts.
🧠 Core Concept
The integration works as a one-way data sync from your HRIS to Snappy.
Employee data is fully managed in your HRIS system
You upload (or automatically push) a CSV file on a scheduled basis (e.g. daily)
Snappy processes the file and updates recipients accordingly
Snappy continuously reflects your latest HRIS dataset
❗ Important behavior
Snappy does not allow manual edits to SFTP-managed recipients
Only employees included in your HRIS file will exist in Snappy
All updates (additions, changes, removals) are driven by your uploaded files
❌ What this is not
Not a tool for manually managing recipients in Snappy
Not a CRM or editable database
Not intended for manual corrections in the dashboard
🚀 Quick Start
How It Works
You schedule a file upload via SFTP
Snappy processes the file automatically
Recipients are added, updated, or removed
To get started:
Get your SFTP credentials from Snappy or provide your own server
Prepare a CSV file following the format below
Use a unique file name (example: snappy_20250128_153045.csv)
Upload the file
Check processing results via the recipients page
🔐 Setup
Option 1: Snappy SFTP Server (Recommended)
Server: sftp.snappygifts.com
Port: 22
Authentication:
SSH key (recommended)
Or public key (ssh-rsa format)
Steps:
Generate or provide a public key
Connect your HRIS or SFTP client
Upload a sample CSV file
Snappy validates and provides feedback if needed
Once approved, Snappy maps columns and activates sync
Option 2: Your Own SFTP Server
You will provide:
Server address (IP or hostname)
Protocol and port (SFTP/FTPS)
Credentials (username and password)
Permissions (read/write/delete)
Directory path
Optional IP allowlisting
Snappy will:
Connect securely to your server
Set up folder structure
Validate your file
Run initial sync
🔐 How to Enable SFTP and Access Credentials
Follow these steps to enable SFTP and retrieve your credentials in Snappy:
Enable SFTP
From the top header, click the dropdown next to your initials
Select General
In the left sidebar, click Sharing and Access
Toggle SFTP Access
Activation may take a few seconds
Once enabled:
A username is automatically generated
It will appear on the same page
🔑 Generate SFTP Key (Snappy-managed option)
If using Snappy-generated keys:
Click Generate Key
A private key will be created
Copy and securely store it immediately
⚠️ The key will not be shown again.
You can:
Delete unused keys anytime
Generate new keys if needed (no cost)
Remove inactive keys for security
⬆️ Upload Path (Snappy SFTP Server)
/snappy-sftp-prod/[username]/recipients/roster/uploads/
Only files placed in this path will be processed.
Important Notes
Only one file is processed at a time
Multiple files in the folder may cause skipping or delays
Always ensure files are placed in the
uploads/directory
📅 Date Format Requirements
All date fields must use a consistent format within the same file.
Applies to:
Birthday
Working Since (Hire Date)
Supported formats (choose ONE per file):
YYYY-MM-DD (recommended)
MM-DD-YYYY
DD-MM-YYYY
Rules:
Do not mix formats within the same file
Inconsistent formatting may lead to processing errors
Ensure HRIS exports are standardized before upload
📁 Folder Structure
recipients/
├── roster/
├── add-and-update/
└── delete/
Each folder contains:
uploads/ processed-uploads/ processed-uploads-success/ processed-uploads-failed/ uploads-errors/
⚠️ Always upload files into the uploads/ folder.
📄 File Requirements
CSV format only
UTF-8 encoding recommended
One recipient per row
Must include headers
File name must be unique
Recommended format: snappy_YYYYMMDD_HHMMSS.csv
Example: snappy_20250128_153045.csv
🧾 Field Requirements
First Name – Required
Last Name – Required
Employee ID – Required (unique identifier)
Email – Required
Phone – Optional (required for SMS)
Birthday – Optional
Working Since – Required
Country – Required (ISO 2-letter code)
Accounts – Optional
Department – Optional
📊 Example CSV Structure
First Name | Last Name | Employee ID | Phone | Birthday | Working Since | Country | Accounts | Department | |
First | Last | 12345 | +1123456789 | YYYY-MM-DD | YYYY-MM-DD | US | CA Office | R&D |
🔄 Upload Modes
Roster Mode (HRIS Sync Mode)
Roster mode is the recommended and most common setup for SFTP integrations.
It is designed for organizations that continuously sync employee data from their HRIS system.
🧠 Concept
Each file represents the full current state of your workforce.
Snappy compares your latest HRIS export to the existing dataset and automatically aligns the two.
📊 How it works
First sync (initial upload)
All valid employees in the file are added to Snappy
No deletions occur
Failed rows are reported separately
Ongoing syncs (daily or scheduled files)
For every new file:
Employees in the file → added or updated in Snappy
Employees missing from the file → removed from Snappy
Invalid rows → excluded with error reporting
🧭 Important behavior
Snappy always mirrors the HRIS dataset
The latest file fully defines the active employee list
No manual edits in Snappy override this state
💡 Recommended usage
Run a daily automated export from your HRIS
Upload it to SFTP (or push via automation)
Let Snappy continuously reflect your active workforce
Other modes (not recommended)
Add & Update Mode
Adds new recipients
Updates existing recipients
Does not remove recipients
Delete Mode
Removes recipients included in file.
Required identifier:
Email OR External ID OR Phone OR First Name + Birthday
🏢 Account Mapping
Option 1: All Accounts
Make sure to have a column for “accounts” and populate “all accounts” for all recipients.
Alternatively, you can simply omit the accounts column.
Option 2: Sub-Accounts (Recommended)
Under the accounts column, write the sub-account names as they are in the Snappy dashboard. For example: “CA Office”.
Use when:
Departments are separated
Budgets differ per group
Multiple admins manage sub-accounts
Option 3: Exact Account Names (Multiple accounts)
You can also select multiple accounts per recipient. For example: “California Employees, NY Office”. Use a comma to separate the account names.
⏱️ File Processing Schedule
Snappy automatically checks the designated SFTP upload locations on an hourly basis.
Sync window:
7:00 AM – 3:00 PM EST
4:00 AM – 12:00 PM PST
During this window, Snappy will:
Scan configured SFTP directories every hour
Detect new or updated files in the
uploads/foldersProcess eligible files automatically
Generate success and error reports
Important notes
Only files placed in the correct
uploads/directory will be processedIf multiple files are present, processing order is not guaranteed
Files should be fully written before they appear in the folder to avoid partial ingestion
📦 Processing Results
Success: processed-uploads-success/
Failed rows: processed-uploads-failed/
File errors: uploads-errors/
⚠️ Common Issues
Not using CSV format
Reusing file names
Missing required fields
Incorrect phone format
Uploading to wrong folder
Changing structure without updating mapping
🔐 Security
We follow industry best practices to ensure your data is transferred and stored securely.
Secure transfer (SFTP)
All files are transferred using the SFTP (Secure File Transfer Protocol), which encrypts data in transit and protects it from unauthorized access.
Secure storage (AWS)
Files are stored securely on AWS infrastructure, which includes built-in protections such as encryption at rest and strict access controls.
Optional PGP encryption
For an additional layer of security, we support PGP encryption. With this setup, files are encrypted before being uploaded and can only be decrypted by Snappy after transfer.
To enable PGP encryption, please contact Snappy Support.
⚠️ Limitations
Maximum 50,000 recipients per file
🔄 Frequently Asked Questions
What happens if multiple files are uploaded?
What happens if multiple files are uploaded?
Only one file is processed at a time. If multiple files exist in the uploads folder - the process won’t run. This is a rare edge case that might happen during initial setup and is less likely to happen after the setup is completed.
Can file structure change after setup?
Can file structure change after setup?
Yes, but Snappy support must update mapping.
What happens if a file fails?
What happens if a file fails?
A failure report is generated with row-level error details. The report is available to the Snappy support team. If you suspect something is wrong with the number of recipients on your Snappy dashboard, please contact us so we can check it.
Do I need to manually update recipients?
Do I need to manually update recipients?
No. Everything is fully automated after setup. You only manage and update the recipients in your HRIS platform.
Are formats other than CSV supported?
Are formats other than CSV supported?
No. Only CSV files are supported.
What happens if a recipient appears in multiple files?
What happens if a recipient appears in multiple files?
Roster mode: latest file overrides previous state
Add/update mode: incremental updates applied
🛠 Need Help?
Contact Snappy Support (help@snappy.com) for:
Mapping changes
Upload issues
Account configuration