Heading

Mermaid

strong

CustomLink

article

Eligibility concepts Eligibility API keeps your employee roster in sync so onboarding and offboarding stay current. Eligibility identifier Employees are identified by an Eligibility Identifier. The identifier is defined in your contract and can be based on: Email National ID Employee ID Only the primary identifier is required in API calls. Supporting identifiers can be stored but are optional. {% callout %} Security note: Some characters may be blocked in path parameters to prevent path traversal. If you receive a validation error, try encoding or omitting special characters. {% /callout %} Entities When interacting with Wellhub's API, an access may handle one or more companies simultaneously. For that, it is important to understand what kind of entity the developer is dealing with. The available entity types are: Single Entity : Manages a single company; Multi Entity : Manages multiple companies; Channel Partner : Manages multiple companies;

Identifiers and entities

Eligibility Management This section describes the Eligibility Management endpoints available for managing employees. The Clients API is a REST API, with JSON format for data exchange. There will be a single endpoint to perform eligible related operations (which can be: insert, update or delete), where the action to perform must be specified under the “operation” attribute on the HTTP request. Every server response uses proper HTTP status codes, with proper distinction between successful and unsuccessful requests (both from client side and server side errors). For data exchange, JSON format is utilized for both requests and responses. For information about BASE URl and ACCESS TOKEN values, see /docs/api/getting started. Endpoints summary | Endpoint | Description | | | | | POST /v1/eligibility/jobs | Endpoint to create a job. | | POST /v1/eligibility/jobs/{job id}/items | Endpoint to create job items. | | GET /v1/eligibility/jobs/{job id}/items | Endpoint to list the job items. | | POST /v1/eligibility/jobs/{job id}/submit | Endpoint to submit a job. | | GET /v1/eligibility/jobs/{job id}/status | Endpoint to retrieve the job status. | | GET /v1/eligibility/jobs/{job id}/errors | Endpoint to list the job errors. | | GET /v1/employees | Endpoint to list eligibles for a single entity. | | GET /v1/companies/{company tax id}/employees | Endpoint to list eligibles for multi entities and channel partners. | | GET /v1/companies | Endpoint to list entity companies. | Eligibility jobs Eligibility jobs are used to create, submit, and track batches of eligibility updates. Create Job Create a new eligibility job and return a job identifier for subsequent operations. Curl example curl X POST "{{BASE URL}}/v1/eligibility/jobs" \ H "Authorization: Bearer {{ACCESS TOKEN}}" Parameters This endpoint does not define parameters. Headers | Name | Required | Description | | | | | | Authorization | Yes | Authentication token used to authorize requests. | Response codes | Code | Description | | | | | 201 | Created | | 401 | Unauthorized | | 403 | Forbidden | | 500 | Internal Server Error | Example response 201 Created { "id": "152f4e34 da90 4c9c 9867 9280952a6b68" } Create Job Items These items are employees’ operations, which can create, update or delete entries on Wellhub's database. For multi entities and channel partners: To get more clarity on the company tax IDs within your group, use the /docs/api/eligibility management/ list entity companies. Curl example curl X POST "{{BASE URL}}/v1/eligibility/jobs/{{job id}}/items" \ H "Authorization: Bearer {{ACCESS TOKEN}}" \ H "Content Type: application/json" \ d '[ { "operation": "CREATE", "company tax id": "1234567890", "employee id": "E 1029", "full name": "Maria Santos", "email": "maria.santos@acme.com", "national id": "12345678901", "department": "People", "cost center": "CC 001", "office zip code": "12345", "eligible to payroll": true, "custom fields": { "location": "Sao Paulo" } } ]' Parameters | Name | In | Required | Description | | | | | | | job id | Path | Yes | Job ID. | Request Payload Structure The request body must be an array of job item objects, with maximum size of 500 items per request. Each object in the array represents an employee operation and supports the following fields: | Field | Type | Required | Description | | | | | | | operation | string | Yes | The action to perform: CREATE , UPDATE , or DELETE . | | company tax id | string | Yes | Company's unique identifier a given employee belongs to. | | employee id | string | Yes | Employee identifier within company's system. | | full name | string | No | Full name of the employee. | | email | string | Yes | Email address of the employee. | | national id | string | Yes | National identification registry of the employee. | | department | string | No | Department where the employee works. | | cost center | string | No | Cost center associated with the employee. | | office zip code | string | No | ZIP code of the employee's office location. | | eligible to payroll | boolean | No | Whether the employee is eligible for payroll. | | payroll id | string | No | Payroll system identifier for the employee. | | mobile number | string | No | Mobile phone number of the employee. | | discount subset id | string | No | Identifier for the discount subset applicable to the employee. | | custom fields | object | No | Additional custom fields as key value pairs. | {% callout %} Depending on how the Eligibility Identifier was determined by the company's contract with Wellhub, the field may turn to be optional. {% /callout %} Headers | Name | Required | Description | | | | | | Authorization | Yes | Authentication token used to authorize requests. | | Content Type | Yes | application/json . | Response codes | Code | Description | | | | | 204 | No Content | | 400 | Bad Request (validation errors; see response body details) | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found | | 500 | Internal Server Error | Example request [ { "operation": "CREATE", "company tax id": "1234567890", "employee id": "E 1029", "full name": "Maria Santos", "email": "maria.santos@acme.com", "national id": "12345678901", "department": "People", "cost center": "CC 001", "office zip code": "12345", "eligible to payroll": true, "custom fields": { "location": "Sao Paulo" } } ] Example response 400 Bad Request { "message": "Bad Request", "reason": "Bad information provided", "errors": [ { "field": "[0].operation", "message": "must be one of CREATE, UPDATE, DELETE" }, { "field": "[0].company tax id", "message": "cannot be blank" } ] } List Job Items List the items already attached to a job. Supports pagination via the cursor query parameter. Curl example curl X GET "{{BASE URL}}/v1/eligibility/jobs/{{job id}}/items?cursor={{cursor}}" \ H "Authorization: Bearer {{ACCESS TOKEN}}" Parameters | Name | In | Required | Description | | | | | | | job id | Path | Yes | Job ID. | | cursor | Query | No | Cursor for pagination. | Headers | Name | Required | Description | | | | | | Authorization | Yes | Authentication token used to authorize requests. | Response codes | Code | Description | | | | | 200 | OK | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found | | 500 | Internal Server Error | Example response 200 OK { "cursor": "next cursor token", "data": [ { "id": "item 1", "job id": "job 12345", "change number": 1, "company tax id": "1234567890", "cost center": "CC 001", "created at": "2026 01 20T10:20:30Z", "custom fields": { "location": "Sao Paulo" }, "department": "People", "discount subset id": "subset 123", "eligible to payroll": true, "email": "maria.santos@acme.com", "employee id": "E 1029", "full name": "Maria Santos", "mobile number": "+5511999999999", "national id": "12345678901", "office zip code": "12345", "operation": "CREATE", "payroll id": "PAY 123" } ] } Submit Job Submit a job for processing once all items are uploaded. Curl example curl X POST "{{BASE URL}}/v1/eligibility/jobs/{{job id}}/submit" \ H "Authorization: Bearer {{ACCESS TOKEN}}" Parameters | Name | In | Required | Description | | | | | | | job id | Path | Yes | Job ID. | Headers | Name | Required | Description | | | | | | Authorization | Yes | Authentication token used to authorize requests. | Response codes | Code | Description | | | | | 202 | Accepted | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found | | 409 | Conflict | | 422 | Unprocessable Entity | | 500 | Internal Server Error | Example response No response body is returned for a successful request. Get Job Status Get the current processing status for a job. Curl example curl X GET "{{BASE URL}}/v1/eligibility/jobs/{{job id}}/status" \ H "Authorization: Bearer {{ACCESS TOKEN}}" Parameters | Name | In | Required | Description | | | | | | | job id | Path | Yes | Job ID. | Headers | Name | Required | Description | | | | | | Authorization | Yes | Authentication token used to authorize requests. | Response codes | Code | Description | | | | | 200 | OK | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found | | 500 | Internal Server Error | Example response 200 OK { "id": "job 12345", "status": "VALIDATED", "updated at": "2026 01 20T10:30:00Z", "statistics": { "newcomers": 10, "updaters": 3, "leavers": 2 } } List Job Errors List processing errors for a job. Supports pagination via the cursor query parameter. Curl example curl X GET "{{BASE URL}}/v1/eligibility/jobs/{{job id}}/errors?cursor={{cursor}}" \ H "Authorization: Bearer {{ACCESS TOKEN}}" Parameters | Name | In | Required | Description | | | | | | | job id | Path | Yes | Job ID. | | cursor | Query | No | Cursor for pagination. | Headers | Name | Required | Description | | | | | | Authorization | Yes | Authentication token used to authorize requests. | Response codes | Code | Description | | | | | 200 | OK | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 500 | Internal Server Error | Example response 200 OK { "cursor": "next cursor token", "data": [ { "error type": "VALIDATION ERROR", "field name": "email" } ] } Employees List Employees List employees for a single entity. Supports pagination via the cursor query parameter. Curl example curl X GET "{{BASE URL}}/v1/employees?cursor={{cursor}}" \ H "Authorization: Bearer {{ACCESS TOKEN}}" Parameters | Name | In | Required | Description | | | | | | | cursor | Query | No | Cursor for pagination. | Headers | Name | Required | Description | | | | | | Authorization | Yes | Authentication token used to authorize requests. | Response codes | Code | Description | | | | | 200 | OK | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 500 | Internal Server Error | Example response 200 OK { "cursor": "next cursor token", "data": [ { "id": "emp 456", "employee id": "E 2048", "email": "john.doe@acme.com", "full name": "John Doe", "national id": "10987654321", "mobile number": "+5511988888888", "batch id": "job 12345", "invitation status": "ACTIVE", "updated at": "2026 01 20T11:00:00Z", "deleted at": null, "additional fields": { "department": "Engineering" }, "attributes": {}, "custom fields": { "location": "Rio de Janeiro" } } ] } List Company's Employees List employees for a specific company by tax ID. Supports pagination via the cursor query parameter. Curl example curl X GET "{{BASE URL}}/v1/companies/{{company tax id}}/employees?cursor={{cursor}}" \ H "Authorization: Bearer {{ACCESS TOKEN}}" Parameters | Name | In | Required | Description | | | | | | | company tax id | Path | Yes | Company Tax ID. | | cursor | Query | No | Cursor for pagination. | {% callout %} Note : due to the characteristics of the HTTP protocol, if the company tax id has any slash character(s), it must be sent without them. Example: 00.623.904/0001 73 → 00623904000173 or 00.623.9040001 73 {% /callout %} Headers | Name | Required | Description | | | | | | Authorization | Yes | Authentication token used to authorize requests. | Response codes | Code | Description | | | | | 200 | OK | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found | | 500 | Internal Server Error | Example response 200 OK { "cursor": "next cursor token", "data": [ { "id": "emp 123", "employee id": "E 1029", "email": "maria.santos@acme.com", "full name": "Maria Santos", "national id": "12345678901", "mobile number": "+5511999999999", "batch id": "job 12345", "invitation status": "INVITED", "updated at": "2026 01 20T10:30:00Z", "deleted at": null, "additional fields": { "department": "People" }, "attributes": {}, "custom fields": { "location": "Sao Paulo" } } ] } Companies List Entity Companies If you are managing multiple companies or a channel partner organization, to facilitate eligibility management, you will be able to review the company tax ids under your structure. List companies for the current entity. Supports pagination via the cursor query parameter. Curl example curl X GET "{{BASE URL}}/v1/companies?cursor={{cursor}}" \ H "Authorization: Bearer {{ACCESS TOKEN}}" Parameters | Name | In | Required | Description | | | | | | | cursor | Query | No | Cursor for pagination. | Headers | Name | Required | Description | | | | | | Authorization | Yes | Authentication token used to authorize requests. | Response codes | Code | Description | | | | | 200 | OK | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 500 | Internal Server Error | Example response 200 OK { "cursor": "next cursor token", "data": [ { "company name": "Cool Company", "company tax id": "1234567890" } ] }

