SFTP Instructions

This page provides detailed SFTP operation instructions for each entity type. Select the section that matches your organization's setup.


Single Entity (SE)

Overview of the directory structure

TEXT
/
└── {CompanyID}/
    ├── employees/
    │   ├── download/
    │   │   └── eligible-list.zip
    │   └── upload/
    │       ├── all/
    │       ├── error-details/
    │       │   ├── {Timestamp}-{Uploaded-Filename}.csv
    │       │   └── ...
    │       ├── leavers/
    │       ├── new/
    │       └── status.csv
    ├── payroll/
    │   ├── YYYYMM_wellhub_payroll_deduction.csv
    │   ├── ...
    │   ├── leavers/
    │   │   ├── YYYYMM_wellhub_partial_payroll_deduction.csv
    │   │   └── ...
    │   └── ...
    └── reports/
        └── gympass-year-report.zip

Employees

Through the SFTP Server, you can manage the employees of a specific company. Some supported operations are:

  • Full file - Update the entire employee base.
  • Newcomers - Add new employees.
  • Leavers - Remove former employees.
  • Download eligible list - Download the list of registered employees.
  • Upload history (status.csv) - Download the status of uploads.
  • Error details - Get the details for errors found during an upload and what's required to address them.

For details on eligibility fields and file requirements, see the Eligibility via SFTP guide.

Overview of the employees directory structure

TEXT
/
└── {CompanyID}/
    ├── employees/
    │   ├── download/
    │   │   └── eligible-list.zip
    │   └── upload/
    │       ├── all/
    │       ├── error-details/
    │       │   ├── {Timestamp}-{Uploaded-Filename}.csv
    │       │   └── ...
    │       ├── leavers/
    │       ├── new/
    │       └── status.csv
    └── ...
  • The initial directory is the root /.
  • /{CompanyID} is the directory representing the company being managed. The directory name is the UUID of the company.
  • /{CompanyID}/employees is the directory where we can manage the employees of this company, for organizational purposes.
  • /{CompanyID}/employees/upload/all is the directory where we can update the employee base by uploading a Full file.
  • /{CompanyID}/employees/upload/new is the directory where we can update the employee base by uploading a Newcomers file.
  • /{CompanyID}/employees/upload/leavers is the directory where we can update the employee base by uploading a Leavers file.
  • /{CompanyID}/employees/upload/status.csv is the file where we can download and view the status of each upload.
  • /{CompanyID}/employees/upload/error-details is the directory where we can download the errors of a rejected upload.
  • /{CompanyID}/employees/upload/{Timestamp}-{Uploaded-Filename}.csv is the error report of a specific upload.
  • /{CompanyID}/employees/download/eligible-list.zip is the file where we can download and view the list of employees for this company.

Upload a Full file

Once connected to the SFTP server, you'll be able to manage all of the employees data. This includes adding, removing, and editing employee records within the file.

Attention

Since "Fullfile" is a replace operation, it requires extra attention.

The SFTP Server expects the "Full file" to contain all the employees already registered for the company. Any employee that is in the database but not in the file will be removed from the database. Any employee that exists in the database but cannot be identified in the file by the SFTP Server will be removed from the database. For example, if the SFTP Server knows an employee by the name of "Ciara Walter" through the email "ciara.walter@coolcompany.com," but this email is spelled incorrectly in the file, the SFTP Server will not be able to identify this employee in the database, and they will be removed. Employees found in the file but not in the database will be added. Employee records present in both the file and the database will be updated with any changes found in the file.

Note: Although it's possible to remove employees by uploading a "Fullfile", it's not possible to remove all employees using this method.

  1. Navigate to the /{CompanyID}/employees/upload/all directory for this company.
BASH
cd /{CompanyID}/employees/upload/all
  1. Upload the all-employees.csv file and replace the existing one with your file containing the full list of employees for a company.
BASH
put all-employees.csv
File Organization
Example file - all-employees.csv
NameEmailNational IDEmployee IDDepartmentPayroll IDCost centerOffice zip codePayroll Enabled
Freyja Obrienfreyja.obrien@coolcompany.com257.573.080-52331234UX13241-114-87304571-926Yes
Ciara Walterciara.walter@coolcompany.com700.594.980-30834372Engineering73751-114-77304571-926No

Upload a Newcomers file

Once connected to the SFTP Server, we can then add new employees.

  1. Navigate to the /{CompanyID}/employees/upload/new directory for this company.
BASH
cd /{CompanyID}/employees/upload/new
  1. Upload the new-employees.csv file. Replace new-employees.csv with your file containing the list of new employees.
BASH
put new-employees.csv
File Organization
Example file - new-employees.csv
NameEmailNational IDEmployee IDDepartmentPayroll IDCost centerOffice zip codePayroll Enabled
Freyja Obrienfreyja.obrien@coolcompany.com257.573.080-52331234UX13241-114-87304571-926Yes
Ciara Walterciara.walter@coolcompany.com700.594.980-30834372Engineering73751-114-77304571-926No

