Endpoints

Employees

An eligible employee represents an individual who is associated with your company, can sign up for a Wellhub account, and can subscribe to a plan as defined by your company's contract.

Create Many

This endpoint creates multiple new eligible employees simultaneously. Initially, the limit is set to 10 per request in this endpoint.

The response will show a list of the Eligibility Identifiers for each of the created eligible employees.

Our bulk endpoint works as a single unit to ensure data consistency and integrity. This means that if any operation in a batch fails, the entire batch will fail. In case of a failure, you'll receive detailed error information specifying which operation caused it. So, make sure all operations in your batch are correct and valid before submitting them.

POST {{environment-url}}/eligibility/v1/employees/bulk-create

Request Example
1curl --location --request POST '{{environment-url}}/eligibility/v1/employees/bulk-create' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer {{Wellhub API Key}}' \
4--data-raw'[
5  {
6    "email": "string",
7    "national_id": "string",
8    "full_name": "string",
9    "employee_id": "string",
10    "additional_fields": {
11      "department": "string",
12      "cost_center": "string",
13      "office_zip_code": "string",
14      "payroll_id": "string"
15    },
16    "attributes": {
17      "eligible_to_payroll": true or false
18    }
19  }
20]'

Request Parameters

Headers

Response

Example Response
1[
2   {
3     "email": "bulk1@certo.com"
4   },
5   {
6     "email": "bulk2@certo.com"
7   }
8]

HTTP status code: 201 Created

Response Fields

Update Many

This endpoint updates data for multiple eligible employees simultaneously. Initially, the limit is set to 10 per request in this endpoint. The identification of employees is based on the client company's main identifier. For example, if the main identifier for a client is email, the "email" field is required in the request, while "employee_id" and "national_id" are optional.

Our bulk endpoint works as a single unit to ensure data consistency and integrity. This means that if any operation in a batch fails, the entire batch will fail. In case of a failure, you'll receive detailed error information specifying which operation caused it. So, make sure all operations in your batch are correct and valid before submitting them.

Please note: Only data that is sent in the request will be updated. Data that is not sent will remain unchanged.

POST {{environment-url}}/eligibility/v1/employees/bulk-update

Request Example
1curl --location --request POST \
2'{{environment-url}}/eligibility/v1/employees/bulk-update' \
3--header 'Content-Type: application/json' \
4--header 'Authorization: Bearer {{Wellhub API Key}}' \
5--data-raw '[
6  {
7    "email": "string",
8    "national_id": "string",
9    "full_name": "string",
10    "employee_id": "string",
11    "additional_fields": {
12      "department": "string",
13      "cost_center": "string",
14      "office_zip_code": "string",
15      "payroll_id": "string"
16    },
17    "attributes": {
18      "eligible_to_payroll": true or false
19    }
20  }
21]'

Request Params

Headers

Response

Empty Response

HTTP status code: 204 No Content

Delete Many

This endpoint deletes multiple eligible employees simultaneously, removing their eligibility for the client’s Wellhub benefit. There is a limit of 10 per request in this endpoint. Each employee to be deleted must be identified by its main Eligibility Identifier. If a valid main identifier is provided, but no employees are identified by it, the data will be ignored.

POST {{environment-url}}/eligibility/v1/employees/bulk-delete

Request Example
1curl --location --request POST '{{environment-url}}/eligibility/v1/employees/bulk-delete' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer {{Wellhub API Key}}' \
4--data-raw '[
5        {
6            "email": "employee01@example.com"
7        },
8        {
9            "email": "employee02@example.com"
10        }
11]'

Request Parameters

The request payload is an array that may contain a list of JSON objects with the Eligibility Identifier (email, national ID or employee ID).

Headers

Response

Empty Response

HTTP status code: 204 No Content

Get One

This endpoint gets one eligible employee by its main Eligibility Identifier. As the identifier may have special characters, its content must be encoded. This endpoint does not allow a search for a deleted eligible employee, and will return a not found error when a request like this happens as in the following example:

Attention: the Get One endpoint, different from the others, has a different path version (v2)

GET {{environment-url}}/eligibility/v2/employees/{eligibilityIdentifier}

Request Example
1curl --location --request GET {{environment-url}}/eligibility/v2/employees/john.doe@gympass.com \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer {{Wellhub API Key}}'

Path Variable

The request's URL must contain the employee's main identifier value.

Headers

Response

Example Response
1{
2  "full_name": "Carol Fisher",
3  "email": "carol.fisher@acme.com",
4  "national_id": "03963105089",
5  "employee_id": "abc123",
6  "updated_at": "2023-06-15T10:03:18.427465-03:00",
7  "deleted_at": null
8}

HTTP status code: 200 OK

Response Fields

Get Many

This endpoint lists employees on pages of 50 records per page. To list all employees (when there are more than 50), you'll need to perform subsequent calls and provide the desired page number. This endpoint is also designed to allow you to list all employees, even the logically deleted ones (via DELETE calls). By default, it returns all employees including deleted employees.

GET {{environment-url}}/eligibility/v1/employees

Request Example
1curl --location --request GET '{{environment-url}}/eligibility/v1/employees?page=1&deleted=false&searchTerm=@acme.com' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer {{Wellhub API Key}}'

Request Params

Headers

Response

Example Response
1{
2  "page_info": {
3    "current_page": 2,
4    "total_pages": 2,
5    "total_elements": 52,
6    "offset_start": 51,
7    "offset_end": 52,
8    "page_size": 50
9  },
10  "items": [
11    {
12      "full_name": "Carol Fisher",
13      "email": "carol.fisher@acme.com",
14      "national_id": "03963105089",
15      "employee_id": "abc123",
16      "updated_at": "2023-06-15T10:03:18.427465-03:00",
17      "deleted_at": null
18    },
19    {
20      "full_name": "John Doe",
21      "email": "john.doe@acme.com",
22      "national_id": "20366667017",
23      "employee_id": "abc321",
24      "updated_at": "2023-06-15T10:03:18.427465-03:00",
25      "deleted_at": null
26    }
27  ]
28}

HTTP status code: 200 OK

Response Fields