Skip to main content

Employee Search API

Summary​

The direct search endpoint returns a tenant-scoped, paged Employee summary list with confirmed text, assignment, status, skill, location, employment-type, activity, and sorting inputs.

Audience​

  • Frontend and integration developers
  • QA engineers
  • Support engineers diagnosing search behavior

Reference Content​

The following inventory and contract define the direct search endpoint.

API inventory​

MethodRoutePurposeAuthenticationTenantRequestResponseMaturitySource path
GET/employee/employeesSearch employeesRequires confirmationRequiredQuery stringApiResponse<EmployeeSearchResult>Transitionalmicroservices/src/employee-service/Api/EmployeeDirectEndpoints.cs

Search employees​

  • Operation: SearchEmployeesDirect
  • Purpose / business behavior: returns only matching records in the current tenant and projects summary fields.
  • Method and public route: GET /employee/employees
  • Authentication / authorization: Bearer-capable host; endpoint enforcement and permission are Requires confirmation.
  • Tenant context: required. Missing context returns 400.
  • Route parameters / request body: none.
  • Query parameters: optional query, name, code, email, departmentId, designationId, managerId, status, skill, location, employmentType, isActive, page, pageSize, sortBy, sortDir.
  • Validation: defaults are page 1 and page size 25; values are normalized to page at least 1 and page size 1–200. Confirmed sort fields are displayName, employeeCode, status, joiningDate, and updatedAt; unsupported values fall back to display name. Only desc selects descending order; other values produce ascending order. GUID query binding failures are framework-managed and their public body is Requires confirmation.
  • Response: data.items contains id, employeeCode, displayName, nullable email, departmentId, designationId, reportingManagerId, status, employmentType, location, and isActive; the result also contains total, page, pageSize, sortBy, and sortDirection.
  • Statuses: 200 success; 400 missing tenant. Authentication 401/403 and unhandled-error behavior are Requires confirmation.
  • Side effects: none confirmed.
  • Compatibility notes: this is the direct transitional search contract. Compatibility GET /api/employees supports only includeInactive and returns a different DTO/list.

Example request:

GET /employee/employees?name=Alex&isActive=true&page=1&pageSize=25&sortBy=displayName&sortDir=asc
Authorization: Bearer <approved-token>

Example success response:

{
  "success": true,
  "message": "Success",
  "data": {
    "items": [{"id":"11111111-1111-4111-8111-111111111111","employeeCode":"EMP-EXAMPLE-001","displayName":"Alex Example","email":"alex@example.com","departmentId":null,"designationId":null,"reportingManagerId":null,"status":"Active","employmentType":"Full-time","location":null,"isActive":true}],
    "total": 1,
    "page": 1,
    "pageSize": 25,
    "sortBy": "displayName",
    "sortDirection": "asc"
  },
  "correlationId": "safe-correlation-id",
  "errors": null
}

Example public-safe error shape (the server's context-supply guidance is intentionally redacted):

{"success":false,"message":"Tenant context is required.","data":null,"correlationId":"safe-correlation-id","errors":{"tenant":["[approved context guidance omitted]"]}}

Source References​

  • microservices/src/employee-service/Api/EmployeeDirectEndpoints.cs
  • microservices/src/employee-service/Application/Search/EmployeeSearch.cs
  • microservices/src/employee-service/Infrastructure/PostgresEmployeeSearchProvider.cs

See Also​

Keywords​

  • Employee search
  • Pagination
  • Filtering

Revision Information​

  • Status: Draft
  • Last reviewed: 2026-07-15
  • Review cycle: Quarterly