---
title: "Search and list employees"
method: GET
path: "/v1/employees"
tags: ["List Employees"]
---

# Search and list employees

`GET /v1/employees`

Retrieve a paginated list of employees based on various filter criteria.

Employees are automatically filtered by the company associated with your authentication token.

This endpoint allows you to:
- Filter employees by status
- Sort results by various fields
- Paginate through large result sets

**Filter Precedence:**
When both `employeeId` and `employeeCode` are provided, `employeeId` takes precedence.
It is recommended to use only one filter at a time for clarity.

## Query parameters

- `page` integer
- `pageSize` integer
- `status` 'ONBOARDING' | 'ACTIVE' | 'OFFBOARDING' | 'ENDED' | 'DELETED' | 'ALL' — Employment status filter
- `employeeId` string, uuid
- `employeeCode` string
- `sortBy` 'startOn' — Field to sort by
- `sortOrder` 'ASC' | 'DESC' — Sort direction

## Response `200`

Successfully retrieved employee list

- V1EmployeesGetResponse
  - `data` EmployeeData[], required — List of employees matching the search criteria
    - `id` string, uuid, required — Unique identifier for the employee
    - `employeeCode` string, nullable — Human-readable employee code (optional)
    - `employeeId` string, nullable — Deprecated: Use employeeCode instead. Human-readable employee code (optional)
    - `firstName` string, required — Employee's first name
    - `middleName` string, nullable — Employee's middle name
    - `lastName` string, required — Employee's last name
    - `fullName` string, required — Employee's full legal name
    - `displayName` string, required — Display name for the employee
    - `workEmail` string, email, nullable — Employee's work email address
    - `designation` string, required — Job title/position
    - `department` string, nullable — Department name
    - `status` 'ONBOARDING' | 'ACTIVE' | 'OFFBOARDING' | 'ENDED' | 'DELETED' | 'UNKNOWN', required — Current employment status
    - `type` 'EMPLOYEE' | 'CONTRACTOR' | 'FREELANCER' | 'HR_MEMBER' | 'UNKNOWN', required — Type of employment
    - `startDate` string, date, required — Employment start date (ISO 8601 format YYYY-MM-DD)
    - `endDate` string, date, nullable — Employment end date (ISO 8601 format YYYY-MM-DD)
    - `country` string, required — ISO 3166-1 alpha-3 country code for work location
    - `customerId` string, uuid, required — ID of the company this employee belongs to
    - `customerName` string, required — Name of the company
    - `entity` string, nullable — Legal entity name for the employee's employment
  - `pagination` Pagination, required — Pagination information for list responses
    - `page` integer, required — Current page number (1-based)
    - `pageSize` integer, required — Number of items per page
    - `totalCount` integer, required — Total number of items across all pages
    - `totalPages` integer, required — Total number of pages

## Other responses

- `400` — Invalid request parameters
- `401` — Authentication required
- `403` — Forbidden - insufficient permissions
- `422` — Unprocessable entity - validation error
- `500` — Internal server error
- `503` — Service unavailable - upstream dependency error

---

[API](https://skmtc.net/usemultiplier/apis/multiplier-public-rest-api.md) · [All operations](https://skmtc.net/usemultiplier/apis/multiplier-public-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/usemultiplier/multiplier-public-rest-api/revisions/59cd6443fdbf/schema)