Heading

strong

I'm new to Wellhub integrations

CustomLink

Callout

I want to implement a specific flow

I already know my integration technology

thead

tbody

Table

article

Eligibility FAQ 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. For validation and security, we strongly advise against including National Identification data (e.g., CPF, National Insurance Number, or US Social Security Number) within the Employee ID field. The Employee ID should ideally contain a unique internal company identifier. If you have any questions regarding the recommended eligibility key combinations, please contact your sales representative for clarifications. 2. What if all employees do not have an email address? That indicates that the Employee ID 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 and .csv formats are supported. Proper delimiters 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 Eligibility File be sent to Wellhub? Wellhub recommends weekly since this allows new hires to have the quickest access to Wellhub as they onboard. 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 Eligibility File contents? Yes. Name, Email, Employee ID, 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.

Eligibility FAQ

Eligibility Flow The Eligibility flow manages which employees in your organization are eligible to access Wellhub's benefits platform. As a business to business company, Wellhub only provides its services to employees of subscribing companies, and all integration processes begin with establishing and maintaining employee eligibility. This page describes the eligibility flow at a conceptual level. For implementation details, see the integration specific guides linked at the bottom of this page. What Is Eligibility? An eligible is an employee record that has been submitted to Wellhub and grants that employee access to the platform. Eligibility management is the process of keeping these records accurate and up to date as your workforce changes. Supported Operations {% mermaid %} graph TB Eligibility["<b Eligibility</b "] Add["<b Add employees</b <br/ Submit new employee records to grant access to Wellhub"] Update["<b Update employees</b <br/ Modify existing records to reflect changes in employee data"] Remove["<b Remove employees</b <br/ Revoke access for employees who should no longer be eligible"] Eligibility Add Eligibility Update Eligibility Remove classDef blueBox fill: bbdefb,stroke: 1976d2,stroke width:2px classDef yellowBox fill: fff9c4,stroke: fbc02d,stroke width:2px class Eligibility blueBox class Add,Update,Remove yellowBox {% /mermaid %} How these operations are expressed depends on the integration technology. For file based integrations (SFTP), they map to specific submission types (full file, newcomers, leavers). For API integrations, they map to specific endpoint calls. See the guides under implement this flow for details. Data Model Each eligibility record is made up of the standard Wellhub employee attributes. See the /docs/getting started/glossary wellhub data model in the Glossary for the full field reference. Eligibility Identifiers Each employee is uniquely identified in Wellhub by an Eligibility Identifier . The identifier is defined in your contract and is one of the following configurations: | Configuration | Required fields | | | | | Email | email | | Employee ID | employee id | | National ID | national id | | Employee ID and National ID | employee id and national id | | Mobile Number | mobile number | Fields that do not compose the Eligibility Identifier can be stored but are optional. Eligibility identifiers cannot be changed once set — they are the permanent key used to look up an employee record. The exception is the Employee ID and National ID configuration: in this case, employee id is the primary identifier and cannot be updated, while national id is treated as a regular field that can be updated by referencing the employee via their employee id . When this configuration is used, both fields are required and each enforces its own uniqueness constraint independently. The same employee id value cannot be assigned to more than one employee, even if their national id values differ, and vice versa. For validation and security, we strongly advise against including National Identification data (e.g., CPF, National Insurance Number, or US Social Security Number) within the Employee ID field. The Employee ID should ideally contain a unique internal company identifier. If you have any questions regarding the recommended eligibility key combinations, please contact your sales representative for clarifications. Examples: In API jobs , the eligibility identifier must be present in the job item creation payload. In SFTP files , the eligibility identifier must be present in the file header and in every data row. {% callout title="Security note" %} Some characters may be blocked or normalized in technical channels (for example, URL paths, query parameters, or file names) to prevent security issues such as path traversal. If you receive a validation or processing error related to an identifier, try encoding or omitting special characters, and coordinate with your Wellhub contact if you need to use a specific format. {% /callout %} Implement This Flow {% callout title="Choose your integration technology" %} The eligibility flow is supported by the following integration technologies. Select the one that matches your setup: /docs/integrations/api/eligibility — Real time, programmatic eligibility management /docs/integrations/sftp/eligibility — Batch file based eligibility management {% /callout %}

Eligibility

Flexible Benefits Flow {% callout title="Availability" %} The Flexible Benefits flow is available for Multi Entity (ME) and Channel Partners (CP) only. Single Entity organizations do not have access to this flow. {% /callout %} The Flexible Benefits flow enables organizations to manage benefit credits for their employees through Wellhub. Credits can be created, updated, or removed, and employees can allocate them to the benefit options that best suit their individual needs. This page describes the flexible benefits flow at a conceptual level. For implementation details, see the integration specific guide linked at the bottom of this page. What Are Flexible Benefits? Flexible benefit credits are amounts assigned by the company to each employee. Employees can then allocate those credits towards the Wellhub benefit options available to them. Companies can add new credits, update existing ones, or remove them entirely as workforce or policy changes occur. Supported Operations {% mermaid %} graph TB FlexBen["<b Flexible Benefits</b "] AddUpdate["<b Add / Update credits</b <br/ Create new credits or update existing ones"] Remove["<b Remove credits</b <br/ Delete existing credits"] History["<b Upload history</b <br/ Status of previous uploads"] Errors["<b Error details</b <br/ Errors from a failed upload"] Beneficiaries["<b Beneficiaries list</b <br/ Snapshot of currently credited employees"] FlexBen AddUpdate FlexBen Remove FlexBen History FlexBen Errors FlexBen Beneficiaries classDef blueBox fill: bbdefb,stroke: 1976d2,stroke width:2px classDef yellowBox fill: fff9c4,stroke: fbc02d,stroke width:2px class FlexBen blueBox class AddUpdate,Remove,History,Errors,Beneficiaries yellowBox {% /mermaid %} Data Model Flexible Benefits records include employee identification fields and credit specific data. See the /docs/getting started/glossary wellhub data model in the Glossary for the full field reference. Implement This Flow {% callout title="Choose your integration technology" %} The Flexible Benefits flow is currently supported by the following integration technology: /docs/integrations/sftp/flexible benefits — Manage benefit credits via SFTP file uploads {% /callout %}

Flexible Benefits

Feature Flows A flow is a business process that defines a specific type of data exchange with Wellhub. Flows are technology agnostic — the same business rules apply regardless of whether you use the REST API, SFTP, or another integration method. Choose the flow that matches your use case, then follow the implementation guide for your chosen integration technology. Available Flows The Documentation Status column below reflects the availability of documentation in this portal, not whether the flow is live in production. Flows marked as "Documentation in progress" are available in production — full documentation is being prepared. | Flow | Description | Documentation Status | | | | | | /docs/flows/eligibility | Manage which employees are eligible to access Wellhub | Available | | /docs/flows/payroll | Download benefit deduction data for payroll processing | Available | | /docs/flows/flexible benefits | Manage flexible benefit credits for employees | Documentation in progress | | /docs/flows/reports | Access usage and adoption reports | Available | | /docs/flows/sign up | Manage employee self enrollment flows | Documentation in progress | Flows × Integrations Compatibility Matrix Not all flows are supported by every integration technology. Use this matrix to find the right combination for your use case. | Flow | REST API | SFTP | SSO | | |: :|: :|: :| | Eligibility | ✓ | ✓ | — | | Payroll | Coming soon | ✓ | — | | Flexible Benefits | Coming soon | ✓ | — | | Reports | Coming soon | ✓ | — | | Sign up | Coming soon | — | ✓ | {% callout title="Need help choosing?" %} If you are unsure which flow and integration technology to use, start with /docs/getting started/concepts or contact your Wellhub integration representative. {% /callout %}

Feature Flows

