Instructions for Channel Partners

Introduction

A Channel Partner works under a reseller business model, and can manage the Eligibility and Flexible Benefits of the clients/tax ids under the structure.

Through Wellhub's SFTP Server, you can perform operations for all the companies within a channel partner structure in one go. The interaction with the SFTP Server is simple - it's a file system where you can navigate between directories, list, upload, and download files.

These are the operations supported on the SFTP Server for Channel Partners:

Creation and updates

Loading diagram...

Details

Loading diagram...

Encrypt the content of files you upload and/or download. See Encryption.
To manage multiple companies under the channel partners structure, you must select Channel partners view when generating the SFTP keys. See Getting Started.

The following sections provide more details on each operation.

Overview of the directory structure

/
└── 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

/
└── 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).

Navigate to the /channelpartner/employees/upload/all.

cd /channelpartner/employees/upload/all

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.

put all-employees.csv

File Organization

Example file - all-employees.csv

Company Tax ID	Name	Email	National ID	Employee ID	Department	Payroll ID	Cost center	Office zip code	Payroll Enabled
37.211.173/0001-69	Phoebe Bridgers	maxinethedog@bridgers.com	764.254.640-89	331234	UX	1324	1-114-873	04571-926	Yes
37.211.173/0001-69	Lucy Dacus	dacus@modigliani@com	151.846.620-65	834372	Engineering	7375	1-114-773	04571-926	No

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.

Navigate to the /channelpartner/employees/upload directory.

cd /channelpartner/employees/upload

The command below downloads the status.csv file.

get status.csv

File Organization

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

filename	batch_type	date_and_time	processing_status	source
Composition between the timestamp and the uploaded file name	Upload type, can be: full_file, newcomers or leavers (exclusive to single entities)	Date and time when the upload occurred	Status can be: Validating, Validated, Pending, Processing, Succeeded, Succeeded with errors (exclusive to channel partners), Rejected, Deleted, Approval_Requested	Source 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.

Navigate to the /channelpartner/employees/upload/error-details directory. And display the list of error details.

cd /channelpartner/employees/upload/error-details
ls

The command below downloads the error details file.

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.

Navigate to the /channelpartner/employees/download directory for this company.

cd /channelpartner/employees/download

Download the {Timestamp}_Eligible-list.csv file.

get {Timestamp}_Eligible-list.csv

File Organization

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

Company Tax ID	Error Source	Line ID	Field Name	Error Type	Error Description
Points out which client had issues	This 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 errors	The line # will be displayed if applicable to the Error Source + Type	The impacted field will be displayed if applicable to the Error Source + Type	This refers to the type of error found	Will 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

/
├── 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

Navigate to the /channelpartner/flexben/upload/add-or-update/.

cd /channelpartner/flexben/upload/add-or-update/

The command below uploads the .csv file, creating the new credit entries and updating the existing ones.

put credit-employees.csv

File Organization

Example file - credit-employees.csv

Company Tax ID	Email	National ID	Employee ID	Amount	Last Credited Month	Last Credited Year
1916628000102	david.smith+fbstg01@wellhub.com			10	12	2025
1916628000102	elena.silva+fbstg30002@wellhub.com			100	12	2025
12069193000116		59427909064	59427909064-0	50	12	2025
12069193000116		70202860035	70202860035-1	45	12	2025
12069193000116		37385391079	70202860035-2	75	12	2025
12069193000116		20982323069	70202860035-3	30	12	2025

Upload a Credits removal file

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

cd /channelpartner/flexben/upload/removal/

The command below uploads the .csv file, deleting the credits.

put credits-removal.csv

File Organization

Example file - credits-removal.csv

Company Tax ID	Email	National ID	Employee ID
1916628000102	elena.silva+fbstg30002@wellhub.com	59427909064	59427909064-0
12069193000116		70202860035	70202860035-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.

Navigate to the /channelpartner/flexben/download directory.

cd /channelpartner/flexben/download

The command below downloads the upload_history.csv file.

get upload_history.csv

File Organization

Example file - upload_history.csv

File name	Upload date + time	Type	Method	Status	Author	# Errors
1740767257-INTERNAL [Flexible Benefits x SFTP] Dry-run - PROD #11.csv	2025-02-28 17:12:37.820047 +0000 UTC	CANCEL	SFTP	SUCCEEDED	01JNGQ2EXFFESN9B2MPM6CKK79	0
1740762701-INTERNAL [Flexible Benefits x SFTP] Dry-run - PROD #11.csv	2025-02-28 17:11:41.476435 +0000 UTC	ADD	SFTP	SUCCEEDED	01JNGQ2EXFFESN9B2MPM6CKK79	2
1740762492-INTERNAL [Flexible Benefits x SFTP] Dry-run - PROD #11.csv	2025-02-28 17:08:12.544859 +0000 UTC	CANCEL	SFTP	REJECTED	01JNGQ2EXFFESN9B2MPM6CKK79	0
1740762163-INTERNAL [Flexible Benefits x SFTP] Dry-run - PROD #10.csv	2025-02-28 17:02:43.171987 +0000 UTC	ADD	SFTP	SUCCEEDED	01JNGQ2EXFFESN9B2MPM6CKK79	5

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.

Navigate to the /channelpartner/flexben/download/errors/ directory. And display the list of error details.

cd /channelpartner/flexben/download/errors/
ls

The command below downloads the error details file.

get 1736255395-credit-employees.csv

File Organization

Example file - <timestamp>-credit-employees.csv

Company Tax ID	Line	Field name	Error Type	Error report
10.516.829	1	Credit amount	Invalid	Make sure the amount is a numeric value in the format 100.00 (separated with a '.').
189585880000156	3	E-mail	Missing	Missing field: Fill in all required fields.
66903831000181	5	Last credited month	Invalid	Make sure the credited month is the same or higher than the current date.
66903831000181	13	Employee id	Unknown	Unknown 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.

Navigate to the /channelpartner/flexben/download directory.

cd /channelpartner/flexben/download

The command below downloads the beneficiaries-list.csv file.

get beneficiaries-list.csv

File Organization

Example file - beneficiaries-list.csv

Company Tax ID	Employee ID	Amount	Last Credited Month	Last Credited Year
12069193000116	111110	101.00	4	2025
12069193000116	111138	300.00	11	2025
12069193000116	111125	100.00	8	2025
12069193000116	111102	300.00	5	2025
12069193000116	111126	300.00	9	2025
12069193000116	111103	15.00	6	2025