List Employees
Search and list 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.
get/v1/employees
Query parameters
pageinteger
Example:1
Page number (1-indexed)
pageSizeinteger
Example:20
Number of items per page
status'ONBOARDING' | 'ACTIVE' | 'OFFBOARDING' | 'ENDED' | 'DELETED' | 'ALL'
Employment status filter
Filter by employment status
employeeIdstring uuid
Filter by employee ID (UUID, exact match)
employeeCodestring
Filter by human-readable employee code (exact match)
sortBy'startOn'
Field to sort by
Field to sort by. Currently only supports "startOn".
sortOrder'ASC' | 'DESC'
Sort direction
Sort direction
Response
Successfully retrieved employee list
Example response
{
"data": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"employeeCode": "EMP-12345",
"employeeId": "EMP-12345",
"firstName": "John",
"middleName": "Michael",
"lastName": "Doe",
"fullName": "John Michael Doe",
"displayName": "John Doe",
"workEmail": "john.doe@company.com",
"designation": "Senior Software Engineer",
"department": "Engineering",
"status": "ACTIVE",
"type": "EMPLOYEE",
"startDate": "2023-01-15",
"endDate": null,
"country": "USA",
"customerId": "550e8400-e29b-41d4-a716-446655440000",
"customerName": "Tech Corp Inc",
"entity": "Tech Corp Singapore Pte Ltd"
}
],
"pagination": {
"page": 1,
"pageSize": 20,
"totalCount": 100,
"totalPages": 5
}
}