Payroll FAQ 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 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.

Payroll FAQ

Payroll Flow The Payroll Deductions flow enables your organization to retrieve benefit cost deduction data from Wellhub so it can be applied during your regular payroll processing cycle. When employees choose and enroll in a Wellhub plan, they may pay the monthly subscription fee via payroll deduction. For payroll deductions, Wellhub provides monthly deduction data containing specific information for each charge an employee is responsible for covering in that period. This page describes the payroll deductions flow at a conceptual level. For implementation details, see the integration specific guide linked at the bottom of this page. What Are Payroll Deductions? When employees use Wellhub and their benefit plan includes a co payment or employee contribution, Wellhub calculates the amounts to be deducted from each employee's paycheck. These amounts are made available to your organization through the payroll deductions flow so they can be applied during payroll processing. Supported Operations {% mermaid %} graph TB Payroll["<b Payroll Deductions</b "] Deduction["<b Deductions report</b <br/ Access the list with the relevant paycheck<br/ deduction amount per employee<br/ <i SEs · MEs</i "] Leavers["<b Leavers deductions report</b <br/ Filtered list with the paycheck deduction<br/ information for removed employees<br/ <i SEs · MEs</i "] Payroll Deduction Payroll Leavers classDef blueBox fill: bbdefb,stroke: 1976d2,stroke width:2px classDef yellowBox fill: fff9c4,stroke: fbc02d,stroke width:2px class Payroll blueBox class Deduction,Leavers yellowBox {% /mermaid %} Deduction Cycle Frequency Deduction data is generated and made available at the same time the company invoice is issued, on a monthly basis. The most recent billing cycle's data replaces the previous one each month. Deduction Data The deductions report contains one row per employee with fields reflecting the employee data shared at eligibility (Name, Email, Employee ID, Department, Cost Center, Office ZIP Code, Payroll ID) plus the amount due in local currency. See the /docs/getting started/glossary wellhub data model in the Glossary for the full field reference. {% callout title="Note on multiple charges" %} Because of the flexibility provided to make changes to plans, there may be more than one charge per employee in a billing period. Deduction data sums the amounts for each employee into a single line and single deduction amount. {% /callout %} Implement This Flow {% callout title="Choose your integration technology" %} The payroll deductions flow is currently supported by the following integration technology: /docs/integrations/sftp/payroll — Download deduction files via SFTP {% /callout %}

Payroll

Reports Flow The Reports flow provides organizations with visibility into the usage of the Wellhub benefit by their employees. Reports include data on adoption, subscriptions, check ins, and engagement — covering the last 12 months (data is delayed by 2 days, referred to as D 2). Supported Operations {% mermaid %} graph TB Reports["<b Reports</b "] ER["<b Engagement rates</b <br/ Daily snapshot of total of eligibles,<br/ members, subscribers, and family members<br/ if applicable"] CI["<b Check ins</b <br/ Full list of check ins at Wellhub partner locations<br/ for both physical and virtual activities.<br/ Includes family member data if applicable"] SS["<b Subscribers snapshot</b <br/ Full list of subscribers and their subscription<br/ details, including 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 employee's subscription: first subscription,<br/ upgrade, downgrade, pause, cancellation,<br/ and new subscription.<br/ Includes family member data if applicable"] Reports ER Reports CI Reports SS Reports SH classDef blueBox fill: bbdefb,stroke: 1976d2,stroke width:2px classDef yellowBox fill: fff9c4,stroke: fbc02d,stroke width:2px class Reports blueBox class ER,CI,SS,SH yellowBox {% /mermaid %} Implement This Flow {% callout title="Currently available via SFTP" %} The Reports flow is delivered via SFTP file download. /docs/integrations/sftp/reports — Download report files and understand available report types /docs/integrations/sftp/instructions single entity se — Single Entity directory structure {% /callout %}

Reports

Sign up Flow {% callout title="Documentation in progress" variant="yellow" %} Full documentation for the Sign up flow is being prepared. If you need to implement this flow now, contact your Wellhub integration representative for guidance. {% /callout %} The Sign up flow enables organizations to manage how their employees self enroll in Wellhub benefits, including customization of the enrollment experience. What to Expect How the Wellhub employee sign up process works Configuration options for the sign up flow Which integration technologies support sign up customization Step by step implementation guides Get Help Now If you cannot wait for this documentation to be published, reach out to your Wellhub integration representative directly. They can provide implementation guidance for your specific setup.

Sign-up

