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

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

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.

Implement This Flow