Upload a Leavers file

Once connected to the SFTP Server, we can remove existing employees.

  1. Navigate to the /{CompanyID}/employees/upload/leavers directory for this company.
BASH
cd /{CompanyID}/employees/upload/leavers
  1. Upload the remove-employees.csv file. Replace employees.csv with your file containing the list of employees to be removed.
BASH
put remove-employees.csv

Download the status file

Once connected to the SFTP Server, we can download the status of the most recent uploads. This is very useful for checking if a specific upload was successful or if it failed.

  1. Navigate to the /{CompanyID}/employees/upload directory for this company.
BASH
cd /{CompanyID}/employees/upload
  1. Download the status.csv file.
BASH
get status.csv
File Organization

It contains information about the status of the last 20 uploads (regardless of their source).

filenamebatch_typedate_and_timeprocessing_statussource
Composition between the timestamp and the uploaded file nameUpload type, can be: full_file, newcomers or leavers (exclusive to single entities)Date and time when the upload occurredStatus can be: Validating, Validated, Pending, Processing, Succeeded, Succeeded with errors (exclusive to channel partners), Rejected, Deleted, Approval_RequestedSource of the upload, can be SFTP or W4C

Download the error details

Once connected to the SFTP Server, you can download the files with error details of a rejected upload. For example, you uploaded a Fullfile, checked the status.csv, and saw that this upload failed. You can check the reason for the failure using the error details.

  1. Navigate to the /{CompanyID}/employees/upload/error-details directory for this company.
BASH
cd /{CompanyID}/employees/upload/error-details
ls
  1. List the available error files.
BASH
ls
  1. Download the error details file.
BASH
get {Timestamp}_{Uploaded file name}.csv
File Organization

It contains information about the type of error and where the error is.

Company Tax IDError SourceLine IDNameError TypeError Description
N/AThis refers at what level the error occurred: Upload error or Client error - impacted the whole file, Input error - refers to line errorsThe line # will be displayed if applicable to the Error Source + TypeThe impacted field will be displayed if applicable to the Error Source + TypeThis refers to the type of error foundWill explain in detail what needs to be addressed

Download the eligible list file

Once connected to the SFTP Server, we can then download the complete list of employees for the company. With this file you'll both be able to list all the existing employees in a company, as well as use that as a base to add or remove employees for a "Fullfile" operation.

  1. Navigate to the /{CompanyID}/employees/download directory for this company.
BASH
cd /{CompanyID}/employees/download
  1. Download the eligible-list.zip file. Extract the zip file to access the list.
BASH
get eligible-list.zip

Payroll

Through the SFTP Server, you can download the payroll information for the employees in a specific company. Some supported operations are:

  • Deduction file - Download existing payroll files for a specified date range.
  • Deduction file for leavers - Download any existing payroll files for employees who have been removed.
Note

Only employees with payroll enabled will appear in the payroll files.

Get to know more regarding Payroll on the Payroll section.

Overview of the payroll file structure

TEXT
/
└── {CompanyID}/
    ├── employees/
    ├── payroll/
    │   ├── leavers/
    │   │   ├── YYYYMM_wellhub_partial_payroll_deduction.csv
    │   │   └── ...
    │   ├── YYYYMM_wellhub_payroll_deduction.csv
    │   └── ...
    └── ...
  • The initial directory is the root /.
  • /{CompanyID} is the directory representing the company being managed. The directory name is Wellhub's UUID for the company.
  • /{CompanyID}/payroll is the directory where the payroll files are available for download.
  • /{CompanyID}/payroll/YYYYMM_wellhub_payroll_deduction.csv is a payroll file. The name consists of a timestamp (for sorting purposes), the start and end dates of the period, and the UUID of the invoice.
  • /{CompanyID}/payroll/leavers/YYYYMM_wellhub_partial_payroll_deduction.csv is a payroll file for removed employees. The name consists of a timestamp and an invoice's UUID.

Download payroll files

Once connected to the SFTP Server, we can download the available payroll files for this company.

  1. Navigate to the /{CompanyID}/payroll/ directory for this company.
BASH
cd /{CompanyID}/payroll
  1. Download a payroll file.
BASH
get YYYYMM_wellhub_payroll_deduction.csv
File Organization
Example file - YYYYMM_wellhub_payroll_deduction.csv
Full nameEmailNational IDEmployee IDAmount dueDepartmentCost centerOffice zip codePayroll ID
Freyja Obrienfreyja.obrien@coolcompany.com257.573.080-52331234R$ 449,90UX132404571-9261324
Ciara Walterciara.walter@coolcompany.com700.594.980-30834372R$ 449,90Engineering737504571-9267375

Download payroll files of removed employees

Once connected to the SFTP Server, we can download the payroll files for employees who have been removed from this company.

  1. Navigate to the /{CompanyID}/payroll/leavers/ directory for this company.
BASH
cd /{CompanyID}/payroll/leavers
  1. Download a payroll file.
BASH
get YYYYMM_wellhub_partial_payroll_deduction.csv

Reports