Core Concepts Before diving into implementation details, it helps to understand the two fundamental dimensions of any Wellhub integration: flows and integrations . Flows vs. Integrations A flow is a business process that defines what data is exchanged with Wellhub and why. For example, the Eligibility flow describes how employee eligibility records are created, updated, and removed. Flows are technology agnostic — the same business rules apply regardless of whether you use the API or SFTP to implement them. Wellhub currently supports: /docs/flows/eligibility — Manage which employees are eligible to access Wellhub. /docs/flows/payroll — Download benefit deduction data for payroll processing. /docs/flows/flexible benefits — Manage flexible benefit credits for employees. /docs/flows/reports — Access usage and adoption reports. /docs/flows/sign up — Manage employee self enrollment flows. An integration is the technical method used to implement one or more flows. Wellhub currently supports: REST API — Real time, programmatic data exchange over HTTPS. SFTP File Exchange — Batch file based data exchange using structured files (CSV or XLSX) transferred over SFTP. SSO — Single Sign On for user authentication on Sign Up. Not every integration supports every flow. Refer to the /docs/flows overview or the /docs/integrations overview for a full compatibility matrix. The Integration Lifecycle A typical Wellhub integration follows these steps: 1. Understand your flows — Identify which business processes you need to integrate (e.g., eligibility management, payroll deductions). 2. Choose your integration technology — Based on your technical capabilities and the flows you need, select the appropriate technology (API, SFTP, or SSO). 3. Set up your environment — Configure credentials, keys, or certificates as required by your chosen technology (which can be performed on https://clients.gympass.com/). 4. Implement the flows — Follow the implementation guides for each flow under your chosen integration technology. 5. Test in sandbox — Validate your integration in the sandbox environment before going live. 6. Go live — Switch to the production environment and begin exchanging data. Environments Wellhub provides two environments: Sandbox — For development and testing. Data submitted here does not affect production. Currently only available for the REST API. Production — The live environment where real employee data is processed. Data Model & Glossary For a full reference of all data fields used across Wellhub flows — including which fields belong to Eligibility, Payroll, or both — see the /docs/getting started/glossary. The glossary also defines key terms used throughout this documentation. 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 PCI DSS and ISO 27001 certification and with local regulations (e.g. GDPR, LGPD). For detailed questions on Wellhub's security posture, reach out to your Wellhub Customer Engineering representative. SFTP file exchange supports optional /docs/integrations/sftp/encryption for both uploaded and downloaded files, providing an additional layer of protection for sensitive data in transit. Next Steps Read about /docs/getting started/entity types to understand how your organization is represented in Wellhub. Browse /docs/flows to identify which flows apply to your use case. Browse /docs/integrations to choose your implementation technology.

Core Concepts

Entity Types Wellhub organizes companies into three entity types. Your entity type determines how your company is represented in the system, how your eligibility data is structured, and which integration flows and options are available to you. Single Entity (SE) A Single Entity is a company with a single legal entity integrated directly with Wellhub. All employees belong to the same company record. Use this when: Your organization is a single legal entity. You manage employee eligibility under one company profile. Multi Entity (ME) A Multi Entity is a holding company or corporate group that integrates with Wellhub on behalf of multiple subsidiary legal entities. Each subsidiary is represented as a separate entity within Wellhub, but they are all managed under a single parent. Use this when: Your organization has multiple subsidiaries or branches, each with their own HR data. You need to submit eligibility updates that span multiple legal entities (to distinguish them, it's required to include the Company Tax ID). Channel Partners (CP) A Channel Partner is an intermediary (such as an HR software vendor, broker, or benefits administrator) that integrates with Wellhub on behalf of multiple independent client companies. Each client company is onboarded as a separate entity within Wellhub. Use this when: You are a third party platform managing benefits for multiple separate companies. You need to submit eligibility updates for many different clients from a single integration (to distinguish them, it's required to include the Company Tax ID). Summary | Entity Type | Who Uses It | Key Characteristic | | | | | | Single Entity (SE) | Individual companies | One company, one set of employees | | Multi Entity (ME) | Corporate groups / holdings | One parent, multiple subsidiaries | | Channel Partners (CP) | HR platforms, brokers | One integrator, multiple client companies | {% callout title="Why does entity type matter?" %} Your entity type affects how eligibility files are structured (single vs. multiple entity identifiers), which API endpoints are relevant to you, and how SFTP instructions apply. Implementation guides in the /docs/integrations section will indicate when behavior differs by entity type. {% /callout %} {% callout title="Eligibility identifiers" %} Each employee is uniquely identified by an Eligibility Identifier defined per company contract. Available configurations: Email, Employee ID, National ID, Employee ID and National ID, or Mobile Number. See /docs/flows/eligibility eligibility identifiers for details. {% /callout %}

Entity Types

Glossary Wellhub Data Model These are the standard fields used to represent employees across all Wellhub flows, regardless of the integration technology used. The Used In column indicates which flow(s) each field belongs to. Note: Fields with a String format accept any textual value, including alphanumeric and symbol characters. | Field | Description | Format | Used In | | | | | | | Name | Employee's full name. Used in communications | String | Eligibility, Payroll, Reports | | Email | Employee email address. Must be unique per company Tax ID; duplicates accepted at ME/CP level | Valid email address | Eligibility, Payroll, Reports | | National ID | National identification registry. Must be unique per company Tax ID; duplicates accepted at ME/CP level | Alphanumeric; format validated by country mask (e.g. CPF in Brazil) | Eligibility, Payroll, Reports | | Employee ID | Employee identifier within the company's HR system. Must be unique per company Tax ID; duplicates accepted at ME/CP level | Alphanumeric | Eligibility, Payroll, Reports | | Cost Center | Employee's cost center | String | Eligibility, Payroll, Reports | | Department | Employee's department | String | Eligibility, Payroll, Reports | | Office ZIP Code | Employee's office ZIP code | String | Eligibility, Payroll, Reports | | Payroll ID | Identifies the employee in the company's payroll software | String | Eligibility, Payroll, Reports | | Company Tax ID | Identifies to which company an employee belongs | Alphanumeric; special characters accepted | Eligibility, Reports | | Discount Group / Subset ID | Determines which discount group an employee belongs to | Numeric; if empty, the discount group is removed | Eligibility | | Mobile Number | Employee mobile number, can be used for identification. Unique under a given company | Must start with country code ( + ); digits with optional spaces, hyphens, or parentheses; mobile numbers only | Eligibility | | Payroll Enabled | Whether the employee is allowed to use paycheck as a payment method | Yes or No | Eligibility | | Custom Fields | Additional company specific information not covered by standard fields. Must be pre configured with Wellhub; only mapped fields are persisted. | String | Eligibility | | Amount Due | Amount owed by the employee in local currency, as provided in the Payroll Deduction file | Currency symbol + two decimal amount (e.g. $123.45 , R$20,00 ) | Payroll | | Amount | Flexible benefit credit assigned to the employee | Numeric, up to 2 decimal places (e.g. 1000.00 ) | Flexible Benefits | | Last Credited Month | Month in which the employee was most recently credited | Whole number, 1–12 | Flexible Benefits | | Last Credited Year | Year in which the employee was most recently credited | YYYY | Flexible Benefits | | Company Name | Display name of the company or subsidiary | String | Reports | | Date | Date of the daily engagement snapshot | YYYY MM DD | Reports | | Reference Month | Billing or reporting month the file covers | YYYY MM | Reports | | Eligible Employees | Total number of employees added to Wellhub; they are able to sign up and subscribe | Whole number | Reports | | Members | Employees who signed up and have a Wellhub account | Whole number | Reports | | Subscribers | Members who subscribed to a Wellhub plan | Whole number | Reports | | Family Members | People employees bought subscriptions for and invited to Wellhub | Whole number | Reports | | Subscriber Type | Indicates whether the subscriber is an employee or a family member | Employee or Family member | Reports | | Family Member Name | Full name of the family member subscriber | String | Reports | | Family Member Email | Email address of the family member subscriber | Valid email address | Reports | | Family Member ID | Identifier for the family member within Wellhub | Alphanumeric | Reports | | Check in Date | Day when the check in occurred | YYYY MM DD | Reports | | Check in Timezone | Timezone in which the check in was performed; typically based on the partner location | Timezone name (e.g. America/Sao Paulo ) | Reports | | Check in Country | Country where the check in took place | String | Reports | | Check in State | State or province where the check in took place | String | Reports | | Check in City | City where the check in took place | String | Reports | | Check in ZIP Code | ZIP or postal code of the check in location | String | Reports | | Check in Type | How the employee engaged in the activity | In person , Live class , or Partner app | Reports | | Plan Name | Name of the Wellhub plan the employee is subscribed to | String | Reports | | Pre discount Plan Price | Plan price before company discount is applied | Currency amount | Reports | | Company Discount | Discount the company offers employees on their plans | Currency amount | Reports | | Post discount Plan Price | Amount the employee pays after company discount, excluding taxes | Currency amount | Reports | | Plan Currency | Currency of plan prices | 3 letter currency code (e.g. BRL , USD ) | Reports | | Subscription Start Date | Date the employee started their Wellhub plan, including any free trial period | YYYY MM DD | Reports | | Status | Subscription status at the end of the reporting period | Active , Paused , Limited access , or Canceled | Reports | | Transaction Day | Day on which a subscription transaction event occurred | YYYY MM DD | Reports | | Transaction Event | Type of subscription lifecycle event | First subscription , Upgrade , Downgrade , Pause , Cancellation , or New subscription | Reports | Key Terms Business Concepts Eligibility Identifier The attribute (or combination of attributes) used to uniquely identify an employee in Wellhub. Defined per company contract. Can be Email, Employee ID, National ID, Employee ID and National ID, or Mobile Number. Any attribute that does not compose the eligibility identifier for a company is optional. See /docs/flows/eligibility eligibility identifiers. Primary Identifier When an Eligibility Identifier is composed of multiple attributes, the primary identifier is the one used to look up the employee and cannot be updated. In the Employee ID and National ID configuration, employee id is the primary identifier, while national id can be updated by referencing the employee via their employee id . Email An employee's email address. Can serve as an Eligibility Identifier. Must be unique per company Tax ID. National ID A national identification number (e.g. CPF in Brazil). Can serve as an Eligibility Identifier attribute. Format is validated by country mask. Employee ID An employee's identifier within the company's HR system. Can serve as an Eligibility Identifier. Must be unique per company Tax ID. Mobile Number An employee's mobile phone number. Must start with + followed by the country code. Accepted separators are spaces, hyphens, and parentheses. Fixed line, shared cost, and emergency numbers are not accepted. Can serve as an Eligibility Identifier. Must be unique within a given company. Wellhub The corporate wellness platform for which this Developer Hub provides integration documentation. Formerly known as Gympass. Flow A business process that defines a specific type of data exchange with Wellhub (e.g., eligibility, payroll deductions). Flows are technology agnostic. See /docs/flows. Eligibility The process of managing which employees are allowed to use Wellhub's services. See the /docs/flows/eligibility. Eligible An employee record that has been submitted to Wellhub and is eligible to access Wellhub's benefits platform. Full File An eligibility sub flow in which the submitted file represents the complete current state of all eligible employees. Any employee not in the file is considered a leaver. See /docs/flows/eligibility. Newcomer An employee being added to Wellhub eligibility for the first time via a newcomers sub flow. See /docs/flows/eligibility. Leaver An employee who is being removed from Wellhub eligibility, either explicitly (via a leavers file) or implicitly (by absence from a full file). See /docs/flows/eligibility. Family Member A person an employee has purchased a Wellhub subscription for and invited to the platform. Family members can use Wellhub independently and appear alongside the employee in subscription, check in, and reporting data. Availability depends on the company's contract with Wellhub. Member An employee (or family member) who has signed up and created an account on Wellhub, without subscribing to a plan. Payroll Deductions The process by which Wellhub provides deduction files for companies to process benefit cost deductions from employee payroll. See the /docs/flows/payroll. Flexible Benefits The process by which organizations assign benefit credits to employees, who can then allocate those credits towards Wellhub benefit options. Credits can be added, updated, or removed. Available for Multi Entity and Channel Partner organizations. See the /docs/flows/flexible benefits. Reports The process by which Wellhub provides usage and adoption data to organizations, covering engagement rates, check ins, subscriber snapshots, and subscription history over the last 12 months. Available for Single Entity organizations. See the /docs/flows/reports. Entity A company or organizational unit as represented in Wellhub. Depending on your entity type, this may be a single company, a subsidiary, or a client company. See /docs/getting started/entity types. Single Entity (SE) A company that integrates directly with Wellhub as a single legal entity. See /docs/getting started/entity types. Multi Entity (ME) A corporate group or holding company with multiple subsidiaries, all integrated under one parent. See /docs/getting started/entity types. Channel Partner (CP) An intermediary company (e.g., HR software vendor or benefits broker) that integrates with Wellhub on behalf of multiple independent client companies. See /docs/getting started/entity types. Custom Fields Additional company specific information attached to an employee record, beyond the standard Wellhub data model. Custom fields must be pre configured with Wellhub before use: the company works with the responsible Wellhub team to define and map the desired fields. Once configured, they can be submitted via the API using the custom fields object. Only pre configured fields will be persisted; any other keys are ignored. Integration The technical method used to exchange data with Wellhub (e.g., REST API, SFTP). See /docs/integrations. API (Application Programming Interface) A programmatic interface that allows systems to communicate in real time over HTTPS. Wellhub provides a REST API for integration. SFTP (Secure File Transfer Protocol) A file transfer protocol used for batch data exchange. Wellhub supports SFTP for eligibility, payroll, flexible benefits, and reports file transfers. SSO (Single Sign On) An authentication method that allows users to log in to Wellhub using their existing corporate identity provider. Currently used in the Wellhub Sign Up flow. Credentials Authentication secrets (such as client ID and client secret for the API, or SSH keys for SFTP) used to identify and authorize an integration. Job In the context of the REST API, a job is a batch operation that processes a set of eligibility records. A job contains one or more job items. Sandbox Environment A non production Wellhub environment used for development and testing. Data submitted here does not affect real employee records. Production Environment The live Wellhub environment where real data is processed. Contrast with Sandbox.

Glossary

Getting Started This hub is your reference for integrating with Wellhub's platform. Whether you are connecting your HR system to manage employee eligibility, processing payroll deductions, or exploring other benefit flows, you'll find everything you need here. How This Hub Is Organized The documentation is structured around three pillars: Flows — The business processes you can integrate with Wellhub (eligibility, payroll, flexible benefits, and more). Flows describe what happens, independently of the technology you use to implement them. Integrations — The technical methods available to implement those flows (REST API, SFTP file exchange, SSO). Integrations describe how to connect your systems to Wellhub. Getting Started (you are here) — Core concepts, entity types, and a glossary to help you understand the terminology used throughout this hub. Choose Your Path {% callout title="I'm new to Wellhub integrations" %} Start with /docs/getting started/concepts to understand the Wellhub integration model, then read about /docs/getting started/entity types to learn which model applies to your organization. {% /callout %} {% callout title="I want to implement a specific flow" %} Go to /docs/flows to find the flow you need (eligibility, payroll, flexible benefits, reports, or sign up) and understand its business logic before choosing a technology. {% /callout %} {% callout title="I already know my integration technology" %} Go to /docs/integrations to find the technical guide for your chosen method (REST API, SFTP, or SSO) and see which flows each technology supports. {% /callout %} Quick Reference | Section | Description | | | | | /docs/getting started/concepts | Understand the Wellhub integration model | | /docs/getting started/entity types | Single Entity, Multi Entity, Channel Partners | | /docs/getting started/glossary | Definitions of key terms | | /docs/flows | All available business flows | | /docs/integrations | All available integration technologies |

Getting Started

Wellhub Developer Hub This hub is your reference for integrating your systems with Wellhub. Whether you are managing employee eligibility, processing payroll deductions, or enabling employee self enrollment, you will find the concepts, guides, and references you need here. Where to Start {% callout title="New to Wellhub integrations?" %} Begin with /docs/getting started to understand the integration model, entity types, and key terminology. {% /callout %} {% callout title="Looking for a specific business process?" %} Go to /docs/flows to find the flow you need — eligibility, payroll, flexible benefits, reports, or sign up. {% /callout %} {% callout title="Ready to implement?" %} Go to /docs/integrations to find the technical guide for your chosen method — REST API, SFTP, or SSO. {% /callout %} Documentation Sections | Section | Description | | | | | /docs/getting started | Core concepts, entity types, and glossary | | /docs/flows | Business processes available for integration | | /docs/integrations | Technical implementation guides |

Documentation

Eligibility via REST API Use the Eligibility Management API to keep your employee roster in sync with Wellhub so onboarding and offboarding stay up to date. The API follows REST conventions and uses JSON for all requests and responses, where the latter follow standard HTTP status codes to distinguish success and error scenarios. For information about BASE URL and ACCESS TOKEN values, see /docs/integrations/api/getting started. For an overview of Eligibility Identifiers and Entity Types, see /docs/getting started/entity types. 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 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 | Identifies to which company an employee belongs | | 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 | Employee is allowed to use paycheck as a payment method | | payroll id | string | No | Employee identifier in company's payroll software | | mobile number | string | Yes | Mobile phone number of the employee. | | discount subset id | string | No | Identifier for the discount group applicable to the employee, when able. | | custom fields | object | No | Additional custom fields as key value pairs. | {% callout %} Depending on the Eligibility Identifier defined in the company's contract with Wellhub, some of these fields may turn out to be optional. For example: | Configuration | Required fields | | | | | Email | email | | Employee ID | employee id | | National ID | national id | | Employee ID and National ID | employee id and national id | | Mobile Number | mobile number | All other identifier fields are optional for the configurations above. For full details on how each identifier configuration works, see /docs/flows/eligibility eligibility identifiers. Contact your Wellhub integration representative if you are unsure which identifier applies to your contract. {% /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 | | 413 | Content Too Large (request body exceeds 1 MB limit) | | 500 | Internal Server Error | Example request — CREATE [ { "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 request — UPDATE [ { "operation": "UPDATE", "company tax id": "1234567890", "employee id": "E 1029", "full name": "Maria Santos", "email": "maria.santos@acme.com", "national id": "12345678901", "department": "Engineering", "cost center": "CC 002", "office zip code": "12345", "eligible to payroll": true, "payroll id": "PAY 123", "mobile number": "+5511999999999", "discount subset id": "1", "custom fields": { "location": "Sao Paulo" } } ] {% callout title="Note" %} For UPDATE operations, any omitted field will be set to an empty value ( "" ). To preserve an existing value, always include it explicitly in the request. The exception is eligible to payroll : its behavior when omitted depends on whether the company has payroll enabled. If payroll is not enabled, the field always defaults to false . If payroll is enabled, omitting the field preserves the existing value when one is already set, or defaults to true when no value has been set yet. custom fields behaves differently: only fields pre configured by Wellhub for your company will be persisted or updated. To set up or modify your custom fields mapping, contact your Wellhub integration representative. {% /callout %} Example request — DELETE [ { "operation": "DELETE", "company tax id": "1234567890", "employee id": "E 1029" } ] {% callout title="Note" %} For DELETE operations, only the fields required to identify the employee (based on the eligibility identifier) and company tax id are needed. All other fields are ignored. {% /callout %} 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. Pagination works as follows: when a response includes a non null cursor field, pass that value as the cursor query parameter in the next request to retrieve the next page. When cursor is null , you have reached the last page. Do not construct or modify cursor values — treat them as opaque tokens. Curl example curl X GET "{{BASE URL}}/v1/eligibility/jobs/{{job id}}/items?cursor={{cursor}}" \ H "Authorization: Bearer {{ACCESS TOKEN}}" \ H "Content Type: application/json" 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": "1", "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": "PROCESSING", "updated at": "2026 01 20T10:30:00Z", "statistics": { "newcomers": 10, "updaters": 3, "leavers": 2 } } Possible Job Status {% mermaid %} stateDiagram v2 draft : DRAFT pending : PENDING validating : VALIDATING processing : PROCESSING approvalRequested : APPROVAL REQUESTED succeededWithErrors : SUCCEEDED WITH ERRORS internalServerError : INTERNAL SERVER ERROR succeeded : SUCCEEDED rejected : REJECTED [ ] draft draft pending pending validating validating processing validating approvalRequested validating rejected processing succeededWithErrors processing internalServerError processing succeeded approvalRequested succeeded approvalRequested rejected succeededWithErrors [ ] succeeded [ ] rejected [ ] internalServerError [ ] {% /mermaid %} {% spacer /%} | Status | Description | | : | : | | Draft | Job is in draft state and not yet submitted for validating. | | Pending | Job is awaiting user action before processing. | | Validating | Job is currently being validated and a change request is in progress; if not rejected, will be processed shortly. | | Processing | Job is currently being processed. | | Succeeded with errors | Job has been partially processed, with error entries that must be fixed. | | Approval Requested | Job has a pending approval request by either Wellhub or the benefits manager due to extensive breaking changes in the eligible base. | | Rejected | Job has been rejected. | | Succeeded | Job was processed successfully. | | Internal Server Error | A server side error occurred during processing. It is recommended to try again. | 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": [ { "change number": 1, "field name": "EMAIL", "field value": "invalid email", "error type": "WRONG FORMAT", "recovered by": null, "company tax id": "1234567890" }, { "change number": 2, "field name": "EMPLOYEE ID", "field value": "E 1029", "error type": "CONFLICT", "recovered by": null, "company tax id": "1234567890" } ] } Response fields | Field | Type | Description | | | | | | change number | integer | The sequential number of the item within the job that caused the error. | | field name | string | The name of the field that triggered the error. See possible error details. | | field value | string | The value that was submitted for the field. | | error type | string | The type of error. See possible error details. | | recovered by | string or null | If the error was automatically recovered, indicates the recovery method. null when not recovered. | | company tax id | string | The company tax ID associated with the item that caused the error. | Possible Error Details The table below lists all possible field name and error type combinations that can be returned in the job errors response. | field name | error type | Description | | : | : | : | | COMPANY TAX ID | INVALID COMPANY TAX ID | The company tax ID does not match any valid company within the entity or group. | | EMAIL | MISSING | The email field is required based on the eligibility identifier but was not provided. | | EMAIL | WRONG FORMAT | The email address is not in a valid format (expected: name@example.com ). | | EMAIL | DUPLICATED | The same email address appears more than once in the job. | | EMAIL | DOMAIN UNREACHABLE | The email domain could not be reached or verified. | | EMAIL | NOT FOUND | The email does not match any existing eligible record. Applies to UPDATE and DELETE operations. | | EMAIL | CONFLICT | The email conflicts with an existing eligible record that belongs to a different employee. | | NATIONAL ID | MISSING | The national ID field is required based on the eligibility identifier but was not provided. | | NATIONAL ID | WRONG FORMAT | The national ID is not in a valid format. | | NATIONAL ID | DUPLICATED | The same national ID appears more than once in the job. | | NATIONAL ID | NOT FOUND | The national ID does not match any existing eligible record. Applies to UPDATE and DELETE operations. | | NATIONAL ID | CONFLICT | The national ID conflicts with an existing eligible record that belongs to a different employee. | | EMPLOYEE ID | MISSING | The employee ID field is required based on the eligibility identifier but was not provided. | | EMPLOYEE ID | DUPLICATED | The same employee ID appears more than once in the job. | | EMPLOYEE ID | NOT FOUND | The employee ID does not match any existing eligible record. Applies to UPDATE and DELETE operations. | | EMPLOYEE ID | CONFLICT | The employee ID conflicts with an existing eligible record that belongs to a different employee. | | MOBILE NUMBER | MISSING | The mobile number field is required based on the eligibility identifier but was not provided. | | MOBILE NUMBER | WRONG FORMAT | The mobile number is not in a valid format. Must include the international country code (e.g., +1 999 999 9999 ). | | MOBILE NUMBER | DUPLICATED | The same mobile number appears more than once in the job. | | MOBILE NUMBER | NOT FOUND | The mobile number does not match any existing eligible record. Applies to UPDATE and DELETE operations. | | MOBILE NUMBER | CONFLICT | The mobile number conflicts with an existing eligible record that belongs to a different employee. | | DISCOUNT SUBSET ID | WRONG FORMAT | The discount subset ID is not in a valid format. | 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", "full name": "John Doe", "email": "john.doe@acme.com", "employee id": "E 2048", "national id": "10987654321", "invitation status": "ACTIVE", "mobile number": "+5511988888888", "cost center": "CC 001", "department": "Engineering", "office zip code": "20040 020", "payroll id": "PAY 2048", "discount subset id": null, "eligible to payroll": true, "deleted at": null, "updated at": "2026 01 20T11:00:00Z" } ] } 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", "full name": "Maria Santos", "email": "maria.santos@acme.com", "employee id": "E 1029", "national id": "12345678901", "invitation status": "INVITED", "mobile number": "+5511999999999", "cost center": "CC 001", "department": "People", "office zip code": "01310 100", "payroll id": "PAY 1029", "discount subset id": null, "eligible to payroll": false, "deleted at": null, "updated at": "2026 01 20T10:30:00Z" } ] } 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 via REST API

