Getting Started

As a Wellhub Client, your company is able to offer Wellhub to its employees. Normally, you would maintain a list of eligible employees by uploading spreadsheets (also known as Eligibility Files) or adding employees to Wellhub one at a time in the Wellhub for Companies platform. With Eligibility API integration, you can connect Wellhub to your existing HCM system to automatically manage your list of eligible employees.

The regular flow is:

With Eligibility API:

Architecture Style

Wellhub's APIs are built following the REST architecture style to describe the interface. We use the JSON format for the data exchange.

Here's what you need to know:

• You'll find endpoints that use the proposed HTTP request methods to define the operation you want to occur in the server side;
• These endpoints are defined so you can predict which resource you're dealing with by looking at the URL;
• Every server response uses proper HTTP response status codes, with proper distinction between successful requests as well as unsuccessful ones (both from client-side and server-side errors);
• For data exchange, be prepared to deal with JSON format for both requests and responses.

Authentication

Wellhub API Key

The Wellhub API authentication process depends on API key usage. This gives you the ability to have one authentication credential stored in your code that will permit access to all of our APIs.

You can create API keys anytime in Wellhub for Companies by going to Settings > Add API key or Settings > Manage keys > Add API key.

The following table illustrates which integration type will use which authentication method with the Wellhub API key.

Authentication methods

Every API interaction must use the Wellhub API Key as an authentication Bearer token, otherwise the standard HTTP status code in the response will be 403 Forbidden. In practical terms, every request made is expected to define an Authentication header, and its value is expected to be something like: Bearer {{Wellhub API Key}}.

Eligibility Integration example

Request Example

--header 'Content-Type: application/json' \
1--header 'Authorization: Bearer {{Wellhub API Key}}' \
2--data-raw '{
3   ...
4}'

Eligibility API

Wellhub receives employee information via Eligibility API in real time as you add or remove employees from your HCM. This creates a faster signup experience for new employees and promptly offboards any terminated employees so that your Enterprise Subscription will always reflect your current headcount.

Endpoints Summary

The following is a list of the endpoints provided by the Eligibility API.

Eligibility Identifier

In the API, certain actions may involve identifying data using the Eligibility Identifier. The Eligibility Identifier refers to the personal unique information assigned to an employee when granting them eligibility to use Wellhub. The type of information in the Eligibility Identifier is defined when the client signs their contract with Wellhub.

An Eligibility Identifier is composed of one main identifier and optional supporting data. There are three available types of data that can be part of an Eligibility Identifier: email, national ID and employee ID. Even though all of them can be persisted through the API, only the main identifier will be required to identify employees during API calls.

Security disclosure: To ensure the security of employee data, certain special characters (e.g. % /) may be disallowed when querying employees through the API endpoint's path. This measure is in place to protect against potential Path Traversal attacks. Source: OWASP.

Environment URLs

The APIs are public, and ready to use. But we provide a Sandbox environment, where you can test your integration with no side effects. When you're ready to launch your integration, use the Production environment.

You'll find the endpoints for each operation described throughout the document. Make sure you're considering the correct environment as the base URL for your calls.

Production: https://api.clients.gympass.com

Sandbox: https://sandbox.clients.gympass.com

Throttling

Limits are placed on the number of API requests you can make with your API key. The current state makes no distinction between API keys, as this is a work in progress. Therefore, the current limits of our environments default to:

• Time Limit: 1.6 million requests per hour (450 requests per second)
• Burst: 50 parallel requests per second

Any requests that exceed these limits will be denied. Denials are in the format of a 429 Too Many Requests status code response, as per RFC 6585, section 4.

Error handling

The following table shows status codes for error cases, along with the cause of and solution to each error.