Eligibility Management

This section describes the Eligibility Management endpoints available for managing employees.

The Clients API is a REST API, with JSON format for data exchange.

There will be a single endpoint to perform eligible-related operations (which can be: insert, update or delete), where the action to perform must be specified under the “operation” attribute on the HTTP request.

Every server response uses proper HTTP status codes, with proper distinction between successful and unsuccessful requests (both from client-side and server-side errors).

For data exchange, JSON format is utilized for both requests and responses.

For information about BASE_URl and ACCESS_TOKEN values, see Getting Started.

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 endpoint.

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	Company's unique identifier a given employee belongs to.
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	Whether the employee is eligible for payroll.
payroll_id	string	No	Payroll system identifier for the employee.
mobile_number	string	No	Mobile phone number of the employee.
discount_subset_id	string	No	Identifier for the discount subset applicable to the employee.
custom_fields	object	No	Additional custom fields as key-value pairs.

*Depending on how the Eligibility Identifier was determined by the company's contract with Wellhub, the field may turn to be optional.

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
500	Internal Server Error

Example request

[
  {
    "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 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.

Curl example

curl -X GET "{{BASE_URL}}/v1/eligibility/jobs/{{job-id}}/items?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
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": "subset_123",
      "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": "VALIDATED",
  "updated_at": "2026-01-20T10:30:00Z",
  "statistics": {
    "newcomers": 10,
    "updaters": 3,
    "leavers": 2
  }
}

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": [
    {
      "error_type": "VALIDATION_ERROR",
      "field_name": "email"
    }
  ]
}

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",
      "employee_id": "E-2048",
      "email": "john.doe@acme.com",
      "full_name": "John Doe",
      "national_id": "10987654321",
      "mobile_number": "+5511988888888",
      "batch_id": "job_12345",
      "invitation_status": "ACTIVE",
      "updated_at": "2026-01-20T11:00:00Z",
      "deleted_at": null,
      "additional_fields": {
        "department": "Engineering"
      },
      "attributes": {},
      "custom_fields": {
        "location": "Rio de Janeiro"
      }
    }
  ]
}

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.

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

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",
      "employee_id": "E-1029",
      "email": "maria.santos@acme.com",
      "full_name": "Maria Santos",
      "national_id": "12345678901",
      "mobile_number": "+5511999999999",
      "batch_id": "job_12345",
      "invitation_status": "INVITED",
      "updated_at": "2026-01-20T10:30:00Z",
      "deleted_at": null,
      "additional_fields": {
        "department": "People"
      },
      "attributes": {},
      "custom_fields": {
        "location": "Sao Paulo"
      }
    }
  ]
}

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"
    }
  ]
}