Getting Started with the REST API {% callout title="⚠ Important!" variant="yellow" %} We are currently migrating to the new version of the API. The old API will be discontinued. Sandbox environment is already available, where you can test and validate your operations. Expected release date for production API is May 2026 . {% /callout %} {% spacer /%} {% callout title="Prerequisites" %} Before getting started, check /docs/getting started/entity types if you're not familiar with the identifiers and entity concepts used in the API. The /docs/flows/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. Rate limits All endpoints are rate limited, and those limits are enforced on two dimensions: Rate limit — maximum requests per minute (RPM). Burst limit — maximum requests per second allowed in a short spike. Limits are tracked per client. | Endpoint | Method | Rate limit | Burst | | | | | | | /oauth/token | POST | 5 RPM | 5 req/s | | /v1/eligibility/jobs | POST | 25 RPM | 5 req/s | | /v1/eligibility/jobs/{job id}/submit | POST | 25 RPM | 5 req/s | | /v1/eligibility/jobs/{job id}/items | POST | 50 RPM | 20 req/s | | /v1/eligibility/jobs/{job id}/items | GET | 50 RPM | 20 req/s | | /v1/eligibility/jobs/{job id}/status | GET | 50 RPM | 20 req/s | | /v1/eligibility/jobs/{job id}/errors | GET | 50 RPM | 20 req/s | | /v1/employees | GET | 300 RPM | 5 req/s | | /v1/companies/{company tax id}/employees | GET | 300 RPM | 5 req/s | | /v1/companies | GET | 300 RPM | 5 req/s | Requests that exceed a limit return 429 Too Many Requests . Responses include standard rate limit headers ( RateLimit Limit , RateLimit Remaining , RateLimit Reset ) so you can track consumption and back off accordingly.