Eligibility Management

Getting Started {% callout %} Before getting started, it is highly recommended to check the /docs/api/eligibility management/identifiers and entities if you're not familiar with the identifiers and entity concepts used in the API. The /docs/eligibility contains detailed information on what eligibility is and how it works inside Wellhub's ecosystem. {% /callout %} The API lets you sync employee eligibility from your HR system so employees can access Wellhub as soon as they are added (and removed when they leave). This guide covers the basics you need to start integrating. Architecture style The API follows REST conventions and uses JSON for request and response bodies. Endpoints align to HTTP methods and resources. Responses use standard HTTP status codes for success and errors. Requests and responses are JSON. The API Sandbox will return synthetic data for testing purposes, mimicking the patterns and structure of the API actions taken will only be reflected in the synthetic data returned in the response, no users sent to the Sandbox will be created, updated or deleted. Authentication Authentication uses the OAuth 2.0 client credentials flow. Your integration uses a Client ID and Client Secret to request a short‑lived access token, then sends that token as a Bearer token on every API call. You can create and manage OAuth credentials in https://clients.gympass.com/, under Settings. Create API credentials Use the Wellhub for Companies portal to generate credentials for your integration. 1) Open API OAuth credentials From the left navigation, go to Settings and open API OAuth credentials . If you have no credentials yet, you will see an empty state with a Generate credential button. {% image src="/assets/api/api credentials list empty.png" alt="API OAuth credentials empty state" /%} 2) Enter credential details Click Generate credential , then fill in: Credential name to identify the integration. Data access : choose Production for live data or Sandbox for testing. Credential expiration : set a duration or choose Never expire . {% image src="/assets/api/api credentials create 01.png" alt="Credential details form" /%} {% image src="/assets/api/api credentials create 04.png" alt="Credential expiration options" /%} 3) Set permissions Choose the access level for each product area, then click Generate credential . {% image src="/assets/api/api credentials create 02.png" alt="Credential permissions selection" /%} 4) Save your client secret After creation, the portal shows your Client ID and Secret once. Store the secret securely right away. {% image src="/assets/api/api credentials create 03.png" alt="Credential created with client ID and secret" /%} 5) View or manage credentials Open an existing credential to review details, copy the Client ID , edit permissions, or deactivate the credential. {% image src="/assets/api/api credentials view 01.png" alt="Credential details panel" /%} Generate an OAuth token Use the token endpoint to exchange your client credentials for an access token. Create Authorization Token Endpoint POST /oauth/token Parameters | Name | Required | Description | | | | | | client id | Yes | Your OAuth client ID. | | client secret | Yes | Your OAuth client secret. | | grant type | Yes | Use client credentials . | Headers | Name | Required | Description | | | | | | Content Type | Yes | application/x www form urlencoded . | Response codes | Code | Description | | | | | 200 | OK | | 400 | Bad Request | | 401 | Unauthorized | | 500 | Internal Server Error | Example request curl X POST "{{BASE URL}}/oauth/token" \ H "Content Type: application/x www form urlencoded" \ d "client id={{CLIENT ID}}" \ d "client secret={{CLIENT SECRET}}" \ d "grant type=client credentials" Example response { "access token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expires in": 3600, "token type": "Bearer" } Environment URLs Sandbox: https://pilot api.clients.wellhub.com Production: https://api.clients.wellhub.com Use Sandbox for testing before moving to Production. Throttling Requests are rate limited. Current limits are TBD. Requests beyond the limit return 429 Too Many Requests .

Getting Started

API Documentation This section contains documentation about Wellhub's public API. Available guides /docs/api/getting started /docs/api/eligibility management/ /docs/api/eligibility management/identifiers and entities

