Skip to main content

Employee Organization Lookup APIs

Summary​

Two direct read-only endpoints provide tenant-scoped departments and designations for Employee workflows.

Audience​

  • Frontend and integration developers
  • QA engineers

Reference Content​

The following inventory and endpoint sections define the direct organization lookup contracts.

API inventory​

MethodRoutePurposeAuthenticationTenantRequestResponseMaturitySource path
GET/employee/departmentsList departmentsRequires confirmationRequiredQueryApiResponse<DepartmentResponse[]>Transitionalmicroservices/src/employee-service/Api/EmployeeDirectEndpoints.cs
GET/employee/designationsList designationsRequires confirmationRequiredQueryApiResponse<DesignationResponse[]>Transitionalmicroservices/src/employee-service/Api/EmployeeDirectEndpoints.cs

List departments​

  • Operation / purpose: GetEmployeeDepartmentsDirect; supplies department choices ordered by name.
  • Method / route: GET /employee/departments.
  • Authentication / authorization: endpoint enforcement and permission are Requires confirmation. Tenant: required.
  • Parameters: optional includeInactive boolean; no route parameters or body.
  • Validation / behavior: omitted means false; inactive rows are excluded unless true.
  • Response: array items contain id, tenantId, name, code, nullable parentDepartmentId, headEmployeeId, and location, plus isActive.
  • Statuses: 200; 400 missing tenant; 401/403 Requires confirmation. Side effects: none.
  • Compatibility: /api/departments uses a different plain DTO and includes all rows.
GET /employee/departments?includeInactive=false
Authorization: Bearer <approved-token>
{"success":true,"message":"Success","data":[{"id":"22222222-2222-4222-8222-222222222222","tenantId":1001,"name":"Example Department","code":"EXAMPLE","parentDepartmentId":null,"headEmployeeId":null,"location":null,"isActive":true}],"correlationId":"safe-correlation-id","errors":null}

Example public-safe error shape (context-supply guidance redacted):

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

List designations​

  • Operation / purpose: GetEmployeeDesignationsDirect; supplies designation choices ordered by level then name.
  • Method / route: GET /employee/designations.
  • Authentication / authorization: endpoint enforcement and permission are Requires confirmation. Tenant: required.
  • Parameters: optional includeInactive boolean and departmentId GUID; no route parameters or body.
  • Validation / behavior: omitted includeInactive means false; optional department filters department-specific rows.
  • Response: array items contain id, tenantId, name, code, nullable departmentId and grade, level, and isActive.
  • Statuses: 200; 400 missing tenant; binding and 401/403 bodies Requires confirmation. Side effects: none.
  • Compatibility: /api/designations returns a different plain DTO with display/count fields.
GET /employee/designations?includeInactive=false&departmentId=22222222-2222-4222-8222-222222222222
Authorization: Bearer <approved-token>
{"success":true,"message":"Success","data":[{"id":"33333333-3333-4333-8333-333333333333","tenantId":1001,"name":"Example Designation","code":"EXAMPLE","departmentId":"22222222-2222-4222-8222-222222222222","grade":null,"level":1,"isActive":true}],"correlationId":"safe-correlation-id","errors":null}

Example public-safe error shape (context-supply guidance 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/Queries/EmployeeApplicationQueries.cs
  • microservices/src/employee-service/Application/Organization/Organization.cs

See Also​

Keywords​

  • Department lookup
  • Designation lookup
  • Organization assignment

Revision Information​

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