Getting Started with the REST API

REST API Integration The REST API integration enables real time, programmatic data exchange with Wellhub over HTTPS. It is best suited for organizations with software engineering capabilities who need to integrate eligibility management directly into their HR systems or internal tools. Supported Flows | Flow | Supported | | |: :| | /docs/flows/eligibility | ✓ | | /docs/flows/payroll | Coming soon | | /docs/flows/flexible benefits | Coming soon | | /docs/flows/reports | Coming soon | | /docs/flows/sign up | Coming soon | When to Use the REST API You need real time eligibility updates (e.g., on employee hire, termination, or data change events). You have engineering resources to build and maintain an API integration. You want fine grained control over individual employee record operations. Getting Started {% callout title="Set up your API credentials" %} Before implementing any flow, you need to configure authentication credentials for the API. /docs/integrations/api/getting started {% /callout %} Implementation Guides /docs/integrations/api/getting started — Authentication, environments, and first steps /docs/integrations/api/eligibility — Manage employee eligibility records programmatically

REST API

Integrations

Eligibility via SFTP This guide covers how to implement the /docs/flows/eligibility using Wellhub's SFTP file exchange. Prerequisites Completed /docs/integrations/sftp/getting started (SSH keys and server connection). Familiarity with the /docs/flows/eligibility. Knowledge of your /docs/getting started/entity types (SE, ME, or CP). Supported Operations Upload operations (Eligibility management) SFTP based eligibility management uses three submission types, each suited to a different scenario: {% 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 %} Full File A full file submission represents the complete, current list of all eligible employees. When processed, Wellhub will: Add any employees in the file who are not yet eligible. Update records for employees already in the system. Remove (as leavers) any employees currently in the system who are absent from the file. Use full file when you want to synchronize the entire eligible population in a single operation. Supported for Single Entity, Multi Entity, and Channel Partners. Newcomers A newcomers submission contains only employees being added to eligibility for the first time. Existing eligible employees are not affected. Use newcomers when you want to onboard a batch of new employees without touching existing records. Supported for Single Entity only. Leavers A leavers submission contains only employees who should be removed from eligibility. No new employees are added. Use leavers when employees leave your organization or should otherwise lose access to Wellhub. Supported for Single Entity only. Management operations (Details & history) {% 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 %} Entity Type Specific Instructions The directory structure, supported operations, and file format details differ by entity type. See the /docs/integrations/sftp/instructions page for complete guidance per entity type: /docs/integrations/sftp/instructions single entity se /docs/integrations/sftp/instructions multi entity me /docs/integrations/sftp/instructions channel partners cp

