Eligibility via REST API

Use the Eligibility Management API to keep your employee roster in sync with Wellhub so onboarding and offboarding stay up to date. The API follows REST conventions and uses JSON for all requests and responses, where the latter follow standard HTTP status codes to distinguish success and error scenarios.

For information about BASE_URL and ACCESS_TOKEN values, see Getting Started with the REST API. For an overview of Eligibility Identifiers and Entity Types, see Entity Types.

Endpoints summary

EndpointDescription
POST /v1/eligibility/jobsEndpoint to create a job.
POST /v1/eligibility/jobs/{job-id}/itemsEndpoint to create job items.
GET /v1/eligibility/jobs/{job-id}/itemsEndpoint to list the job items.
POST /v1/eligibility/jobs/{job-id}/submitEndpoint to submit a job.
GET /v1/eligibility/jobs/{job-id}/statusEndpoint to retrieve the job status.
GET /v1/eligibility/jobs/{job-id}/errorsEndpoint to list the job errors.
GET /v1/employeesEndpoint to list eligibles for a single entity.
GET /v1/companies/{company-tax-id}/employeesEndpoint to list eligibles for multi entities and channel partners.
GET /v1/companiesEndpoint 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

BASH
curl -X POST "{{BASE_URL}}/v1/eligibility/jobs" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}"

Parameters

This endpoint does not define parameters.

Headers

NameRequiredDescription
AuthorizationYesAuthentication token used to authorize requests.

Response codes

CodeDescription
201Created
401Unauthorized
403Forbidden
500Internal Server Error

Example response

201 Created

JSON
{
  "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

BASH
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

NameInRequiredDescription
job-idPathYesJob 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:

FieldTypeRequiredDescription
operationstringYesThe action to perform: CREATE, UPDATE, or DELETE
company_tax_idstringYesIdentifies to which company an employee belongs
employee_idstringYes*Employee identifier within company's system
full_namestringNoFull name of the employee
emailstringYes*Email address of the employee.
national_idstringYes*National identification registry of the employee
departmentstringNoDepartment where the employee works
cost_centerstringNoCost center associated with the employee
office_zip_codestringNoZIP code of the employee's office location
eligible_to_payrollbooleanNoEmployee is allowed to use paycheck as a payment method
payroll_idstringNoEmployee identifier in company's payroll software
mobile_numberstringYes*Mobile phone number of the employee.
discount_subset_idstringNoIdentifier for the discount group applicable to the employee.
custom_fieldsobjectNoAdditional 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

NameRequiredDescription
AuthorizationYesAuthentication token used to authorize requests.
Content-TypeYesapplication/json.

Response codes

CodeDescription
204No Content
400Bad Request (validation errors; see response body details)
401Unauthorized
403Forbidden
404Not Found
500Internal Server Error

Example request

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

JSON
{
  "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

BASH
curl -X GET "{{BASE_URL}}/v1/eligibility/jobs/{{job-id}}/items?cursor={{cursor}}" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Content-Type: application/json"

Parameters

NameInRequiredDescription
job-idPathYesJob ID.
cursorQueryNoCursor for pagination.

Headers

NameRequiredDescription
AuthorizationYesAuthentication token used to authorize requests.

Response codes

CodeDescription
200OK
400Bad Request
401Unauthorized
403Forbidden
404Not Found
500Internal Server Error

Example response

200 OK

JSON
{
  "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

BASH
curl -X POST "{{BASE_URL}}/v1/eligibility/jobs/{{job-id}}/submit" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}"

Parameters

NameInRequiredDescription
job-idPathYesJob ID.

Headers

NameRequiredDescription
AuthorizationYesAuthentication token used to authorize requests.

Response codes

CodeDescription
202Accepted
400Bad Request
401Unauthorized
403Forbidden
404Not Found
409Conflict
422Unprocessable Entity
500Internal 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

BASH
curl -X GET "{{BASE_URL}}/v1/eligibility/jobs/{{job-id}}/status" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}"

Parameters

NameInRequiredDescription
job-idPathYesJob ID.

Headers

NameRequiredDescription
AuthorizationYesAuthentication token used to authorize requests.

Response codes

CodeDescription
200OK
400Bad Request
401Unauthorized
403Forbidden
404Not Found
500Internal Server Error

Example response

200 OK

JSON
{
  "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

BASH
curl -X GET "{{BASE_URL}}/v1/eligibility/jobs/{{job-id}}/errors?cursor={{cursor}}" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}"

Parameters

NameInRequiredDescription
job-idPathYesJob ID.
cursorQueryNoCursor for pagination.

Headers

NameRequiredDescription
AuthorizationYesAuthentication token used to authorize requests.

Response codes

CodeDescription
200OK
400Bad Request
401Unauthorized
403Forbidden
500Internal Server Error

Example response

200 OK

JSON
{
  "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

BASH
curl -X GET "{{BASE_URL}}/v1/employees?cursor={{cursor}}" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}"

Parameters

NameInRequiredDescription
cursorQueryNoCursor for pagination.

Headers

NameRequiredDescription
AuthorizationYesAuthentication token used to authorize requests.

Response codes

CodeDescription
200OK
400Bad Request
401Unauthorized
403Forbidden
500Internal Server Error

Example response

200 OK

JSON
{
  "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

BASH
curl -X GET "{{BASE_URL}}/v1/companies/{{company-tax-id}}/employees?cursor={{cursor}}" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}"

Parameters

NameInRequiredDescription
company-tax-idPathYesCompany Tax ID.
cursorQueryNoCursor 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

NameRequiredDescription
AuthorizationYesAuthentication token used to authorize requests.

Response codes

CodeDescription
200OK
400Bad Request
401Unauthorized
403Forbidden
404Not Found
500Internal Server Error

Example response

200 OK

JSON
{
  "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

BASH
curl -X GET "{{BASE_URL}}/v1/companies?cursor={{cursor}}" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}"

Parameters

NameInRequiredDescription
cursorQueryNoCursor for pagination.

Headers

NameRequiredDescription
AuthorizationYesAuthentication token used to authorize requests.

Response codes

CodeDescription
200OK
400Bad Request
401Unauthorized
403Forbidden
500Internal Server Error

Example response

200 OK

JSON
{
  "cursor": "next_cursor_token",
  "data": [
    {
      "company_name": "Cool Company",
      "company_tax_id": "1234567890"
    }
  ]
}