Retrieve Employees List

Overview

Retrieves a paginated list of employee records. Supports filtering by status and date range. Set isExport to true to generate an Excel export of the results instead of a paginated JSON response.

Command Details

• Command: RetrieveEmployeesListQuery
• Type: Query (read operation)

API Endpoint

POST /api/bpm/cmd

Request Structure

Field	Type	Required	Description
$type	string	Yes	Must be RetrieveEmployeesListQuery
isExport	bool	No	Set to true to export results as Excel (default: false)
pageNumber	int	No	Page number (default: 1)
pageSize	int	No	Items per page (default: 10)
id	int	No	Filter by employee ID
status	array of int	No	Filter by employee status codes
startDate	string	No	Filter employees created on or after this date (ISO 8601)
endDate	string	No	Filter employees created on or before this date (ISO 8601)
filters	array	No	Dynamic predicate filters (see below)

Dynamic Filter Fields

The filters array supports dot-notation property paths on the Employee entity. Use the exact field paths below.

Filter goal	Correct field value	Example
Filter by email	EmployeeContact.Email	{"field": "EmployeeContact.Email", "operator": "equals", "value": "john@example.com"}
Filter by first name	FirstName	{"field": "FirstName", "operator": "contains", "value": "John"}
Filter by staff ID	StaffId	{"field": "StaffId", "operator": "equals", "value": "EMP-001"}
Filter by date range	Use startDate / endDate params	Do not use CreatedAt in filters — use the top-level startDate/endDate fields instead

warning

Do not use ContactDetails.Email as a filter field name — the actual navigation property is EmployeeContact.Email. Using the wrong path will return unfiltered results.

Try It Out

POST/api/bpm/cmdRetrieveEmployeesListQuery

Base URL

Bearer Token

Request Body

{ "cmd": "RetrieveEmployeesListQuery", "data": { "pageNumber": 1, "pageSize": 10, "isExport": false, "startDate": "2026-01-01", "endDate": "2026-03-31" } }

Response Structure

Success:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 101,
        "staffId": "EMP-001234",
        "email": "john.doe@company.com",
        "firstName": "John",
        "lastName": "Doe",
        "referralCode": "REF-EMP001234",
        "branch": "Lagos Main Branch",
        "branchName": "Lagos Main Branch",
        "role": "Relationship Manager",
        "roleName": "Relationship Manager",
        "isAccountOfficer": false,
        "canReferCustomer": true,
        "status": 1,
        "createdAt": "2026-03-09T10:30:00Z"
      }
    ],
    "pageNumber": 1,
    "pageSize": 10,
    "totalCount": 1,
    "totalPages": 1
  },
  "message": "Employees retrieved successfully"
}

Error:

{
  "success": false,
  "data": null,
  "message": "Failed to retrieve employees",
  "errors": [
    "Invalid filter parameters"
  ]
}

Related Operations

• Retrieve Employee by ID — Get a single employee
• Create Employee — Add a new employee
• Upload Employees — Bulk import from Excel