Eligibility via SFTP

Encryption Introduction PGP encryption is optional but supported for both file uploads and downloads on the Wellhub SFTP Server, providing an extra layer of security for sensitive data. Encryption is configured per SSH user. A company can have multiple SSH users, each with its own encryption settings. By default, encryption is disabled for both uploads and downloads on new SSH users. {% callout title="Note" %} Once encryption is enabled for uploads, all uploaded files must be encrypted — the SFTP Server will reject any unencrypted file. Similarly, once encryption is enabled for downloads, all files downloaded through that SSH user will be encrypted. {% /callout %} Encrypting file uploads When upload encryption is enabled, you are responsible for encrypting files before sending them to Wellhub. Files are encrypted using Wellhub's PGP public key , which is provided by the Portal. Step 1 — Enable upload encryption and get Wellhub's public key 1. In the Portal, go to the SFTP page (side menu → "Settings" → "SFTP"). 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" confirmation. 4. Click "Copy" to copy Wellhub's PGP public key. {% image src="/assets/sftp/encryption/enable pgp download.png" alt="Enable PGP upload encryption" /%} Step 2 — Import Wellhub's public key Create a new file (e.g. pgp key wellhub.pub ) and paste the key you copied. Then import it: gpg import pgp key wellhub.pub Step 3 — Encrypt and upload Encrypt your file using Wellhub's public key. Use the recipient email address associated with the imported key (visible after importing with gpg list keys ): gpg encrypt recipient <recipient from wellhub key output output.csv.gpg employees.csv Upload the resulting .gpg file to the SFTP Server. Encrypting file downloads When download encryption is enabled, Wellhub encrypts files before making them available for download. Files are encrypted using your PGP public key , which you register in the Portal. You then decrypt downloaded files using your private key. Step 1 — Generate a PGP key pair {% 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 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 %} Run the following command and follow the prompts to associate a name and email with the key: gpg gen key Then export your public key. Replace <YOUR EMAIL with the email used to generate the key: gpg armor export <YOUR EMAIL Step 2 — Enable download encryption and register your public key 1. In the Portal, go to the SFTP page (side menu → "Settings" → "SFTP"). 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 PGP public key in the field provided. 4. Click "Save settings" . All files downloaded through this SSH user will now be encrypted with your public key. {% image src="/assets/sftp/encryption/pgp key.png" alt="PGP key" /%} Step 3 — Decrypt downloaded files After downloading an encrypted file (e.g. gympass year report.zip.pgp ), decrypt it using your private key: gpg decrypt output output.zip gympass year report.zip.pgp PGP MDC PGP MDC (Modification Detection Code) is a security feature in OpenPGP that verifies the integrity of encrypted messages — it confirms that a file has not been tampered with in transit. {% callout title="Attention!" %} The Wellhub SFTP Server validates MDC on all incoming PGP files. Files uploaded without MDC enabled will be rejected. {% /callout %} Technical notes MDC has been enabled by default in GnuPG since 2003 for new keys. If you receive a warning about missing integrity checks during decryption, the file was encrypted without MDC. Newer GPG versions may require workarounds to decrypt such files — this is strongly discouraged for any new encryption.

Encryption