Through the SFTP Server, you can download usage data for the employees of a specific company. This is important to track employee engagement with the Wellhub services.

Overview of the reports file structure

TEXT
/
└── {CompanyID}/
    ├── employees/
    ├── payroll/
    └── reports/
        └── wellhub-year-report.zip
  • The initial directory is the root /.
  • /{CompanyID} is the directory representing the company being managed. The directory name is the UUID of the company.
  • /{CompanyID}/reports/wellhub-year-report.zip is the report file for the usage of employees for this company.

Download report file

Once connected to the SFTP Server, you can then download any available reports for this company.

  1. Navigate to the /{CompanyID}/reports/ directory for this company.
BASH
cd /{CompanyID}/reports
  1. Download the yearly usage report file.
BASH
get gympass-year-report.zip
File Organization

File name: start date + end date + report name + wellhub. Example: 20231209-20241209_subscription-history-wellhub.csv.

The reports contain information from the last 12 months on:

  • Engagement rates: A daily snapshot of the total number of eligibles, members, subscribers, and family-members (if applicable).
  • Check-ins: A full list of the check-ins in Wellhub partners, for both physical and virtual activities. Includes family-member data (if applicable).
  • Subscribers snapshot: A full list of the subscribers and their subscription details, including the plan selected and its price. Includes family-member data (if applicable).
  • Subscription history: A full list of transaction events related to an employee's subscription, such as: first subscription, upgrade, downgrade, pause, cancellation, and new subscription. Includes family-member data (if applicable).

Multi Entity (ME)

Overview of the file structure

File Structure

TEXT
/
├── multientity/
│   ├── employees/
│   │   ├── download/
│   │   │   └── {Timestamp}_Eligible-list.csv
│   │   └── upload/
│   │       ├── all/
│   │       ├── error-details/
│   │       │   ├── {Timestamp}-{Uploaded-Filename}.csv
│   │       │   └── ...
│   │       └── status.csv
│   └── payroll/
│       ├── leavers/
│       │   ├── {company name (single entity)}_YYYYMM_wellhub_partial_payroll_deduction.csv
│       │   └── ...
│       ├── {company name (single entity)}_YYYYMM_wellhub_payroll_deduction.csv
│       └── ...
└── reports/
        └── {start date}-{end date}_SUBSCRIPTION-HISTORY.zip
        └── {start date}-{end date}_SUBSCRIBERS-SNAPSHOT.zip
        └── {start date}-{end date}_CHECK-INS.zip
        └── {start date}-{end date}_ADOPTION-OVER-TIME.zip

Employees

Through the SFTP Server, you can manage the employees of multiple companies at the same time. It's simple: include on the file all the tax ids you want to send updates for, and we will update the base accordingly. Note: If a given tax id isn't included on the upload, its eligible base will remain unchanged.

Some supported operations are:

  • Full file - Update the entire employee base.
  • Download eligible list - Download the list of registered employees.
  • Upload history (status.csv) - Download the status of uploads.
  • Error details - Get the details for the errors found during an upload and what's required to address them.

Overview of the employees' directory structure

Directory Structure
TEXT
/
├── multientity/
│   ├── employees/
│   │   ├── download/
│   │   │   └── {Timestamp}_Eligible-list.csv
│   │   └── upload/
│   │       ├── all/
│   │       ├── error-details/
│   │       │   ├── {Timestamp}-{Uploaded-Filename}.csv
│   │       │   └── ...
│   │       └── status.csv
│   └── payroll/
└── ...
  • The initial directory is the root /.
  • /multientity is the directory representing all companies being managed.
  • /multientity/employees/upload/all is the directory where you can update the employee base by uploading a Fullfile file.
  • /multientity/employees/upload/error-details is the directory with the rejected upload error report.
  • /multientity/employees/upload/error-details/{Timestamp}-{Uploaded-Filename}.csv is the error report of a specific upload.
  • /multientity/employees/upload/status.csv is the file where you can download and view the status of each upload.
  • /multientity/employees/download/{Timestamp}_Eligible-list.csv is the file where you can download and view the list of employees.

Upload a Fullfile file

Once connected to the SFTP Server, we can replace the employees base of all companies in the same time. In other words, we can add, remove, and edit employees in the same file.

Attention!

Since Fullfile is a replace operation, it requires extra attention.

The SFTP Server expects the Fullfile to contain all the employees already created for the companies (if there is a company/tax id that doesn't have changes, you don't need to include it on the file). For the companies/tax ids in the file, a given employee who was part of the database and isn't now part of the file, will be removed. The employees that are new entries, will be added accordingly. For employees found in both the file and the database, will be edited if any of their fields were changed.

Note: Even though it is possible to remove employees by uploading a Fullfile, it's not possible to remove all employees (as there's a safety threshold; if this is surpassed we will throw the 'Database wipe' error and reject the upload).

  1. Navigate to the /multientity/employees/upload/all.
BASH
cd /multientity/employees/upload/all

The command below uploads the all-employees.csv file. Replace all-employees.csv with your file containing the list of employees.