Eligibility FAQ FAQs 1. Why does Wellhub generally require the Employee ID, Name, and Email? These attributes are used for multiple purposes. Employee ID and/or Email are used to validate eligible employees when they register for their Wellhub account. Email and Name are used to support communications of information about Wellhub and the Wellhub program to eligible employees, assisting the company's HR team in promoting and encouraging use. 2. What if all employees do not have an email address? That indicates that the EmployeeID will be needed for validating eligible employees, and Wellhub will not be able to provide its full set of communication services to the company. 3. Who can be an eligible employee? That is a decision made by the company. Typical considerations include these situations: Leave of Absence employees, both long term and short term Part time employees Remote or on assignment employees Most companies include their benefits eligible employees only. 4.Can the Eligibility File be created as an Excel file? Yes, both ".xlsx", ".csv" formats are supported. Proper de limiters must be added before providing it to Wellhub. 5. Can a data field contain the delimiter as part of the data? You must ensure that any field containing the delimiter as part of the data (for example, a Department that includes a semicolon) is bounded by quotation marks. 6. What about numeric fields with leading zeros? Please ensure that any numeric fields with leading zeros include the zeros in the CSV. 7. What is a Null field? It is a field that contains no data at all … no space, no blank, etc. 8. How often should the EF be sent to Wellhub? Wellhub recommends weekly since this allows new hires to have the quickest access to Wellhub as they on board. Consult your Wellhub team for a specific recommendation or specific questions on your file delivery cadence. 9. What is a Full File? A Full File is a file that includes all eligible employees. Any employees who were previously eligible and have become ineligible for any reason should be omitted from the next Full File provided to Wellhub. As new hires come on board, or other employees become newly eligible, they should be added to the next file sent to Wellhub 10. If my company has selected to support payroll deductions, are there any implications on the EF contents? Yes. Name, Email, EmployeeID, Department, Cost Center, Office Zip Code, and Payroll ID fields will be reflected back to the company (assuming they were shared on the Eligibility File) in the Wellhub standard Deduction File, which provides the company with the information needed to support payroll deductions.

Frequently Asked Questions

Getting Started Introduction As a business to business company, Wellhub only provides its services to employees (and by extension their family members) of subscribing companies, and because of this, all processes begin by establishing and maintaining the eligibility of end users. Of course, eligibility may change frequently with new people joining the company and others leaving, and because of this, an ongoing process between Wellhub and the company is required to maintain accurate access and use of Wellhub. The company will generate an Eligibility File (EF) and provide it to Wellhub using a manual upload function available in the Wellhub HR Portal or using SFTP for automated transfers. The client will be connected automatically to our systems within a certain frequency (that can be programmed or triggered by the client every time there is a need for an update), eliminating the need for manual work. Flows | Eligibility {% mermaid %} graph TB SFTP["<b SFTP</b "] Full["<b Full file</b <br/ Full eligibles overwrite<br/ <i SEs · MEs · CPs</i "] New["<b Newcomers</b <br/ New eligibles creation<br/ <i SEs</i "] Leavers["<b Leavers</b <br/ Remove eligibles<br/ <i SEs</i "] SFTP Full SFTP New SFTP Leavers classDef greenBox fill: c8e6c9,stroke: 4caf50,stroke width:2px classDef yellowBox fill: fff9c4,stroke: fbc02d,stroke width:2px class SFTP greenBox class Full,New,Leavers yellowBox {% /mermaid %} {% mermaid %} graph TB SFTP["<b SFTP</b "] Download["<b Download eligible list</b <br/ Access the list of all eligible employees<br/ <i SEs</i "] UploadHistory["<b Upload history</b <br/ Get the list and status of previous uploads<br/ <i SEs · MEs · CPs</i "] ErrorDetails["<b Error details</b <br/ Access the errors of a failed update<br/ <i MEs · CPs</i "] EmailRejected["<b Email for rejected uploads</b <br/ Alert for rejected SFTP uploads<br/ <i MEs · CPs</i "] SFTP Download SFTP UploadHistory SFTP ErrorDetails SFTP EmailRejected classDef greenBox fill: c8e6c9,stroke: 4caf50,stroke width:2px classDef yellowBox fill: fff9c4,stroke: fbc02d,stroke width:2px class SFTP greenBox class Download,UploadHistory,ErrorDetails,EmailRejected yellowBox {% /mermaid %} Flows | Payroll For clients with payroll as a 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. {% mermaid %} graph TB SFTP["<b SFTP</b "] Deduction["<b Deduction file download</b <br/ Access the list with the relevant paycheck<br/ deduction amount per employee<br/ <i SEs · MEs </i "] Leavers["<b Deduction file for leavers download</b <br/ Filtered list with the paycheck deduction<br/ information for removed employees<br/ <i SEs · MEs </i "] SFTP Deduction SFTP Leavers classDef greenBox fill: c8e6c9,stroke: 4caf50,stroke width:2px classDef yellowBox fill: fff9c4,stroke: fbc02d,stroke width:2px class SFTP greenBox class Deduction,Leavers yellowBox {% /mermaid %} 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. Flows | Reporting The reporting flow is crucial to track the usage of the Wellhub benefit, as it provides a view on the adoption of the solution, as well as the subscriptions data and check ins of employees and family members (in case the client has that SKU). {% mermaid %} graph TB SFTP["<b SFTP</b "] Reports["<b Reports .zip download</b <br/ Access the reporting files with data<br/ from the last 12 months D 2<br/ <i SEs</i "] ER["<b Engagement rates</b <br/ Daily snapshot of the total of eligibles,<br/ members, subscribers, and family members<br/ if applicable"] CI["<b Check ins</b <br/ Full list of the check ins in Wellhub partners<br/ both physical and virtual activities.<br/ Includes family member data if applicable"] SS["<b Subscribers snapshot</b <br/ Full list of the subscribers and their subscription<br/ details, including the plan selected and price.<br/ Includes family member data if applicable"] SH["<b Subscription history</b <br/ Full list of transaction events related to<br/ an employees subscription, such as: first subscription,<br/ upgrade, downgrade, pause, cancellation,<br/ and new subscription.<br/ Includes family member data if applicable"] SFTP Reports Reports ER Reports CI Reports SS Reports SH classDef greenBox fill: c8e6c9,stroke: 4caf50,stroke width:2px classDef yellowBox fill: fff9c4,stroke: fbc02d,stroke width:2px classDef grayBox fill: e0e0e0,stroke: 757575,stroke width:2px class SFTP greenBox class Reports grayBox class ER,CI,SS,SH yellowBox {% /mermaid %} For more details on the SFTP option, please see the /docs/sftp of this website. For more details on the API option, please see the /docs/api of this website. Data Privacy and Security Wellhub takes the privacy and security of the data it processes from its customers very seriously. Wellhub's processing activities are aligned with our PCI DSS and ISO 27001 certification and aligned with local regulations (eg. GDPR, LGDP). For any detailed questions on our security posture please reach out to your Wellhub Tech Sales representative.