Flexible Benefits via SFTP This guide covers how to implement the /docs/flows/flexible benefits using Wellhub's SFTP file exchange. Prerequisites Completed /docs/integrations/sftp/getting started (SSH keys and server connection). Employees must already be created in the /docs/flows/eligibility before they can receive flexible benefit credits. Knowledge of your /docs/getting started/entity types — Flexible Benefits are available for Multi Entity (ME) and Channel Partners (CP) . Supported Operations {% mermaid %} graph TB SFTP["<b SFTP</b "] AddUpdate["<b Add / Update credits</b <br/ Create new credits or update existing ones"] Remove["<b Remove credits</b <br/ Delete existing credits"] History["<b Upload history</b <br/ Status of previous uploads"] Errors["<b Error details</b <br/ Errors from a failed upload"] Beneficiaries["<b Beneficiaries list</b <br/ Snapshot of currently credited employees"] SFTP AddUpdate SFTP Remove SFTP History SFTP Errors SFTP Beneficiaries AddUpdate ME1["<b ME</b "] AddUpdate CP1["<b CP</b "] Remove ME2["<b ME</b "] Remove CP2["<b CP</b "] History ME3["<b ME</b "] History CP3["<b CP</b "] Errors ME4["<b ME</b "] Errors CP4["<b CP</b "] Beneficiaries ME5["<b ME</b "] Beneficiaries CP5["<b CP</b "] 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 AddUpdate,Remove,History,Errors,Beneficiaries yellowBox class ME1,ME2,ME3,ME4,ME5,CP1,CP2,CP3,CP4,CP5 grayBox {% /mermaid %} Add / Update Credits Upload a file to create new benefit credits or update existing ones for employees. Credits allow employees to allocate amounts to the benefit options that best suit their needs. Remove Credits Upload a file to delete existing credits for employees. {% callout title="Partial uploads accepted" %} Flexible Benefits uploads accept partial submissions. Valid rows are processed normally; rows with errors are rejected individually. Whenever a full or partial rejection occurs, admins are notified via email. {% /callout %} Upload History Download a status file listing all previous Flexible Benefits uploads. Each row records one upload event and includes the following columns: | Column | Description | | | | | File name | Identifier of the uploaded file. Follows the format {unix timestamp} {original filename} , where the numeric prefix is a Unix epoch timestamp recording the exact moment the file was submitted. | | Upload date + time | Date and time the upload was processed, in UTC. | | Type | Operation type: ADD or CANCEL . | | Method | How the upload was triggered: SFTP , WEB , ELIGIBILITY LOSS , RELOCATION , or REASSOCIATION . | | Status | Processing outcome: SUCCEEDED , REJECTED , ERROR , or CANCELED . | | Author | Username of the person who submitted the upload. | | Errors | Number of errors recorded for the upload. | Error Details Download a report of errors from a failed or partially rejected upload, with details on what needs to be corrected. Error files use the same naming convention as the File name column in the upload history: {unix timestamp} {original filename}.csv . The timestamp matches the one shown in the history record, making it straightforward to correlate an error file with its corresponding upload event. Beneficiaries List Download a snapshot of all currently credited employees, showing the current state of benefit credit allocations. File Fields Flexible Benefits files contain a combination of employee identification fields and credit specific data. See the /docs/getting started/glossary wellhub data model in the Glossary for the full field reference. Entity Type Specific Instructions The directory structure and operation details differ by entity type. See the /docs/integrations/sftp/instructions page for complete guidance: /docs/integrations/sftp/instructions multi entity me /docs/integrations/sftp/instructions channel partners cp

Flexible Benefits via SFTP

Getting Started with SFTP Wellhub supports SSH File Transfer Protocol (SFTP) for secure file exchanges. SFTP uses the Secure Shell (SSH) network protocol and public/private key pairs to enforce security. {% callout title="SHA 1 SSH algorithms are being discontinued" variant="yellow" %} Support for SHA 1 based SSH algorithms on the Wellhub SFTP server is being deprecated. All clients should migrate to Ed25519 or other supported algorithms now. See ssh key algorithm requirements for details and a migration checklist. {% /callout %} 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 on your computer, create an SSH user in the Wellhub Clients Portal, and register your SSH public key. Generate an SSH Key 1. Open a Terminal and paste the text below, replacing the email 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. Select which entity you want to manage through the SFTP Server — a single company (Single Entity) or multiple companies (All companies access for Multi Entity; or Channel Partners). {% image src="/assets/sftp/sftp entities.png" /%} {% image src="/assets/sftp/multientity/manage keys.png" alt="All companies view (Multi Entity / Channel Partners)" /%} 2. In the sidebar menu, click Settings , and in the Automations section, click SFTP . {% image src="/assets/sftp/sftp se settings page.png" /%} 3. On the SFTP page, click 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 , your new SSH user will be 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, you need the User name of an SSH user created in the Portal. 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" /%} SSH Key Algorithm Requirements Wellhub's SFTP server supports modern SSH key algorithms. To maintain a secure connection environment, support for SSH algorithms that rely on SHA 1 is being deprecated and will eventually be discontinued. Why SHA 1 is being deprecated SHA 1 (Secure Hash Algorithm 1) is a cryptographic hash function historically used in SSH key and host key algorithms to verify authenticity. Over time, SHA 1 has become vulnerable to practical collision attacks — where two different inputs can produce the same hash value — which breaks a core security guarantee and makes it unsuitable for modern cryptographic use. Continuing to rely on SHA 1 based algorithms exposes clients to: Potential impersonation or man in the middle attacks if collisions are exploited Reduced trust in the integrity and authenticity of SSH connections Non compliance with modern security recommendations and best practices Supported SSH key algorithms The SFTP server currently supports the following SSH public key algorithms: {% table %} Algorithm Notes Ed25519 (recommended) Modern, fast, and secure elliptic curve algorithm. Recommended as the default for all new and existing clients. ECDSA (SHA 2 family) Elliptic curve algorithms using SHA 2 digests, available in most modern SSH clients. RSA with SHA 2 RSA key algorithms using SHA 2 digests rather than SHA 1 for signatures. {% /table %} Prioritize Ed25519 wherever possible — it provides strong security with smaller keys and better performance compared to traditional RSA based algorithms. Deprecation timeline There is currently no fixed date set for the full removal of SHA 1 based SSH algorithms. However, the deprecation is in progress and support may be removed after an appropriate notice period. {% callout title="Important" %} Do not wait for a fixed cutoff date. Migrate to SHA 1 free configurations now to avoid disruptions once SHA 1 based algorithms are ultimately disabled. {% /callout %} Migration checklist Use the following checklist to migrate away from SHA 1 based SSH algorithms: 1. Inventory existing keys and configurations: Identify all client systems and automated jobs that connect to the SFTP server, and list the SSH key types and algorithms they currently use. 2. Generate new Ed25519 keys: Create new Ed25519 key pairs for each client and store private keys securely (see generate an ssh key above). 3. Register new keys with the SFTP server: Add the new public keys to the Portal as described in create an ssh user. 4. Update client configurations: Configure SSH clients to prefer Ed25519 and SHA 2 based algorithms and to stop offering SHA 1 based algorithms during negotiation. 5. Test and phase out legacy keys: Validate connectivity using the new keys, update automation and documentation, then remove remaining SHA 1 dependent keys and algorithms from use. 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. For maintenance purposes, the Eligibility File must be sent to Wellhub at a minimum once a month . When integrating full files, sending it more than once a day is not recommended. File Format Requirements It must include the configured eligible identifiers for the client/company tax ID — see /docs/getting started/entity types for details 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 specification Unknown columns will be ignored The CSV can use any of the accepted separators: 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 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

Getting Started with SFTP

SFTP File Exchange Integration The SFTP File Exchange integration enables batch data exchange with Wellhub using structured files (CSV or XLSX) transferred over Secure File Transfer Protocol (SFTP). It is best suited for organizations that prefer file based integration or whose HR systems can generate periodic export files. Supported Flows | Flow | Supported | | |: :| | /docs/flows/eligibility | ✓ | | /docs/flows/payroll | ✓ | | /docs/flows/flexible benefits | ✓ | | /docs/flows/reports | ✓ | | /docs/flows/sign up | — | When to Use SFTP Your HR system supports periodic file exports (e.g., daily, weekly, or monthly). You prefer batch processing over real time API calls. You need payroll deductions or reports, which are only available via SFTP. Getting Started {% callout title="Set up your SFTP connection" %} Before implementing any flow, you need to configure SSH keys and establish a connection to the Wellhub SFTP server. /docs/integrations/sftp/getting started {% /callout %} Implementation Guides /docs/integrations/sftp/getting started — SSH key setup, server details, file formats /docs/integrations/sftp/eligibility — Submit eligibility files via SFTP /docs/integrations/sftp/payroll — Download payroll deduction files via SFTP /docs/integrations/sftp/reports — Download usage and adoption report files via SFTP /docs/integrations/sftp/flexible benefits — Manage benefit credits via SFTP /docs/integrations/sftp/instructions — Entity type specific directory structure (SE, ME, CP) /docs/integrations/sftp/encryption — PGP file encryption setup /docs/integrations/sftp/troubleshooting — Common errors and solutions