BASH
put all-employees.csv
File Organization
Example file - all-employees.csv
Company Tax IDNameEmailNational IDEmployee IDDepartmentPayroll IDCost centerOffice zip codePayroll Enabled
37.211.173/0001-69Phoebe Bridgersmaxinethedog@bridgers.com764.254.640-89331234UX13241-114-87304571-926Yes
37.211.173/0001-69Lucy Dacusdacus@modigliani@com151.846.620-65834372Engineering73751-114-77304571-926No

Download the status file

Once connected to the SFTP Server, you can download the status of the most recent uploads. This is very useful for checking if a specific upload was successful or rejected.

  1. Navigate to the /multientity/employees/upload directory.
BASH
cd /multientity/employees/upload
  1. The command below downloads the status.csv file.
BASH
get status.csv
File Organization

It contains information about the status of the last 20 uploads (regardless of their source).

filenamebatch_typedate_and_timeprocessing_statussource
Composition between the timestamp and the uploaded file nameUpload type, can be: full_file, newcomers or leavers (exclusive to single entities)Date and time when the upload occurredStatus can be: Validating, Validated, Pending, Processing, Succeeded, Succeeded with errors (exclusive to channel partners), Rejected, Deleted, Approval_RequestedSource of the upload, can be SFTP or W4C

Download the error details

Once connected to the SFTP Server, you can download the files with error details of a rejected upload. For example, you uploaded a Fullfile, checked the status.csv, and saw that this upload failed. You can check the reason for the failure using the error details.

  1. Navigate to the /multientity/employees/upload/error-details directory. And display the list of error details.
BASH
cd /multientity/employees/upload/error-details
ls
  1. The command below downloads the error details file.
BASH
get {Timestamp}_{Uploaded file name}.csv
File Organization

It contains information about the type of error and where the error is.

Company Tax IDError SourceLine IDNameError TypeError Description
Points out which client had issuesThis refers at what level the error occurred: Upload error - impacted the whole file, Client error - caused by a specific entity, Input error - refers to line errorsThe line # will be displayed if applicable to the Error Source + TypeThe impacted field will be displayed if applicable to the Error Source + TypeThis refers to the type of error foundWill explain in detail what needs to be addressed

Download the eligible list file

Once connected to the SFTP Server, it is possible to download the complete list of employees. This file enables listing all existing employees, which can be used as a reference to add or remove employees when performing a "Full file" operation.

  1. Navigate to the /multientity/employees/download directory for this company.
BASH
cd /multientity/employees/download
  1. Download the {Timestamp}_Eligible-list.csv file.
BASH
get {Timestamp}_Eligible-list.csv

Payroll

Through the SFTP Server, you can download payroll information for the employees. Some supported operations are:

Deduction file - Download existing payroll files for the latest billing cycle. Deduction file for leavers - Download any existing payroll files for employees who have been removed (during the latest billing cycle). Note: Only employees with payroll enabled (field: "Payroll Enabled: Yes") will appear in the payroll files. There will be a file per company inside the .zip. The latest deduction file replaces the previous, therefore these won't be listed.

Overview of the payroll file structure

File Structure
TEXT
/
├── multientity/
│   ├── employees/
│   └── payroll/
│       ├── leavers/
│       │   ├── {company name (single entity)}_YYYYMM_wellhub_partial_payroll_deduction.csv
│       │   └── ...
│       ├── {company name (single entity)}_YYYYMM_wellhub_payroll_deduction.csv
│       └── ...
└── ...
  • The initial directory is the root /.
  • /multientity is the directory representing all companies being managed.
  • /multientity/payroll is the directory where you can download the payroll files.
  • /multientity/payroll/{company name (single entity)}_YYYYMM_wellhub_payroll_deduction.csv is a payroll file. The name consists of the company name, the start and end dates of the period, and the UUID of the invoice.
  • /multientity/payroll/leavers/{company name (single entity)}_YYYYMM_wellhub_partial_payroll_deduction.csv is a payroll file for removed employees. - The name is similar to the general payroll file, but with "partial".

Download payroll files

Once connected to the SFTP Server, you can download the available payroll files.

  1. Navigate to the /multientity/payroll directory.
BASH
cd /multientity/payroll
  1. The command below downloads a payroll file.
BASH
get {company name (single entity)}_YYYYMM_wellhub_payroll_deduction.csv
File Organization
Example file - {company name (single entity)}_YYYYMM_wellhub_payroll_deduction.csv
Full NameEmailNational IDEmployee IDAmount dueDepartmentCost centerOffice zip codePayroll ID
Phoebe Bridgersmaximehedog@bridgers.com764.254.640-89331234R$ 449,90UX1-114-87304571-9261324
Lucy Dacusdacus@modigliani@com151.846.620-65834372R$ 449,90Engineering1-114-77304571-9261375

Download payroll files of removed employees

Once connected to the SFTP Server, you can download payroll files of employees who have been removed.

  1. Navigate to the /multientity/payroll/leavers directory.