Global Standard Required fields | Field | Mandatory/Optional | Description | Format | Example | | | | | | | | Company Tax ID | Mandatory for Multi Entities and Channel Partners | Identifies to which company an employee belongs | It can have special characters, but we will transform it, leaving only alphanumeric to identify the corresponding company | 00.623.904/0001 73 → 00623904000173 | | Email | Mandatory (as single eligibility identifier) | It must be unique for the same company tax id; at the at the multi entity and channel partner level, duplicates are accepted | There is no validation if the email exists, but the format is validated (including the company domain), and there isn’t a limit of characters | a@b.com john.doe@gympass.com | | Employee ID | Mandatory if Employee ID + National ID as eligibility identifiers (Email as optional) | It must be unique for the same company tax id; at the multi entity and channel partner level, duplicates are accepted | It’s an alphanumeric field required to have at least 8 characters | 123 John.doe | | National ID | Mandatory if Employee ID + National ID as eligibility identifiers (Email as optional) | It must be unique for the same company tax id; at the multi entity and channel partner level, duplicates are accepted | It’s an alphanumeric field, and its validation depends on the company's country it refers to the employees tax id (e.g. in Brazil CPFs are requested). Format and logical validations are performed | 11122233396 AB1234FA43 | | Name | Optional | This field helps engagement on our communications (Invitation to Sign Up, for example) | There is no validation on the name and no character limit | John Doe | | Payroll Enabled | Optional | It's a boolean column (Yes/No) to allow the clients to manage the employees allowed to use paycheck as a payment method (not managed by the client) | Yes or No | Yes | | Payroll ID | This identifier helps the client find the employee in their payroll software | It’s an alphanumeric (and specials) field without a character limit | 2953ACV@ZF | | Cost Center | Optional | This represents the employee's cost center | It’s an alphanumeric (and specials) field without a character limit | Department | Optional | This represents the employee's department | It’s an alphanumeric (and specials) field without a character limit | Office zip code | Optional | This represents the employee's office zip code | It’s an alphanumeric (and specials) field without a character limit | Discount group | Mandatory for clients with Wellhub+ 2.0 | The value must correspond to the discount groups created | It’s a numeric field, if empty the discount group will be removed from the eligible | 1 Header record The Header Record must be included in the file. The Attribute Names (column titles) must be written exactly as indicated in the specification table above. {% image src="/assets/eligibility/CIA Integrations Guidebook SFTP and API Spreadsheet Example.jpg" alt="Headers example" /%} Data Record Mandatory Fields Generally, Wellhub requires each of these fields to be included for Wellhub to have the necessary information required to validate eligible employees and to assist in program communications with employees. However, there may be special cases, for example when an employee does not have an email address, that can be accommodated. If you cannot provide this data for all your employees, please consult with your Wellhub Sales and Technical Sales representatives. If you have any questions on this, consult your Wellhub Customer Success representative. Format Notes The header is mandatory, and needs to be in English for all countries The column order is not mandatory The column titles (attribute names) must be written exactly as indicated in the document Unknown columns will be ignored The CSV can use any of the accepted separators, as: comma ( , ), semicolon ( ; ), tab, and space CSV UTF 8 is the format supported

Global Standard

Eligibility This section contains documentation about eligibility in Wellhub. Available guides /docs/eligibility/getting started /docs/eligibility/global standard /docs/eligibility/eligibility faq

Eligibility