SFTP File Exchange

SFTP Instructions

Payroll via SFTP This guide covers how to implement the /docs/flows/payroll using Wellhub's SFTP file exchange. Prerequisites Completed /docs/integrations/sftp/getting started (SSH keys and server connection). Familiarity with the /docs/flows/payroll. Supported Operations {% mermaid %} graph TB SFTP["<b SFTP</b "] Deduction["<b Deduction file</b <br/ Paycheck deduction amount per employee"] LeaversDed["<b Deduction file for leavers</b <br/ Deductions for removed employees"] SFTP Deduction SFTP LeaversDed Deduction SE1["<b SE</b "] Deduction ME1["<b ME </b "] LeaversDed SE2["<b SE</b "] LeaversDed ME2["<b ME </b "] 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,LeaversDed yellowBox class SE1,SE2,ME1,ME2 grayBox {% /mermaid %} \ For Multi Entity, only a .zip file is currently available (containing individual files). A consolidated file will be added in the future. Overview Payroll deductions via SFTP use a file download model . Wellhub generates the deduction file at the end of each billing cycle and places it in your designated SFTP download directory. You download the file and process the deductions in your payroll system. 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 (if the content hasn't been shared, it will be blank) The currency will follow the client's location (if there are entities with different locations/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 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 are generated and available at the same time the company invoice is issued. You will find the deduction file for the latest billing cycle in the Payroll SFTP folder. On a monthly basis, it will be replaced by the most recent file. File Naming Convention Single Entity Deduction file: YYYYMM wellhub payroll deduction.csv Example: 202507 wellhub payroll deduction.csv If there is more than one file issued, versioning is applied: 202507 wellhub payroll deduction 1.csv , 202507 wellhub payroll deduction 2.csv Deduction file for leavers: YYYYMM wellhub partial payroll deduction.csv Example: 202507 wellhub partial payroll deduction.csv Multi Entity Deduction file: ClientName YYYYMM wellhub payroll deduction.csv Example: Clientname1 202507 wellhub payroll deduction.csv Deduction file for leavers: ClientName YYYYMM wellhub partial payroll deduction.csv Example: Clientname1 202507 wellhub partial payroll deduction.csv File Contents See the /docs/getting started/glossary wellhub data model in the Glossary for the full field reference. There will be only one record per 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. Any questions as to the nature of the charge can be answered by the employee logging into their Wellhub app under Profile → Settings → Account → Receipts or Billing History.

Payroll via SFTP

Reports via SFTP This guide covers how to access the /docs/flows/reports using Wellhub's SFTP file exchange. Prerequisites Completed /docs/integrations/sftp/getting started (SSH keys and server connection). Familiarity with the /docs/flows/reports. Knowledge of your /docs/getting started/entity types — Reports are available for Single Entity (SE) only. Supported Operations Reports are provided as a .zip file download. The zip contains individual report files, each covering a specific dimension of benefit usage over the last 12 months (D 2). {% mermaid %} graph TB SFTP["<b SFTP</b "] Zip["<b Reports (.zip) download</b <br/ Reporting files covering the last 12 months D 2"] SE["<b SE</b "] ER["<b Engagement rates</b <br/ Daily snapshot of eligibles,<br/ members, subscribers, and family members"] CI["<b Check ins</b <br/ Full list of check ins at Wellhub<br/ in person and virtual activities.<br/ Includes family member data if applicable"] SS["<b Subscribers snapshot</b <br/ Full list of subscribers with<br/ plan and price details.<br/ Includes family member data if applicable"] SH["<b Subscription history</b <br/ Transaction events: first subscription,<br/ upgrade, downgrade, pause, cancellation.<br/ Includes family member data if applicable"] SFTP Zip Zip SE SE ER SE CI SE SS SE SH classDef greenBox fill: c8e6c9,stroke: 4caf50,stroke width:2px classDef grayBox fill: e0e0e0,stroke: 757575,stroke width:2px classDef yellowBox fill: fff9c4,stroke: fbc02d,stroke width:2px class SFTP greenBox class SE grayBox class Zip,ER,CI,SS,SH yellowBox {% /mermaid %} Engagement Rates A daily snapshot that captures the total number of eligibles, members, subscribers, and family members (if applicable). Use this to track adoption trends over time. Check ins A full list of all check ins at Wellhub partner locations, covering both in person and virtual activities. Includes family member data if the client has that SKU. Subscribers Snapshot A full list of current subscribers with their subscription details, including the plan selected and price. Includes family member data if applicable. Subscription History A full list of transaction events related to each employee's subscription lifecycle: first subscription, upgrade, downgrade, pause, cancellation, and new subscription. Includes family member data if applicable. Report Fields Each report file contains a combination of employee attributes and report specific metrics. See the /docs/getting started/glossary wellhub data model in the Glossary for the full field reference. Entity Type Specific Instructions Reports are currently available for Single Entity only. See the /docs/integrations/sftp/instructions single entity se page for the directory structure and download guide.

Reports via SFTP

Troubleshooting File is not uploadable Cause: The file failed validation. Possible reasons: Incompatible file format. /docs/integrations/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/integrations/sftp/instructions single entity se, /docs/integrations/sftp/instructions multi entity me, or /docs/integrations/sftp/instructions channel partners cp. 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. gopenpgp: unsupported feature: message is not integrity protected 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/integrations/sftp/encryption section. Connection timeouts Cause: The client is unable to connect to sftp.clients.wellhub.com on port 443. The server may be unreachable, or the connection times out before it can be fully established. Possible reasons: A firewall rule is blocking outbound traffic to sftp.clients.wellhub.com on port 443, making the server unreachable or causing the connection to be dropped. A proxy or SSL inspection tool is intercepting the connection. A recent network or security policy change on the client's side is dropping the traffic before it reaches our server. How to solve: Check whether any network or security configuration changes were recently made that could be interfering with the connection (e.g., new firewall rules, proxy settings, or security policies). Verify whether a firewall, proxy, or SSL inspection tool is intercepting traffic to sftp.clients.wellhub.com and add an exception if needed. 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/integrations/sftp/instructions single entity se, /docs/integrations/sftp/instructions multi entity me, or /docs/integrations/sftp/instructions channel partners cp sections. Verify that the path is correct (e.g., uploads should occur in /upload/ ). The directory structure may vary slightly depending on the client type. See the directories for /docs/integrations/sftp/instructions single entity se, /docs/integrations/sftp/instructions multi entity me, and /docs/integrations/sftp/instructions channel partners cp.

Troubleshooting

SSO Integration {% callout title="Documentation in progress" variant="yellow" %} Full documentation for the SSO integration is being prepared. If you need to implement SSO now, contact your Wellhub integration representative for guidance. {% /callout %} The SSO (Single Sign On) integration enables employees to sign up to Wellhub using their existing corporate identity provider (IdP), automatically entering their required personal information to create a Wellhub account. What This Guide Will Cover Supported identity providers and protocols (e.g., SAML 2.0, OIDC) SSO configuration in the Wellhub partner portal Which flows are enhanced or enabled by SSO Step by step setup guide Get Help Now If you cannot wait for this documentation to be published, reach out to your Wellhub integration representative directly. They can provide implementation guidance and share any available interim resources for your IdP.

Section	Description
Core Concepts	Understand the Wellhub integration model
Entity Types	Single Entity, Multi Entity, Channel Partners
Glossary	Definitions of key terms
Feature Flows	All available business flows
Integrations	All available integration technologies