BASH
cd /multientity/payroll/leavers
  1. The command below downloads a payroll file.
BASH
get {company name (single entity)}_YYYYMM_wellhub_partial_payroll_deduction.csv

Reports

Through the SFTP Server, you can download usage data for the employees of a specific company. This is important to track employee engagement with the Wellhub services. Inside each .zip you will find a file per client under the multi entity structure.

Overview of the reports file structure

File Structure
TEXT
/
└── multientity/
    └── reports/
        └── {start date}-{end date}_SUBSCRIPTION-HISTORY.zip
        └── {start date}-{end date}_SUBSCRIBERS-SNAPSHOT.zip
        └── {start date}-{end date}_CHECK-INS.zip
        └── {start date}-{end date}_ADOPTION-OVER-TIME.zip

Download report file

Once connected to the SFTP Server, you can then download any available reports for the group.

  1. Navigate to /multientity/reports/ directory.
BASH
cd /multientity/reports/
  1. The command below downloads the yearly usage report file.
BASH
get  {start date}-{end date}_SUBSCRIPTION-HISTORY.zip
File Organization

Detailed directories: <start date>-<end date>_<report name>.zip Example: 2024-07-01-2025-07-01_SUBSCRIPTION-HISTORY.zip

File naming: Clientname_<start date>-<end date>_<report name>-wellhub.csv Example: Client1_2024-07-01-2025-07-01_subscription-history-wellhub.csv

The reports contain information from the last 12 months on:

  • Engagement rates: A daily snapshot of the total number of eligibles, members, subscribers, and family-members (if applicable).
  • Check-ins: A full list of the check-ins in Wellhub partners, for both physical and virtual activities. Includes family-member data (if applicable).
  • Subscribers snapshot: A full list of the subscribers and their subscription details, including the plan selected and its price. Includes family-member data (if applicable).
  • Subscription history: A full list of transaction events related to an employee’s subscription, such as: first subscription, upgrade, downgrade, pause, cancellation, and new subscription. Includes family-member data (if applicable).

Flexible Benefits

Flexible Benefits allow multi entities to upload credits for their clients, allowing a company's employees to allocate the credits to those that best suit their individual needs. For an employee to be eligible for credits, they need to be created in the eligibility flow.

Contrary to the eligibility flow, partial uploads are accepted. This means that, by default, the correct lines will be created; and the ones with errors will be rejected. Every time a full or partial rejection happens, the multi entity admins will be notified via email.

Overview of the credits file structure

Directory Structure
TEXT
/
├── multientity/
│   └── flexben/
│       └── upload/
│           ├── add-or-update/
│           ├── removal/
│       └── download/
│           ├── upload_history.csv/
│           ├── errors/
│           │   ├── {Timestamp}-{Uploaded-Filename}.csv
│           │   └── ...
│           └── beneficiaries-list.csv
  • The initial directory is the root /.
  • /multientity is the directory representing all companies under the multi entity's structure.
  • /multientity/flexben/upload/add-or-update is the directory to use if you need to create new credits and/or update existing ones.
  • /multientity/flexben/upload/removal should be used to delete credits.
  • /multientity/flexben/download/upload_history.csv is the file containing the status of the latest uploads.
  • /multientity/flexben/download/errors/ is the directory containing the failed upload error report.
  • /multientity/flexben/download/errors/{Timestamp}-{Uploaded-Filename}.csv is the error report referring to a specific upload.
  • /multientity/flexben/download/beneficiaries-list.csv/ will download the snapshot of credited employees.

Manage the credits

There are two types of uploads available:

  • Add or update - a file that will create new credits or edit existing ones
  • Removal - a file that will delete existing credits

Upload an Add/Update credits file

  1. Navigate to the /multientity/flexben/upload/add-or-update/.
BASH
cd /multientity/flexben/upload/add-or-update/
  1. The command below uploads the .csv file, creating the new credit entries and updating the existing ones.
BASH
put credit-employees.csv
File Organization
Example file - credit-employees.csv
Company Tax IDEmailNational IDEmployee IDAmountLast Credited MonthLast Credited Year
1916628000102david.smith+fbstg01@wellhub.com10122025
1916628000102elena.silva+fbstg30002@wellhub.com100122025
120691930001165942790906459427909064-050122025
120691930001167020286003570202860035-145122025
120691930001163738539107970202860035-275122025
120691930001162098232306970202860035-330122025

Upload a Credits removal file

Navigate to the /multientity/flexben/upload/removal/.

BASH
cd /multientity/flexben/upload/removal/
  1. The command below uploads the .csv file, deleting the credits.
BASH
put credits-removal.csv
File Organization
Example file - credits-removal.csv
Company Tax IDEmailNational IDEmployee ID
1916628000102elena.silva+fbstg30002@wellhub.com5942790906459427909064-0
120691930001167020286003570202860035-1

Download the status file

You can download the status of the most recent uploads. This is very useful for checking if a specific upload was successful or failed. This file will contain the last 40 uploads (regardless of the method - W4C or SFTP), sorted by date.

  1. Navigate to the /multientity/flexben/download/upload_history.csv directory.