Getting Started Introduction When employees choose and enroll in a Wellhub plan, they will be responsible for paying the monthly plan subscription fee. This amount may be paid using a Credit Card or through Payroll deductions. For payroll deductions, there is an additional integration process required between Wellhub and the company related to managing the deduction data (i.e. creating, exchanging, and processing the deduction data). This is a monthly process, and Wellhub will provide a file that provides specific information for each charge the employee is responsible for covering for that month. {% image src="/assets/eligibility/CIA Integrations Guidebook SFTP and API.png" alt="Eligibility ecosystem" /%} As indicated in the diagram, the company will generate an Eligibility File (EF) and provide it to Wellhub using either (1) a manual upload function available in the Wellhub for Companies Portal, or (2) SFTP for a more automated transfer. More details on using SFTP for exchanging information with Wellhub can be found in the /docs/sftp. File Characteristics The CSV delimiter will be semicolons ( ; ) The headers will be in English The file headers will follow the Eligibility file specifications shared by the client (in case the content hasn't been shared, it will be blank) The currency will follow the client's location (in case there are entities within the structure with different location/currencies, currencies will be returned accordingly) Only employees who have payroll enabled (as determined by the Eligibility File) will appear on the deduction file Only employees who have payroll enabled (as determined by the Eligibility File), and have subscribed to a plan and then were removed from the company during the given billing cycle will appear on the deduction file for leavers File Exchange Frequency Deduction Files (DFs) are generated and available at the same time the company invoice is issued. You will find in the Payroll SFTP folder the deduction file referring to the latest billing cycle (at the same time the company invoice will be issued). On a monthly basis, it will be replaced by the most recent file. File Naming Convention Single Entity Deduction file File name: YYYYMM wellhub payroll deduction.csv Example: 202507 wellhub payroll deduction.csv If there is more than one file issued, there will be versioning. Ex: YYYYMM wellhub payroll deduction 1.csv , YYYYMM wellhub payroll deduction 2.csv Deduction file for leavers File name: YYYYMM wellhub partial payroll deduction.csv Example: 202507 wellhub partial payroll deduction.csv Multi Entity Deduction file File name: Client name (single entity) + YYYYMM + wellhub payroll deduction.csv Example: Clientname1 202507 wellhub payroll deduction.csv Deduction file for leavers File name: Client name (single entity) + YYYYMM + wellhub partial payroll deduction.csv Example: Clientname1 202507 wellhub partial payroll deduction.csv File Contents Overview Deduction Files (DFs) contain fields that identify the employee that the charge belongs to. Because of the flexibility provided to make changes to plans, there may be more than one charge for the employee baked into the total amount owed on the DF.

Global Standard File Content Specifications | Parameter | Description | Format | | | | | | Full name | Same as provided in the Eligibility File to Wellhub | First Last No character length restrictions | | Email | Same as provided in the Eligibility File to Wellhub | Valid email address | | National ID | CPF (Brazil) or National ID; Same as provided in Eligibility File. Not applicable to all countries | Valid country ID | | Employee ID | Employee ID, same as provided in the Eligibility File to Wellhub | Alpha and/or Numeric | | Amount due | Amount owed by the employee in local currency | Currency symbol, blank, two decimal amount Example: $123.45, R$20,00 | | Department | Department, same as provided in the Eligibility File to Wellhub | Variable, company defined, alpha and/or numeric | | Cost Center | Same as provided in the Eligibility File to Wellhub | Variable, company defined, alpha and/or numeric | | Office zip code | Same as provided in the Eligibility File to Wellhub | Alpha and/or numeric (and specials) field without character limit | | Payroll ID | Same as provided in the Eligibility File to Wellhub | Alpha and/or numeric (and specials) field without character limit | Header Record The Header Record will be included in the file, and the Attribute Names (column titles) will be as indicated in the specification table above. Data Record There will only be one record for a single employee in a file. Because of the flexibility provided to make changes to plans, there may be more than one charge for the employee baked into the total amount owed on the DF. Any questions as to the nature of the charge can be answered by the employee logging into their Wellhub app navigating to Profile navigating to Settings navigating to Account and clicking on either Receipts or Billing history. For more information, please contact your Wellhub Sales or Technical Sales representative.

Eligibility This section contains documentation about payroll deductions in Wellhub. Available guides /docs/payroll/getting started /docs/payroll/global standard /docs/payroll/payroll faq

Payroll

Payroll FAQ FAQs 1. Why are the files generated monthly? Wellhub plans are paid on a monthly subscription basis. 2. How can an employee understand the full breakdown of their deduction amount? While the subscription price of a Wellhub plan is a monthly charge, users can start, upgrade, downgrade, or cancel their plans at any time. Consequently, there may be partial amounts owed, in addition to the full monthly subscription amount. The Payroll Deduction File that Wellhub shares with each of its clients monthly will simply sum the amounts for each employee to one line and one deduction amount. For more details on the specifics and the breakdown behind this amount, employees can log into their Wellhub app and navigate to their Receipts and Billing History through "Account." 3. What if my payroll cycle is not monthly? You can process the deduction in one of the payroll cycles or you can split the total amount owed and process in each cycle. 4. Tell me more about Custom Connectors. Custom Connectors are Professional Services developed transformation Connectors that will transform the standard Deduction File content and format, as described here, into a specification aligned to your payroll system. If you would like to explore this option more, please contact your Wellhub Sales or Technical Sales representative.

Encryption Introduction It is optional, but one of the features supported by the Wellhub SFTP Server is file encryption during upload and/or download. Since we are dealing with sensitive data, this provides an extra layer of security. Encryption is enabled for each SSH user. For example, you can have more than one SSH user managing the same company. One with encryption enabled and another without. By default, a new SSH user will have encryption disabled for both uploads and downloads. {% callout title="Note" %} Once encryption is enabled for file uploads, all files must be encrypted. Otherwise, the SFTP Server will reject them. The same applies to file downloads. If encryption is enabled, all downloaded files will be encrypted. {% /callout %} Enabling encryption for file uploads You can enable or disable encryption for uploaded files at any time through the Portal, on the "SFTP" page. 1. Access the SFTP page (side menu, "Settings," then "SFTP") in the Portal. 2. Select an SSH user and click the arrow icon on the right. 3. In the drawer that opens, select "Send encrypted files to Wellhub," enable the toggle, and wait for the "Settings saved" message. {% image src="/assets/sftp/encryption/enable pgp download.png" alt="Enable PGP upload encryption" /%} 4. Click the "Copy" button. The Portal will provide a PGP Public Key . Copy and use this key to encrypt files before sending them to the SFTP Server. Encrypting a file for upload 1. Create a new file, for example pgp key wellhub.pub , and paste the key you copied in the previous step. 2. Import this key by running the following command. gpg import pgp key wellhub.pub 3. Now, you can encrypt a file using the PGP Public Key provided by Wellhub. In the example below, from the recipient "ps@gympass.com.br" , we are encrypting the file employees.csv using the key provided by Wellhub. The result will be a new file called output.csv.gpg . This is the file you can send to the SFTP Server. gpg encrypt recipient ps@gympass.com.br output output.csv.gpg employees.csv Enabling encryption for file downloads To enable the SFTP Server to encrypt files for download, you need to enable encryption in the Portal and register your PGP Public Key, which will be used by the SFTP Server to encrypt the files before download. First, we will generate a new PGP Key. {% callout title="Note" %} https://docs.redhat.com/en/documentation/red hat enterprise linux/6/html/security guide/sect security guide encryption gpg creating gpg keys using the command line and https://docs.github.com/en/authentication/managing commit signature verification/generating a new gpg key generating a gpg key have nice documentation for generating a new GPG key. The key must follow the OpenPGP specification [[RFC 9580]](https://www.rfc editor.org/rfc/rfc9580.html). {% /callout %} Basically, the two terminal commands below should be sufficient. 1. Run the following command. You will be prompted for a name and email to associate with this key. gpg gen key 2. To view your public key for the new PGP Key, run the following command. Replace <RECIPIENT'S EMAIL with the email used to generate the new key. gpg armor export <RECIPIENT'S EMAIL Enabling download encryption via the Portal With the PGP Public Key that will be used by the SFTP Server to encrypt the files to be downloaded, enable download encryption in the Portal. This requires registering the PGP public key . You can enable or disable encryption for downloaded files at any time. 1. Access the SFTP page (side menu, "Settings," then "SFTP") in the Portal. 2. Select an SSH user and click the arrow icon on the right. 3. In the drawer that opens, select "Receive encrypted files from Wellhub," enable the toggle, and paste your public key in the appropriate field . 4. Click "Save settings." Now, all downloads made through the SFTP Server using this same SSH user will be encrypted with your public key. {% image src="/assets/sftp/encryption/pgp key.png" alt="PGP key" /%} Decrypting a downloaded file After downloading gympass year report.zip.pgp , for example, you need to decrypt it. When you run the command, the file will be decrypted into a new file, in this case, called output.zip . gpg decrypt output output.zip gympass year report.zip.pgp PGP MDC PGP MDC, which stands for Modification Detection Code, is a crucial security feature in OpenPGP used to verify the integrity of encrypted messages. In simpler terms, it helps you check if the message you received hasn't been tampered while in transit. Why is PGP MDC important? Ensures message authenticity: With MDC, you can be confident that the message you receive is exactly what the sender sent. If the code doesn't match, it indicates that the message content has been altered. Prevents undetected modifications: Without MDC, even slight changes to the message content can go unnoticed. This is especially important for sensitive information. Mitigates security vulnerabilities: MDC helps protect against attacks where someone might try to intercept and modify an encrypted message. {% callout title="Attention!" %} The Wellhub SFTP system checks all PGP files MDC. The file will be rejected if the encrypted file sent to Wellhub has no MDC enabled. {% /callout %} Additional technical information Checking PGP MDC status depends on the specific software you're using. Since 2003, MDC has been typically enabled by default for new keys in GnuPG. However, there is no direct way to check if MDC was used during encryption for older keys or messages received from others. If messages lack integrity checks (no MDC), you'll encounter warnings during decryption. Newer GPG versions might require enabling workarounds to decrypt such messages, but this is highly discouraged for new messages.

Encryption

Getting Started Introduction Wellhub is a SaaS platform that enables companies to provide a well being benefit to their employees. As a business to business company, Wellhub provides services to subscribing companies and limits access to its platform to its clients' employees and their family members. This model requires Wellhub to validate that people accessing the platform are employees of a subscribing company. It also allows Wellhub to work with the companies to set up employee payments through payroll deductions, much like other benefits that employees may use. While Wellhub has implemented a number of options for handling these processes, the most commonly used options take advantage of simple file exchanges. For Eligibility management, Wellhub receives an Eligibility File from the company. This file contains a minimal set of information that allows Wellhub to validate users and provide a number of communication and reporting services to the company. For Payroll deductions, Wellhub provides a standard Deduction File containing the information required to deduct amounts owed to Wellhub based on employees' use of the Wellhub plans. For Reporting , Wellhub provides a set of reports to monitor the usage of the benefit by the client's employees, including data from the last 12 months (D 2). These are the detailed flows available per entity type: NOTE: SEs single entity; MEs multi entity; CPs channel partners. Flows | Eligibility {% mermaid %} graph TB SFTP["<b SFTP</b "] Full["<b Full file</b <br/ Full eligibles overwrite<br/ <i SEs · MEs · CPs</i "] New["<b Newcomers</b <br/ New eligibles creation<br/ <i SEs</i "] Leavers["<b Leavers</b <br/ Remove eligibles<br/ <i SEs</i "] SFTP Full SFTP New SFTP Leavers classDef greenBox fill: c8e6c9,stroke: 4caf50,stroke width:2px classDef yellowBox fill: fff9c4,stroke: fbc02d,stroke width:2px class SFTP greenBox class Full,New,Leavers yellowBox {% /mermaid %} {% mermaid %} graph TB SFTP["<b SFTP</b "] Download["<b Download eligible list</b <br/ Access the list of all eligible employees<br/ <i SEs</i "] UploadHistory["<b Upload history</b <br/ Get the list and status of previous uploads<br/ <i SEs · MEs · CPs</i "] ErrorDetails["<b Error details</b <br/ Access the errors of a failed update<br/ <i MEs · CPs</i "] EmailRejected["<b Email for rejected uploads</b <br/ Alert for rejected SFTP uploads<br/ <i MEs · CPs</i "] SFTP Download SFTP UploadHistory SFTP ErrorDetails SFTP EmailRejected classDef greenBox fill: c8e6c9,stroke: 4caf50,stroke width:2px classDef yellowBox fill: fff9c4,stroke: fbc02d,stroke width:2px class SFTP greenBox class Download,UploadHistory,ErrorDetails,EmailRejected yellowBox {% /mermaid %} Flows | Payroll For clients with payroll as a 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. {% mermaid %} graph TB SFTP["<b SFTP</b "] Deduction["<b Deduction file download</b <br/ Access the list with the relevant paycheck<br/ deduction amount per employee<br/ <i SEs · MEs </i "] LeaversPayroll["<b Deduction file for leavers download</b <br/ Filtered list with the paycheck deduction<br/ information for removed employees<br/ <i SEs · MEs </i "] SFTP Deduction SFTP LeaversPayroll classDef greenBox fill: c8e6c9,stroke: 4caf50,stroke width:2px classDef yellowBox fill: fff9c4,stroke: fbc02d,stroke width:2px class SFTP greenBox class Deduction,LeaversPayroll yellowBox {% /mermaid %} 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. Flows | Reporting The reporting flow is crucial to track the usage of the Wellhub benefit, as it provides a view on the adoption of the solution, as well as the subscriptions data and check ins of employees and family members (in case the client has that SKU). {% mermaid %} graph TB SFTP["<b SFTP</b "] Reports["<b Reports .zip download</b <br/ Access the reporting files with data<br/ from the last 12 months D 2<br/ <i SEs</i "] ER["<b Engagement rates</b <br/ Daily snapshot of the total of eligibles,<br/ members, subscribers, and family members<br/ if applicable"] CI["<b Check ins</b <br/ Full list of the check ins in Wellhub partners<br/ both physical and virtual activities.<br/ Includes family member data if applicable"] SS["<b Subscribers snapshot</b <br/ Full list of the subscribers and their subscription<br/ details, including the plan selected and price.<br/ Includes family member data if applicable"] SH["<b Subscription history</b <br/ Full list of transaction events related to<br/ an employees subscription, such as: first subscription,<br/ upgrade, downgrade, pause, cancellation,<br/ and new subscription.<br/ Includes family member data if applicable"] SFTP Reports Reports ER Reports CI Reports SS Reports SH classDef greenBox fill: c8e6c9,stroke: 4caf50,stroke width:2px classDef yellowBox fill: fff9c4,stroke: fbc02d,stroke width:2px classDef grayBox fill: e0e0e0,stroke: 757575,stroke width:2px class SFTP greenBox class Reports grayBox class ER,CI,SS,SH yellowBox {% /mermaid %} Wellhub supports SSH File Transfer Protocol (SFTP) to ensure security in these file exchanges. SFTP uses the Secure Shell (SSH) network protocol and public/private key pairs to enforce security. General Information Connection settings Host: sftp.clients.wellhub.com Port: 443 Limits {% table %} Limit Value Total number of sessions per client 5 Max file size 40 Mb Total number of files per session 2 Unprocessed files per session 1 Accepted file types .xlsx , .xlsx.pgp , .xlsx.gpg , .csv , .csv.pgp , .csv.gpg {% /table %} Authentication To interact with the SFTP Server, you'll need to generate an SSH key in your computer and create an SSH user in the Wellhub Clients Portal , and once that is done, you'll then need to register your SSH public key in the Wellhub Clients Portal. Generate an SSH Key You can generate a new SSH key on your local machine. 1. Open a Terminal and paste the text below, replacing the email "your email@example.com" used in the example with your email address. ssh keygen t ed25519 C "your email@example.com" {% callout title="Note" %} When executing this command, the SSH key generator will ask for information such as where to save the new key and whether or not it should have a passphrase. If you have any doubts during this process, refer to this step by step guide from https://docs.github.com/en/authentication/connecting to github with ssh/generating a new ssh key and adding it to the ssh agent generating a new ssh key. {% /callout %} Create an SSH User With an SSH key in hand, access the https://clients.gympass.com/ using your Wellhub account. The process for creating a new SSH user is the same, regardless of the type of management of your Wellhub account. 1. Just make sure to correctly select which entity you want to manage through the SFTP Server, that is, just one company (through Single Entity) or multiple companies (All companies access for Multi Entity; or Channel partners). {% image src="/assets/sftp/sftp entities.png" /%} 2. In the sidebar menu, click Settings , and in the Automations section, click SFTP . {% image src="/assets/sftp/sftp se settings page.png" /%} 3. Now, on the SFTP page, click on Create SSH key . 4. Give a name to this new user and paste the public key of your new SSH key in the appropriate field. {% image src="/assets/sftp/sftp se create user ssh 1.png" /%} 5. After clicking Create , you should be able to see your new SSH user listed on the SFTP page. {% image src="/assets/sftp/sftp se create user ssh 2.png" /%} Accessing the SFTP Server Before connecting to the SFTP Server, we need the User name of an SSH user created in the Portal. By accessing the Portal and navigating to the SFTP page, we can see all SSH users created to manage this company. 1. Go to the SFTP page (sidebar menu, Settings , then SFTP ) in the Portal. 2. Choose an SSH user and click the right arrow icon. 3. In the drawer, click Copy or manually copy the User name . {% image src="/assets/sftp/sftp se copy username.png" /%} Connect to the SFTP Server 1. Open a terminal and run the command below, replacing your username with the User name copied in the previous step. sftp P 443 i /.ssh/id ed25519 your username@sftp.clients.wellhub.com The flag i /.ssh/id ed25519 indicates the location of your SSH key's private key. Change the location if necessary. 2. Upon executing this command, you should see the welcome message from the SFTP Server. {% image src="/assets/sftp/sftp welcome.png" /%} File Exchange Frequency The first production Eligibility File must be sent to Wellhub at least one week before the date that the Wellhub program will be announced to your company’s employees. Then, for maintenance purposes, the Eligibility File must be sent to Wellhub at a minimum once a month . However, when integrating full files we don't recommend sending it more than once a day. File Format Requirements It must include the configured eligible identifiers for the client/company tax id see further details here The header is mandatory, and needs to be in English for all countries The column order is not mandatory The column titles (attribute names) must be written exactly as indicated on Unknown columns will be ignored The CSV can use any of the accepted separators, as: comma (,), semicolon ( ; ), tab, and space CSV UTF 8 is the format supported National ID and Tax ID are validated as a mask. If they are wrong, an error is thrown see further details here Accepted file types: ".xlsx", ".csv" for SSH; ".xlsx.pgp", ".xlsx.gpg", ".csv.pgp", ".csv.gpg" if PGP is enabled Note that even though ".csv" is supported, since this file format can be mutable, using ".xlsx" or encrypted files with PGP is highly recommended. File Naming Convention For production: your company name Eligibility mmddyyyy.csv For test: your company name Eligibility Test mmddyyyy.csv

SFTP This section contains documentation about Wellhub's SFTP product, which allows you to securely exchange Eligibility, Payroll, Reporting and Credits files with Wellhub. Available guides /docs/sftp/getting started /docs/sftp/instructions for single entity /docs/sftp/instructions for multi entity /docs/sftp/instructions for channel partners /docs/sftp/encryption /docs/sftp/troubleshooting

SFTP

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 {% mermaid %} graph TB SFTP["<b SFTP</b "] Full["<b Full file</b <br/ Full eligibles overwrite"] SFTP Full classDef greenBox fill: c8e6c9,stroke: 4caf50,stroke width:2px classDef yellowBox fill: fff9c4,stroke: fbc02d,stroke width:2px class SFTP greenBox class Full yellowBox {% /mermaid %} Details {% mermaid %} graph TB SFTP["<b SFTP</b "] Download["<b Download eligible list</b <br/ Access the list of all eligible employees"] UploadHistory["<b Upload history</b <br/ Get the list and status of previous uploads"] ErrorDetails["<b Error details</b <br/ Access the errors of a failed update"] EmailRejected["<b Email for rejected uploads</b <br/ Alert for rejected SFTP uploads"] SFTP Download SFTP UploadHistory SFTP ErrorDetails SFTP EmailRejected classDef greenBox fill: c8e6c9,stroke: 4caf50,stroke width:2px classDef yellowBox fill: fff9c4,stroke: fbc02d,stroke width:2px class SFTP greenBox class Download,UploadHistory,ErrorDetails,EmailRejected yellowBox {% /mermaid %} Encrypt the content of files you upload and/or download. See /docs/sftp/encryption. To manage multiple companies under the channel partners structure, you must select Channel partners view when generating the SFTP keys. See /docs/sftp/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 {% highlight %}/{% /highlight %}. {% highlight %}/channelpartner{% /highlight %} is the directory representing all companies under the channel partner's structure. {% highlight %}/channelpartner/employees/upload/all{% /highlight %} is the directory to use if you need to update the employee database by uploading a "Fullfile" file. {% highlight %}/channelpartner/employees/upload/error details{% /highlight %} is the directory containing a failed upload error report. {% highlight %}/channelpartner/employees/upload/error details/{Timestamp} {Uploaded Filename}.csv{% /highlight %} is the error report referring to a specific upload. {% highlight %}/channelpartner/employees/upload/status.csv{% /highlight %} is the file containing the status of the latest uploads. {% highlight %}/channelpartner/employees/download/{Timestamp} Eligible list.csv{% /highlight %} 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. {% callout title="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). {% /callout %} 1. Navigate to the /channelpartner/employees/upload/all . cd /channelpartner/employees/upload/all 2. 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 {% excel table title="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 | {% /excel table %} 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. cd /channelpartner/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). | 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. 1. Navigate to the /channelpartner/employees/upload/error details directory. And display the list of error details. cd /channelpartner/employees/upload/error details ls 2. 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. 1. Navigate to the /channelpartner/employees/download directory for this company. cd /channelpartner/employees/download 2. 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 {% highlight %}/{% /highlight %}. {% highlight %}/channelpartner{% /highlight %} is the directory representing all companies under the channel partner's structure. {% highlight %}/channelpartner/flexben/upload/add or update{% /highlight %} is the directory to use if you need to create new credits and/or update existing ones. {% highlight %}/channelpartner/flexben/upload/removal{% /highlight %} should be used to delete credits. {% highlight %}/channelpartner/flexben/download/upload history.csv{% /highlight %} is the file containing the status of the latest uploads. {% highlight %}/channelpartner/flexben/download/errors/{% /highlight %} is the directory containing the failed upload error report. {% highlight %}/channelpartner/flexben/download/errors/{Timestamp} {Uploaded Filename}.csv{% /highlight %} is the error report referring to a specific upload. {% highlight %}/channelpartner/flexben/download/beneficiaries list.csv{% /highlight %} 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/ . cd /channelpartner/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 {% excel table title="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 | {% /excel table %} Upload a Credits removal file 1. Navigate to the /channelpartner/flexben/upload/removal/ . cd /channelpartner/flexben/upload/removal/ 2. The command below uploads the .csv file, deleting the credits. put credits removal.csv File Organization {% excel table title="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 | {% /excel table %} 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. cd /channelpartner/flexben/download 2. The command below downloads the upload history.csv file. get upload history.csv File Organization {% excel table title="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 | {% /excel table %} 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. cd /channelpartner/flexben/download/errors/ ls 2. The command below downloads the error details file. get 1736255395 credit employees.csv File Organization {% excel table title="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. | {% /excel table %} 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. cd /channelpartner/flexben/download 2. The command below downloads the beneficiaries list.csv file. get beneficiaries list.csv File Organization {% excel table title="Example file beneficiaries list.csv" %} | Company Tax ID | Email | National 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 | {% /excel table %}

Instructions for Channel Partners

Instructions for Multi Entity

Instructions for Single Entity Introduction When you want to manage just one company, we call this Single Entity . Through Wellhub's SFTP Server, you can perform certain operations for a specific company. 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 a Single Entity : Creation and updates {% mermaid %} graph TB SFTP["<b SFTP</b "] Full["<b Full file</b <br/ Full eligibles overwrite<br/ <i SEs · MEs · CPs</i "] New["<b Newcomers</b <br/ New eligibles creation<br/ <i SEs</i "] Leavers["<b Leavers</b <br/ Remove eligibles<br/ <i SEs</i "] SFTP Full SFTP New SFTP Leavers classDef greenBox fill: c8e6c9,stroke: 4caf50,stroke width:2px classDef yellowBox fill: fff9c4,stroke: fbc02d,stroke width:2px class SFTP greenBox class Full,New,Leavers yellowBox {% /mermaid %} Details {% mermaid %} graph TB SFTP["<b SFTP</b "] Download["<b Download eligible list</b <br/ Access the list of all eligible employees<br/ <i SEs</i "] UploadHistory["<b Upload history</b <br/ Get the list and status of previous uploads<br/ <i SEs · MEs · CPs</i "] ErrorDetails["<b Error details</b <br/ Access the errors of a failed update<br/ <i MEs · CPs</i "] EmailRejected["<b Email for rejected uploads</b <br/ Alert for rejected SFTP uploads<br/ <i MEs · CPs</i "] SFTP Download SFTP UploadHistory SFTP ErrorDetails SFTP EmailRejected classDef greenBox fill: c8e6c9,stroke: 4caf50,stroke width:2px classDef yellowBox fill: fff9c4,stroke: fbc02d,stroke width:2px class SFTP greenBox class Download,UploadHistory,ErrorDetails,EmailRejected yellowBox {% /mermaid %} 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. {% mermaid %} graph TB SFTP["<b SFTP</b "] Deduction["<b Deduction file download</b <br/ Access the list with the relevant paycheck<br/ deduction amount per employee"] Leavers["<b Deduction file for leavers download</b <br/ Filtered list with the paycheck deduction<br/ information for removed employees"] SES["<b SEs</b "] MES["<b MEs </b "] SFTP Deduction SFTP Leavers Deduction SES Deduction MES Leavers SES Leavers MES classDef greenBox fill: c8e6c9,stroke: 4caf50,stroke width:2px classDef yellowBox fill: fff9c4,stroke: fbc02d,stroke width:2px classDef grayBox fill: e0e0e0,stroke: 757575,stroke width:2px class SFTP greenBox class Deduction,Leavers yellowBox class SES,MES grayBox {% /mermaid %} 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. Flows | Reporting The reporting flow is crucial to track the usage of the Wellhub benefit, as it provides a view on the adoption of the solution, as well as the subscriptions data and check ins of employees and family members (in case the client has that SKU). {% mermaid %} graph TB SFTP["<b SFTP</b "] Download["<b Reporting (.zip) download</b <br/ Access the reporting files with data from<br/ the last 12 months D 2"] SES["<b SEs</b "] SFTP Download Download SES SES ER["<b Engagement rates</b <br/ Daily snapshot that contains all of<br/ eligibles, members, subscribers,<br/ and family members if applicable"] SES CI["<b Check ins</b <br/ Full list of the check ins in<br/ Wellhub in person, physical<br/ and virtual activities.<br/ Includes family member data if applicable"] SES SS["<b Subscribers snapshot</b <br/ Full list of the subscribers and<br/ their subscription details,<br/ including the plan selected and price.<br/ Includes family member data if applicable"] SES SH["<b Subscription history</b <br/ Full list of transaction events<br/ related to an employee subscription,<br/ such as: first subscription, upgrade,<br/ downgrade, pause, cancellation.<br/ Includes family member data if applicable"] classDef greenBox fill: c8e6c9,stroke: 4caf50,stroke width:2px classDef yellowBox fill: fff9c4,stroke: fbc02d,stroke width:2px classDef grayBox fill: e0e0e0,stroke: 757575,stroke width:2px class SFTP greenBox class Download yellowBox class ER,CI,SS,SH yellowBox class SES grayBox {% /mermaid %} Encrypt the content of files you upload and/or download. See /docs/sftp/encryption. The following sections provide more details on each operation. Overview of the directory structure / └── {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. Get to know more regarding Eligibility and the mandatory fields in the https://developer hub.wellhub.com//docs/getting started. Overview of the employees directory structure / └── {CompanyID}/ ├── employees/ │ ├── download/ │ │ └── eligible list.zip │ └── upload/ │ ├── all/ │ ├── error details/ │ │ ├── {Timestamp} {Uploaded Filename}.csv │ │ └── ... │ ├── leavers/ │ ├── new/ │ └── status.csv └── ... The initial directory is the root {% highlight %}/{% /highlight %}. {% highlight %}/{CompanyID}{% /highlight %} is the directory representing the company being managed. The directory name is the UUID of the company. {% highlight %}/{CompanyID}/employees{% /highlight %} is the directory where we can manage the employees of this company, for organizational purposes. {% highlight %}/{CompanyID}/employees/upload/all{% /highlight %} is the directory where we can update the employee base by uploading a Full file. {% highlight %}/{CompanyID}/employees/upload/new{% /highlight %} is the directory where we can update the employee base by uploading a Newcomers file. {% highlight %}/{CompanyID}/employees/upload/leavers{% /highlight %} is the directory where we can update the employee base by uploading a Leavers file. {% highlight %}/{CompanyID}/employees/upload/status.csv{% /highlight %} is the file where we can download and view the status of each upload. {% highlight %}/{CompanyID}/employees/upload/error details{% /highlight %} is the directory where we can download the errors of a rejected upload. {% highlight %}/{CompanyID}/employees/upload/{Timestamp} {Uploaded Filename}.csv{% /highlight %} is the error report of a specific upload. {% highlight %}/{CompanyID}/employees/download/eligible list.zip{% /highlight %} 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. {% callout title="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. {% /callout %} 1. Navigate to the /{CompanyID}/employees/upload/all directory for this company. cd /{CompanyID}/employees/upload/all 2. Upload the all employees.csv file and replace the existing one with your file containing the full list of employees for a company. put all employees.csv File Organization {% excel table title="Example file all employees.csv" %} | Name | Email | National ID | Employee ID | Department | Payroll ID | Cost center | Office zip code | Payroll Enabled | | | | | | | | | | | | Freyja Obrien | freyja.obrien@coolcompany.com | 257.573.080 52 | 331234 | UX | 1324 | 1 114 873 | 04571 926 | Yes | | Ciara Walter | ciara.walter@coolcompany.com | 700.594.980 30 | 834372 | Engineering | 7375 | 1 114 773 | 04571 926 | No | {% /excel table %} 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. cd /{CompanyID}/employees/upload/new 2. Upload the new employees.csv file. Replace new employees.csv with your file containing the list of new employees. put new employees.csv File Organization {% excel table title="Example file new employees.csv" %} | Name | Email | National ID | Employee ID | Department | Payroll ID | Cost center | Office zip code | Payroll Enabled | | | | | | | | | | | | Freyja Obrien | freyja.obrien@coolcompany.com | 257.573.080 52 | 331234 | UX | 1324 | 1 114 873 | 04571 926 | Yes | | Ciara Walter | ciara.walter@coolcompany.com | 700.594.980 30 | 834372 | Engineering | 7375 | 1 114 773 | 04571 926 | No | {% /excel table %} 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. cd /{CompanyID}/employees/upload/leavers 2. Upload the remove employees.csv file. Replace employees.csv with your file containing the list of employees to be removed. 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. cd /{CompanyID}/employees/upload 2. Download the status.csv file. get status.csv File Organization It contains information about the status of the last 20 uploads (regardless of their source). {% table %} 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 {% /table %} 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. cd /{CompanyID}/employees/upload/error details ls 2. List the available error files. ls 3. Download 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. {% table %} Company Tax ID Error Source Line ID Field Name Error Type Error Description N/A This refers at what level the error occurred: Upload error or Client error impacted the whole file, 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 {% /table %} 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. cd /{CompanyID}/employees/download 2. Download the eligible list.zip file. Extract the zip file to access the list. 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. {% callout title="Note" %} Only employees with payroll enabled will appear in the payroll files. {% /callout %} Get to know more regarding Payroll on the Payroll section. Overview of the payroll file structure / └── {CompanyID}/ ├── employees/ ├── payroll/ │ ├── leavers/ │ │ ├── YYYYMM wellhub partial payroll deduction.csv │ │ └── ... │ ├── YYYYMM wellhub payroll deduction.csv │ └── ... └── ... The initial directory is the root {% highlight %}/{% /highlight %}. {% highlight %}/{CompanyID}{% /highlight %} is the directory representing the company being managed. The directory name is Wellhub's UUID for the company. {% highlight %}/{CompanyID}/payroll{% /highlight %} is the directory where the payroll files are available for download. {% highlight %}/{CompanyID}/payroll/YYYYMM wellhub payroll deduction.csv{% /highlight %} 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. {% highlight %}/{CompanyID}/payroll/leavers/YYYYMM wellhub partial payroll deduction.csv{% /highlight %} 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. cd /{CompanyID}/payroll 2. Download a payroll file. get YYYYMM wellhub payroll deduction.csv File Organization {% excel table title="Example file YYYYMM wellhub payroll deduction.csv" %} | Full name | Email | National ID | Employee ID | Amount due | Department | Cost center | Office zip code | Payroll ID | | | | | | | | | | | | Freyja Obrien | freyja.obrien@coolcompany.com | 257.573.080 52 | 331234 | R$ 449,90 | UX | 1324 | 04571 926 | 1324 | | Ciara Walter | ciara.walter@coolcompany.com | 700.594.980 30 | 834372 | R$ 449,90 | Engineering | 7375 | 04571 926 | 7375 | {% /excel table %} 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. cd /{CompanyID}/payroll/leavers 2. Download a payroll file. 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 / └── {CompanyID}/ ├── employees/ ├── payroll/ └── reports/ └── wellhub year report.zip The initial directory is the root {% highlight %}/{% /highlight %}. {% highlight %}/{CompanyID}{% /highlight %} is the directory representing the company being managed. The directory name is the UUID of the company. {% highlight %}/{CompanyID}/reports/wellhub year report.zip{% /highlight %} 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. cd /{CompanyID}/reports 2. Download the yearly usage report file. 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).

Instructions for Single Entity

Troubleshooting File is not uploadable Cause: The file failed validation. Possible reasons: Incompatible file format. /docs/sftp/getting started limits supported file formats. Empty file (0 bytes). Missing required data. Eligibility file uploads require some mandatory information. See the file structure for /docs/sftp/instructions for single entity file organization, /docs/sftp/instructions for multi entity file organization, or /docs/sftp/instructions for channel partners file organization. Unexpected extension for encrypted file Cause: Uploading a file without a .pgp or .gpg extension when encrypted upload is enabled. How to solve: Make sure you upload an encrypted file with the correct extension ( .pgp or .gpg ), or disable encryption in the https://clients.gympass.com/ if it is not needed. Unexpected extension for non encrypted file Cause: Encrypted upload is not enabled, but an encrypted file ( .pgp or .gpg ) was uploaded. How to solve: Send the file without encryption, or enable encryption in the https://clients.gympass.com/ if it is needed. PGP key errors Common errors: gopenpgp: unable to parse public key: gopenpgp: error in reading key ring: openpgp: invalid argument: no armored data found. gopenpgp: error in reading message: openpgp: incorrect key. gopenpgp: error in reading key ring: openpgp: invalid argument: no armored data found. Possible reasons: Invalid or malformed public key. Incorrect key for the client. The key is not in the expected format (non armored or corrupted). How to solve: Verify that the provided public key is valid, matches the client, and is correctly formatted. More information about encryption can be found in the /docs/sftp/encryption section. Operation is not supported for path When interacting with SFTP, not all operations ( put , rename and remove ) are allowed and therefore some error messages may appear. Put /multientity/reports/my report.zip: put is not supported for path /multientity/reports/my report.zip Rename /multientity/reports/gympass year report.zip: put is not supported for path /multientity/reports/renamed file.zip Remove is not supported for path /multientity/reports/gympass year report.zip How to solve: Confirm that the destination directory allows this operation. Files in some directories cannot be removed or renamed. Similarly, files cannot be uploaded to certain directories. See the permitted operations in the /docs/sftp/instructions for single entity, /docs/sftp/instructions for multi entity, or /docs/sftp/instructions for channel partners sections. Verify that the path is correct (e.g., uploads should occur in /uploads/ ). The directory structure may vary slightly depending on the client type. See the directories for /docs/sftp/instructions for single entity, /docs/sftp/instructions for multi entity, and /docs/sftp/instructions for channel partners.