Migration FAQs

General

1. When is the new Clients API expected to launch?

The new API launched in May 2026 — both production and sandbox environments are now live.

2. Why are we changing to a new API?

We are launching the new Clients API to replace the old Eligibility API due to architectural constraints, including the lack of a consistent data validation flow and proper logging/auditing. This update is designed to improve the experience, particularly for Enterprise clients, by:

  1. Improving security: Moving from the legacy API key/token model to industry-standard OAuth 2.0 client credentials and introducing key rotation.
  2. Enhancing reliability and performance: Rebuilding the architectural foundation to be more resilient and faster, even when handling a large volume of data.
  3. Optimizing Eligibility handling: Introducing a standardized validation flow, clear success/error feedback, and error prevention mechanisms to ensure data accuracy and prevent accidental removals.
  4. Expanding scope: The API will expand beyond Eligibility management to include Payroll, Reports, and Flexible Benefits, centralizing all Wellhub flows in a single integration.

3. What is the initial scope of the new Clients API?

For its initial launch, the API scope is limited to Eligibility management. However, the plan is to expand its flows to include Payroll, Reports, and Flexible Benefits.

Migration & Old API Keys

1. When is the deadline to migrate from the old Eligibility API to the new Clients API?

Clients currently using the old Eligibility API are required to migrate to the new API by September 2026.

2. Until when can I use the old API?

You can continue using the old API until September 2026.

3. What are the key steps required for migration?

The migration process involves:

  1. Reviewing the new documentation to make necessary technical adjustments.
  2. Accessing the new API management experience on Wellhub for Companies to generate credentials for test and production purposes.
  3. Creating new API credentials to obtain a unique Client ID and Client Secret.
  4. Using those new credentials to begin submitting requests and developing the integration.

4. Is my current API key inactive?

The keys for the old API will remain active until it is discontinued in September 2026. However, you won't be able to generate new keys under the legacy authentication scheme.

5. Why don't I see my old API keys?

The old API used a legacy API key + token authentication flow that is no longer compatible with the new API. To interact with the new Clients API, you will need to generate new OAuth 2.0 credentials. While the old API keys aren't displayed on the UI, they remain active until the integration is discontinued in September 2026.

6. Can I use the current key to connect to the new API?

No, the new Clients API authentication protocol is OAuth 2.0. You will need to generate new credentials for the new integration.

7. Do I need to deactivate the old key/API integration?

No, the old keys will be deactivated automatically.

New API Authentication

1. What is the new authentication method for the Clients API?

The Clients API now uses OAuth 2.0 client credentials for authentication, replacing the current Bearer token approach.

2. How do I obtain API credentials (Client ID and Client Secret)?

Credentials must be obtained through the Settings section on the Wellhub for Companies platform. You must be an admin user and have an API registration on the system.

3. What are the key security enhancements for authentication?

The new API offers reinforced security and control through:

  • Customizable key expiration: Credentials can be customized for 1-year rotation (recommended), 2 years, or set to never expire.
  • Key expiration reminders: If an expiration period is defined, an email reminder will be sent 4 weeks before the key expires.
  • Granular roles and access: You can define the specific flows and actions that each key is authorized to perform.
  • Centralized management: Users handling multiple related companies can create an aggregate key to manage them centrally.

Eligibility Management

1. What eligibility operations can I perform?

You can perform eligibility operations such as: inserting, updating, and deleting employee records, retrieving a job's status, and retrieving the list of eligibles and companies under a group structure.

2. What new capabilities are included in Eligibility management?

Key enhancements include:

  • Simplified endpoint logic: A single endpoint manages all eligibility-related operations (insert, update, delete).
  • Apply changes confidently: You can make a series of changes, review them, and either submit or discard all changes at once.
  • Real-time error handling: The system provides error feedback and required actions for faulty details upon validation.
  • Error prevention: Operations considered risky (e.g., excessive deletion) are flagged for internal review to prevent erroneous actions.