BASH
cd /multientity/flexben/download/upload_history.csv
  1. The command below downloads the upload_history.csv file.
BASH
get upload_history.csv
File Organization
Example file - upload_history.csv
File nameUpload date + timeTypeMethodStatusAuthor# Errors
1740767257-INTERNAL [Flexible Benefits x SFTP] Dry-run - PROD #11.csv2025-02-28 17:12:37.820047 +0000 UTCCANCELSFTPSUCCEEDED01JNGQ2EXFFESN9B2MPM6CKK790
1740762701-INTERNAL [Flexible Benefits x SFTP] Dry-run - PROD #11.csv2025-02-28 17:11:41.476435 +0000 UTCADDSFTPSUCCEEDED01JNGQ2EXFFESN9B2MPM6CKK792
1740762492-INTERNAL [Flexible Benefits x SFTP] Dry-run - PROD #11.csv2025-02-28 17:08:12.544859 +0000 UTCCANCELSFTPREJECTED01JNGQ2EXFFESN9B2MPM6CKK790
1740762163-INTERNAL [Flexible Benefits x SFTP] Dry-run - PROD #10.csv2025-02-28 17:02:43.171987 +0000 UTCADDSFTPSUCCEEDED01JNGQ2EXFFESN9B2MPM6CKK795

Download the error details

You can download the error details of a failed upload. For example, you uploaded a credits file, checked the upload_history.csv and saw that this upload was rejected. Through the error details, you can check the reason for the failure.

  1. Navigate to the /multientity/flexben/download/errors/ directory. And display the list of error details.
BASH
cd /multientity/flexben/download/errors/
ls
  1. The command below downloads the credit-employees.csv file.
BASH
get 1736255395-credit-employees.csv
File Organization
Example file - <timestamp>-credit-employees.csv
Company Tax IDLineNameError TypeError report
10.516.8291Credit amountInvalidMake sure the amount is a numeric value in the format 100.00 (separated with a '.').
1895858800001563E-mailMissingMissing field: Fill in all required fields.
669038310001815Last credited monthInvalidMake sure the credited month is the same or higher than the current date.
6690383100018113Employee idUnknownUnknown employee: Make sure they are eligible under a company tax id and that their details are up-to-date.

Download the beneficiaries list

You can download a snapshot of the credited employees from a given multi entity.

  1. Navigate to the /multientity/flexben/download/beneficiaries-list.csv directory.
BASH
cd /multientity/flexben/download/beneficiaries-list.csv
ls
  1. The command below downloads the beneficiaries-list.csv file.
BASH
get beneficiaries-list.csv
File Organization
Example file - beneficiaries-list.csv
Company Tax IDEmailNational IDEmployee IDAmountLast Credited MonthLast Credited Year
12069193000116111110101.0042025
12069193000116111138300.00112025
12069193000116111125100.0082025
12069193000116111102300.0052025
12069193000116111126300.0092025
1206919300011611110315.0062025

Channel Partners (CP)

Overview of the directory structure

TEXT
/
└── channelpartner/
    ├── employees/
    │   ├── download/
    │   │   └── {Timestamp}_Eligible-list.csv
    │   └── upload/
    │       ├── all/
    │       ├── error-details/
    │       │   ├── {Timestamp}-{Uploaded-Filename}.csv
    │       │   └── ...
    │       └── status.csv
    └── flexben/
        ├── upload/
        │   ├── add-or-update/
        │   └── removal/
        └── download/
            ├── upload_history.csv/
            ├── errors/
            │   ├── {Timestamp}-{Uploaded-Filename}.csv
            │   └── ...
            └── beneficiaries-list.csv

Employees

Through the SFTP Server, you can manage the employees of multiple companies at the same time. Some supported operations are:

  • Full file - Update the entire employee base.
  • Download eligible list - Download the list of registered employees.
  • Upload history (status.csv) - Download the status of uploads.
  • Error details - Get the details for the errors found during an upload and what's required to address them.

Overview of the employees directory structure

TEXT
/
└── channelpartner/
    └── employees/
        ├── download/
        │   └── {Timestamp}_Eligible-list.csv
        └── upload/
            ├── all/
            ├── error-details/
            │   ├── {Timestamp}-{Uploaded-Filename}.csv
            │   └── ...
            └── status.csv
  • The initial directory is the root /.
  • /channelpartner is the directory representing all companies under the channel partner's structure.
  • /channelpartner/employees/upload/all is the directory to use if you need to update the employee database by uploading a "Fullfile" file.
  • /channelpartner/employees/upload/error-details is the directory containing a failed upload error report.
  • /channelpartner/employees/upload/error-details/{Timestamp}-{Uploaded-Filename}.csv is the error report referring to a specific upload.
  • /channelpartner/employees/upload/status.csv is the file containing the status of the latest uploads.
  • /channelpartner/employees/download/{Timestamp}_Eligible-list.csv is the file where you can download and view the list of employees.

