How to Use SFTP Uploads

New: Added support for multiple access management — up to 10 public keys per tenant.

---

What Is Headless Flatfile (HFF) and Why Would I Use It?

Headless Flatfile (HFF) lets you automatically upload and sync data into your Deputy account through a secure SFTP (Secure File Transfer Protocol) connection — without using the Deputy interface.

This is ideal for automating or bulk-loading structured data, such as:

• Employee lists and payroll data
• Training records and modules
• Location or area configurations
• Timesheets, rosters, or sales data

Each data type uses a Deputy-approved CSV template. When you drop a correctly named and formatted file into your assigned SFTP folder, it’s automatically processed and imported into your Deputy account.

Key benefits:

• Automate large or recurring data imports
• Maintain full control of data from your own systems
• Use your own preferred SFTP client or scripts
• Stay secure — no password sharing, private key authentication only

---

Prerequisites

Before you begin, make sure you have:

1. An active Deputy account with Headless Flatfile access enabled.
   • If you’re not sure, contact your Deputy representative.
2. Ability to generate SSH key pairs (public/private).
   • You’ll need to provide your public key to Deputy so it can be added to your SFTP folder.
   • Your private key stays with you — it’s how you securely connect.
3. An SFTP client or automation tool such as:
   • CyberDuck
   • FileZilla
   • WinSCP
   • Or your own code-based automation (e.g., Python or shell scripts).

Creating SSH Keys

You can generate SSH keys on most systems:

• macOS / Linux / Unix:ssh-keygen -t rsa -b 4096 -C "[email protected]"

  This creates id_rsa (private) and id_rsa.pub (public).

• Windows (PowerShell):ssh-keygen -t rsa -b 4096

Supported key types include RSA (4096-bit recommended), ECDSA, and ED25519.

For more detailed guides on this process, click here for Mac, or here for Windows.

---

Limitations and Best Practices

To ensure reliability and consistency, keep in mind the following:

• No transformations or data cleaning are applied.

  Files must strictly follow the Deputy template format and field names.

• Template file names must match exactly.

  (e.g., Employee_Sync.csv, Training_Module_Sync.csv)

• One file per template at a time.

  Don’t upload multiple files for the same template simultaneously.

• File size: up to 50,000 rows per CSV.

• Retention: files remain on the SFTP server for up to 60 days.

• Regional servers:

  • AMEA → sftp.na.deputy.com
  • EU → sftp.eu.deputy.com
  • AU → sftp.au.deputy.com

---

Connecting to Your SFTP Folder

Once your public key has been registered by Deputy, you’ll receive:

• SFTP URL (based on your region)
• Port: 22
• Username: your Deputy Tenant ID (UUID format)

Example (AU Region)

SFTP URL: sftp.au.deputy.com
Port: 22
Username: 623a8a0c-e8a6-4b7f-984a-6d0aed1c0169

To connect using CyberDuck or FileZilla:

1. Open your SFTP client.
2. Choose SFTP (SSH File Transfer Protocol).
3. Enter the provided host, port, and username.
4. For authentication, use your private key file instead of a password.

You will need to use your private key to authenticate. In your SFTP tool (like CyberDuck or FileZilla), instead of a password, select the option to use a private key file for authentication."

Upon login, you’ll see three folders:

• processing — files currently being processed
• sent_successful — files that fully synced
• sent_failed — files that encountered errors

When a template file is dropped into the root folder, we will use the Training Module template, which requires the file to be named Training_Module_Sync.csv.

The file will be automatically processed and moved to the processing folder.

After the filed processed if it is a successful sync, you will receive an email notification and data inserted into the tenant database.

---

Handling Upload Errors

If a file fails to sync, you’ll receive an email containing a magic link.

This link opens a Flatfile web interface for your Deputy account, where you can review errors, correct data, and re-submit the file.

Common reasons for failure:

• Invalid data (e.g., non-existent location or employee ID)
• Wrong file name or template
• Missing required columns
• Uploading multiple files of the same type simultaneously

---

Managing Multiple Access Keys

Each Deputy tenant can now have up to 10 public keys registered for SFTP access.

This is useful for teams that require separate access credentials for automation systems or multiple users.

You can:

• Add new keys — each key provides its own access credentials.
• Remove keys — revoke access instantly.

Keys must be unique and are managed through Deputy’s Headless Flatfile setup interface.

---

Supported Templates

---

FAQs

What is a public key?

A public key is like an open padlock. You share it with Deputy so only your corresponding private key can unlock access to your SFTP folder.

How will I know if my file succeeded or failed?

You’ll receive an email notification. Files are also sorted into folders:

• sent_successful — every row processed successfully
• sent_failed — one or more errors occurred
• processing — file is currently being handled

How do I retry a failed upload?

Use the magic link in your failure email to open and fix errors directly in the Flatfile interface, then re-submit.

Can I automate uploads?

Yes. You can script uploads from your own systems using SFTP libraries, cron jobs, or integration platforms — just use your private key for authentication.