---
title: "List employees by company"
method: GET
path: "/v1/companies/{company-tax-id}/employees"
tags: ["Employees"]
---

# List employees by company

`GET /v1/companies/{company-tax-id}/employees`

## Request

- Base URL: `https://api.clients.wellhub.com`
- URL: `https://api.clients.wellhub.com/v1/companies/{company-tax-id}/employees`
- Auth: HTTP bearer

Returns a paginated list of employees belonging to the specified company, identified by its tax ID. Only companies accessible to the authenticated entity are allowed.

> **ℹ️ Availability.** This endpoint is available to **multi-entity clients** and **channel partners**. Single-entity clients should use `GET /v1/employees` instead.

## Path parameters

- `company-tax-id` string, required

## Query parameters

- `cursor` string

## Response `200`

OK. Returns a paginated list of employees.

- EmployeesResponse
  - `data` Employee[]: List of employees for the current page.
    - `id` string: Internal Wellhub identifier for the employee.
    - `full_name` string: Employee's full name.
    - `email` string: Employee's email address.
    - `employee_id` string: Client-defined employee identifier.
    - `national_id` string: Employee's national identifier (e.g. CPF in Brazil).
    - `invitation_status` string: Current invitation status for the employee on the Wellhub platform.
    - `mobile_number` string: Employee's mobile phone number.
    - `cost_center` string: Cost center associated with the employee.
    - `department` string: Department the employee belongs to.
    - `office_zip_code` string: ZIP code of the employee's office location.
    - `payroll_id` string: Payroll identifier for the employee.
    - `discount_subset_id` string, nullable: Identifier for the discount subset applicable to this employee, if any.
    - `employee_segment` string, nullable: Identifies the employee's segment for NR01, if set.
    - `eligible_to_payroll` boolean: Whether the employee is eligible for payroll deduction.
    - `deleted_at` string, date-time, nullable: Timestamp when the employee record was soft-deleted. `null` if active.
    - `updated_at` string, date-time: Timestamp of the last update to this employee record.
  - `cursor` string, nullable: Cursor for fetching the next page of results. `null` if there are no more results.

## Other responses

- `400`: Bad Request.
- `401`: Unauthorized. Missing or invalid Bearer token.
- `403`: Forbidden. The authenticated entity does not have access to this company.
- `404`: Not Found. No company found with the given tax ID.
- `500`: Internal Server Error.

---

[API](https://skmtc.dev/wellhub/apis/integrations-api.md) - [All operations](https://skmtc.dev/wellhub/apis/integrations-api/llms.txt) - [OpenAPI document](https://skmtc.dev/wellhub/apis/integrations-api/revisions/3e6a46a18a2e?raw)