Instructions for Multi Entities

Introduction

When you want to manage multiple companies in one go (aggregated), we call this "Multi Entity".

Through Wellhub's SFTP Server, you can perform certain operations for a specific company, or for all your managed companies at the same time.

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 Multi Entities:

Creation and updates

Details

Flows | Payroll

For clients with payroll as payment method, every billing cycle the deduction file and deduction file for leavers (in case there were employee removals) will be provided. This is a list of all the employees that paid for a Wellhub subscription with paycheck in a given billing period. This will then be used by the client to discount the subscription amount when running payroll.

• Note: for now, only the .zip is available for MEs (with individual files within it). In the future, there will also be a consolidated file.

• Encrypt the content of the files you upload and/or download. See Encryption.

• To manage multiple companies within the multi-entity structure, you must select the ‘All companies’ view when generating the SFTP keys. See Getting Started.

The following sections provide more details on each operation.

Overview of the file structure

File Structure

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

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

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

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.

put all-employees.csv

File Organization

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.

cd /multientity/employees/upload

2. 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).

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.

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

2. The command below downloads the error details file.

get {Timestamp}_{Uploaded file name}.csv

File Organization

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

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.

cd /multientity/employees/download

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

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

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

cd /multientity/payroll

2. The command below downloads a payroll file.

get {company name (single entity)}_YYYYMM_wellhub_payroll_deduction.csv

File Organization

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.

cd /multientity/payroll/leavers

2. The command below downloads a payroll file.

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

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

cd /multientity/reports/

2. The command below downloads the yearly usage report file.

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

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

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

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

put credit-employees.csv

File Organization

Upload a Credits removal file

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

cd /multientity/flexben/upload/removal/

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

put credits-removal.csv

File Organization

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.

cd /multientity/flexben/download/upload_history.csv

2. The command below downloads the upload_history.csv file.

get upload_history.csv

File Organization

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.

cd /multientity/flexben/download/errors/
ls

2. The command below downloads the credit-employees.csv file.

get 1736255395-credit-employees.csv

File Organization

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.

cd /multientity/flexben/download/beneficiaries-list.csv
ls

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

get beneficiaries-list.csv

File Organization