Upload a Fullfile file

Once connected to the SFTP server, you'll be able to manage all of the employees' data. This includes adding, removing, and editing employee records within the file. Depending on the error type, the file can be:

  • Rejected (status: rejected) - in this case, the full file needs to be corrected and resubmitted (keeping all entries)
  • Partially rejected (status: succeeded with errors) - in this case, the reseller only needs to address the clients/tax IDs with issues; the remaining lines will be created with success (if no actions are performed, the entries with issues will be ignored).

Every time a full or partial rejection happens, the channel partner admins will be notified via email.

Attention!

Since Fullfile is a replace operation, it requires extra attention.

The SFTP Server expects the Fullfile to contain all the employees already created for the companies (if there is a company/tax id that doesn't have changes, you don't need to include it in the file).

For the companies/tax ids in the file, a given employee who was part of the database and isn't now part of the file, will be removed. The employees that are new entries, will be added accordingly. For employees found in both the file and the database, will be edited if any of their fields were changed.

Note: Even though it is possible to remove employees by uploading a Fullfile, it's not possible to remove all employees (as there's a safety threshold; if this is surpassed we will throw the 'Database wipe' error and reject the upload).

  1. Navigate to the /channelpartner/employees/upload/all.
BASH
cd /channelpartner/employees/upload/all
  1. The command below uploads the all-employees.csv file and replaces the existing one with your file, containing the full list of employees for the companies enclosed.
BASH
put all-employees.csv
File Organization
Example file - all-employees.csv
Company Tax IDNameEmailNational IDEmployee IDDepartmentPayroll IDCost centerOffice zip codePayroll Enabled
37.211.173/0001-69Phoebe Bridgersmaxinethedog@bridgers.com764.254.640-89331234UX13241-114-87304571-926Yes
37.211.173/0001-69Lucy Dacusdacus@modigliani@com151.846.620-65834372Engineering73751-114-77304571-926No

Download the status file

Once connected to the SFTP Server, we can download the status of the most recent uploads. This is very useful for checking if a specific upload was successful or failed.

  1. Navigate to the /channelpartner/employees/upload directory.
BASH
cd /channelpartner/employees/upload
  1. The command below downloads the status.csv file.
BASH
get status.csv
File Organization

It contains information about the status of the last 20 uploads (regardless of their source).

filenamebatch_typedate_and_timeprocessing_statussource
Composition between the timestamp and the uploaded file nameUpload type, can be: full_file, newcomers or leavers (exclusive to single entities)Date and time when the upload occurredStatus can be: Validating, Validated, Pending, Processing, Succeeded, Succeeded with errors (exclusive to channel partners), Rejected, Deleted, Approval_RequestedSource of the upload, can be SFTP or W4C

Download the error details

Once connected to the SFTP Server, you can download the error details of a failed upload. For example, you uploaded a Fullfile, checked the status.csv and saw that this upload failed. Through the error details, you can check the reason for the failure.

  1. Navigate to the /channelpartner/employees/upload/error-details directory. And display the list of error details.
BASH
cd /channelpartner/employees/upload/error-details
ls
  1. The command below downloads the error details file.
BASH
get {Timestamp}_{Uploaded file name}.csv

Download the eligible list file

Once connected to the SFTP Server, it is possible to download the complete list of employees. This file enables listing all existing employees, which can be used as a reference to add or remove employees when performing a "Full file" operation.

  1. Navigate to the /channelpartner/employees/download directory for this company.
BASH
cd /channelpartner/employees/download
  1. Download the {Timestamp}_Eligible-list.csv file.
BASH
get {Timestamp}_Eligible-list.csv
File Organization

It contains information about the type of error and where the error is.

Company Tax IDError SourceLine IDNameError TypeError Description
Points out which client had issuesThis refers at what level the error occurred: Upload error - impacted the whole file, Client error - caused by a specific entity, Input error - refers to line errorsThe line # will be displayed if applicable to the Error Source + TypeThe impacted field will be displayed if applicable to the Error Source + TypeThis refers to the type of error foundWill explain in detail what needs to be addressed

Flexible Benefits

Flexible Benefits allow channel partners to upload credits for their clients, allowing a company's employees to allocate the credits to those that best suit their individual needs. For an employee to be eligible for credits, they need to be created in the eligibility flow.

Contrary to the Eligibility flow, partial uploads are accepted. This means that, by default, the correct lines will be created; and the ones with errors will be rejected. Every time a full or partial rejection happens, the channel partner admins will be notified via email.

Overview of the credits directory structure

TEXT
/
├── channelpartner/
│   └── flexben/
│       └── upload/
│           ├── add-or-update/
│           ├── removal/
│       └── download/
│           ├── upload_history.csv/
│           ├── errors/
│           │   ├── {Timestamp}-{Uploaded-Filename}.csv
│           │   └── ...
│           └── beneficiaries-list.csv
  • The initial directory is the root /.
  • /channelpartner is the directory representing all companies under the channel partner's structure.
  • /channelpartner/flexben/upload/add-or-update is the directory to use if you need to create new credits and/or update existing ones.
  • /channelpartner/flexben/upload/removal should be used to delete credits.
  • /channelpartner/flexben/download/upload_history.csv is the file containing the status of the latest uploads.
  • /channelpartner/flexben/download/errors/ is the directory containing the failed upload error report.
  • /channelpartner/flexben/download/errors/{Timestamp}-{Uploaded-Filename}.csv is the error report referring to a specific upload.
  • /channelpartner/flexben/download/beneficiaries-list.csv will download the snapshot of credited employees.

Manage the credits

There are two types of uploads available:

  • Add or update - a file that will create new credits or edit existing ones
  • Removal - a file that will delete existing credits

Upload an Add/Update credits file

  1. Navigate to the /channelpartner/flexben/upload/add-or-update/.
BASH
cd /channelpartner/flexben/upload/add-or-update/
  1. The command below uploads the .csv file, creating the new credit entries and updating the existing ones.
BASH
put credit-employees.csv
File Organization
Example file - credit-employees.csv
Company Tax IDEmailNational IDEmployee IDAmountLast Credited MonthLast Credited Year
1916628000102david.smith+fbstg01@wellhub.com10122025
1916628000102elena.silva+fbstg30002@wellhub.com100122025
120691930001165942790906459427909064-050122025
120691930001167020286003570202860035-145122025
120691930001163738539107970202860035-275122025
120691930001162098232306970202860035-330122025

Upload a Credits removal file

  1. Navigate to the /channelpartner/flexben/upload/removal/.
BASH
cd /channelpartner/flexben/upload/removal/
  1. The command below uploads the .csv file, deleting the credits.
BASH
put credits-removal.csv
File Organization
Example file - credits-removal.csv
Company Tax IDEmailNational IDEmployee ID
1916628000102elena.silva+fbstg30002@wellhub.com5942790906459427909064-0
120691930001167020286003570202860035-1

Download the status file

You can download the status of the most recent uploads. This is very useful for checking if a specific upload was successful or failed. This file will contain the last 40 uploads (regardless of the method - W4C or SFTP), sorted by date.

  1. Navigate to the /channelpartner/flexben/download directory.
BASH
cd /channelpartner/flexben/download
  1. The command below downloads the upload_history.csv file.
BASH
get upload_history.csv
File Organization
Example file - upload_history.csv
File nameUpload date + timeTypeMethodStatusAuthor# Errors
1740767257-INTERNAL [Flexible Benefits x SFTP] Dry-run - PROD #11.csv2025-02-28 17:12:37.820047 +0000 UTCCANCELSFTPSUCCEEDED01JNGQ2EXFFESN9B2MPM6CKK790
1740762701-INTERNAL [Flexible Benefits x SFTP] Dry-run - PROD #11.csv2025-02-28 17:11:41.476435 +0000 UTCADDSFTPSUCCEEDED01JNGQ2EXFFESN9B2MPM6CKK792
1740762492-INTERNAL [Flexible Benefits x SFTP] Dry-run - PROD #11.csv2025-02-28 17:08:12.544859 +0000 UTCCANCELSFTPREJECTED01JNGQ2EXFFESN9B2MPM6CKK790
1740762163-INTERNAL [Flexible Benefits x SFTP] Dry-run - PROD #10.csv2025-02-28 17:02:43.171987 +0000 UTCADDSFTPSUCCEEDED01JNGQ2EXFFESN9B2MPM6CKK795

Download the error details

You can download the error details of a failed upload. For example, you uploaded a credits file, checked the upload_history.csv and saw that this upload was rejected. Through the error details, you can check the reason for the failure.

  1. Navigate to the /channelpartner/flexben/download/errors/ directory. And display the list of error details.
BASH
cd /channelpartner/flexben/download/errors/
ls
  1. The command below downloads the error details file.
BASH
get 1736255395-credit-employees.csv
File Organization
Example file - <timestamp>-credit-employees.csv
Company Tax IDLineNameError TypeError report
10.516.8291Credit amountInvalidMake sure the amount is a numeric value in the format 100.00 (separated with a '.').
1895858800001563E-mailMissingMissing field: Fill in all required fields.
669038310001815Last credited monthInvalidMake sure the credited month is the same or higher than the current date.
6690383100018113Employee idUnknownUnknown employee: Make sure they are eligible under a company tax id and that their details are up-to-date.

Download the beneficiaries list

You can download a snapshot of the credited employees from a given channel partner.

  1. Navigate to the /channelpartner/flexben/download directory.
BASH
cd /channelpartner/flexben/download
  1. The command below downloads the beneficiaries-list.csv file.
BASH
get beneficiaries-list.csv
File Organization
Example file - beneficiaries-list.csv
Company Tax IDEmailNational IDEmployee IDAmountLast Credited MonthLast Credited Year
12069193000116111110101.0042025
12069193000116111138300.00112025
12069193000116111125100.0082025
12069193000116111102300.0052025
12069193000116111126300.0092025
1206919300011611110315.0062025