Employee Management APIs

Summary

Eight transitional direct endpoints read or change an employee aggregate through application queries and commands. All return the direct ApiResponse<T> convention. Their source tag and gateway shadow routing do not establish production Primary status.

Audience

• Frontend and integration developers
• Backend developers and QA engineers
• Support engineers interpreting safe outcomes

Reference Content

The inventory and endpoint sections below define the confirmed direct management contracts.

API inventory

Method	Route	Purpose	Authentication	Tenant	Request	Response	Maturity	Source path
GET	/employee/employees/{id}	Get employee	Requires confirmation	Required	GUID ID	ApiResponse<EmployeeResponse>	Transitional	microservices/src/employee-service/Api/EmployeeDirectEndpoints.cs
POST	/employee/employees	Create employee	Requires confirmation	Required	EmployeeCreateHttpRequest	ApiResponse<EmployeeResponse>	Transitional	microservices/src/employee-service/Api/EmployeeDirectEndpoints.cs
PUT	/employee/employees/{id}	Update employee profile	Requires confirmation	Required	EmployeeUpdateHttpRequest	ApiResponse<EmployeeResponse>	Transitional	microservices/src/employee-service/Api/EmployeeDirectEndpoints.cs
PATCH	/employee/employees/{id}/status	Change status	Requires confirmation	Required	ChangeEmployeeStatusHttpRequest	ApiResponse<EmployeeResponse>	Transitional	microservices/src/employee-service/Api/EmployeeDirectEndpoints.cs
PATCH	/employee/employees/{id}/department	Change department	Requires confirmation	Required	ChangeEmployeeDepartmentHttpRequest	ApiResponse<EmployeeResponse>	Transitional	microservices/src/employee-service/Api/EmployeeDirectEndpoints.cs
PATCH	/employee/employees/{id}/manager	Change manager	Requires confirmation	Required	ChangeEmployeeManagerHttpRequest	ApiResponse<EmployeeResponse>	Transitional	microservices/src/employee-service/Api/EmployeeDirectEndpoints.cs
POST	/employee/employees/{id}/notes	Add note	Requires confirmation	Required	EmployeeNoteHttpRequest	ApiResponse<bool>	Transitional	microservices/src/employee-service/Api/EmployeeDirectEndpoints.cs
POST	/employee/employees/{id}/documents	Add document reference	Requires confirmation	Required	EmployeeDocumentReferenceHttpRequest	ApiResponse<bool>	Transitional	microservices/src/employee-service/Api/EmployeeDirectEndpoints.cs

Shared contract

All route IDs are GUIDs. The host supports Bearer authentication, but endpoint enforcement and permissions are Requires confirmation. Tenant context is required. These commands confirm 400 validation/context and 404 not-found responses; the shared mapper also supports 409 when a handler returns conflict, although no reviewed Employee command currently does so. 401/403 are Requires confirmation.

EmployeeResponse contains id, tenantId, employeeCode, firstName, nullable lastName, displayName, nullable email, phone, departmentId, designationId, reportingManagerId, gender, employment, status, and isActive. employment contains nullable employmentType, workLocation, joiningDate, confirmationDate, and dateOfBirth.

Get employee

• Operation / purpose: GetEmployeeDirect; retrieve one tenant-scoped employee.
• Method / route: GET /employee/employees/{id}. Route: id GUID. Query/body: none.
• Validation / response: employee must exist; returns EmployeeResponse.
• Statuses: 200, 404, 400 missing tenant. Side effects: none.
• Compatibility: /api/employees/{id} returns a plain compatibility DTO.

GET /employee/employees/11111111-1111-4111-8111-111111111111
Authorization: Bearer <approved-token>

{"success":true,"message":"Success","data":{"id":"11111111-1111-4111-8111-111111111111","tenantId":1001,"employeeCode":"EMP-EXAMPLE-001","firstName":"Alex","lastName":"Example","displayName":"Alex Example","email":"alex@example.com","phone":null,"departmentId":null,"designationId":null,"reportingManagerId":null,"status":"Active","gender":null,"employment":{"employmentType":"Full-time","workLocation":null,"joiningDate":"2026-07-15","confirmationDate":null,"dateOfBirth":null},"isActive":true},"correlationId":"safe-correlation-id","errors":null}

{"success":false,"message":"Employee not found.","data":null,"correlationId":"safe-correlation-id","errors":null}

Create employee

• Operation / purpose: CreateEmployeeDirect; create a tenant employee.
• Method / route: POST /employee/employees. Route/query: none.
• Body: required employeeCode, firstName, email; optional lastName, displayName, phone, departmentId, designationId, reportingManagerId, gender, employment.
• Validation / behavior: required code/name/email; basic email format; code and email unique per tenant; referenced department, designation, and manager must be active; a department-specific designation must match the department.
• Response/status: 201 with EmployeeResponse, message Created, and Location header. Confirmed handled error: 400 validation/context, including duplicates. Side effects: creates the aggregate and related audit/timeline/outbox records through the unit of work; payload details are excluded.
• Compatibility: compatibility create returns 200 and a different DTO.

POST /employee/employees
Authorization: Bearer <approved-token>
Content-Type: application/json

{"employeeCode":"EMP-EXAMPLE-001","firstName":"Alex","lastName":"Example","displayName":"Alex Example","email":"alex@example.com","phone":null,"departmentId":null,"designationId":null,"reportingManagerId":null,"gender":null,"employment":{"employmentType":"Full-time","workLocation":null,"joiningDate":"2026-07-15","confirmationDate":null,"dateOfBirth":null}}

{"success":true,"message":"Created","data":{"id":"11111111-1111-4111-8111-111111111111","tenantId":1001,"employeeCode":"EMP-EXAMPLE-001","firstName":"Alex","lastName":"Example","displayName":"Alex Example","email":"alex@example.com","phone":null,"departmentId":null,"designationId":null,"reportingManagerId":null,"status":"Active","gender":null,"employment":{"employmentType":"Full-time","workLocation":null,"joiningDate":"2026-07-15","confirmationDate":null,"dateOfBirth":null},"isActive":true},"correlationId":"safe-correlation-id","errors":null}

{"success":false,"message":"Employee code already exists for this tenant.","data":null,"correlationId":"safe-correlation-id","errors":{"validation":["Employee code already exists for this tenant."]}}

Update employee

• Operation / purpose: UpdateEmployeeDirect; replace confirmed profile/employment fields without changing employee code, department, manager, or status.
• Method / route: PUT /employee/employees/{id}; id GUID; no query.
• Body: required firstName, email; optional lastName, displayName, phone, designationId, gender, employment.
• Validation: employee exists; first name/email required; basic email format; email unique; designation active.
• Response/status: 200 EmployeeResponse; 400, 404, or 409. Side effects: updates aggregate and confirmed audit/timeline/outbox records; payloads excluded.
• Compatibility: use dedicated direct routes for department, manager, and status changes.

PUT /employee/employees/11111111-1111-4111-8111-111111111111
Authorization: Bearer <approved-token>
Content-Type: application/json

{"firstName":"Alex","lastName":"Example","displayName":"Alex Example","email":"alex.updated@example.com","phone":null,"designationId":null,"gender":null,"employment":{"employmentType":"Full-time","workLocation":null,"joiningDate":"2026-07-15","confirmationDate":null,"dateOfBirth":null}}

{"success":true,"message":"Success","data":{"id":"11111111-1111-4111-8111-111111111111","tenantId":1001,"employeeCode":"EMP-EXAMPLE-001","firstName":"Alex","lastName":"Example","displayName":"Alex Example","email":"alex.updated@example.com","phone":null,"departmentId":null,"designationId":null,"reportingManagerId":null,"status":"Active","gender":null,"employment":{"employmentType":"Full-time","workLocation":null,"joiningDate":"2026-07-15","confirmationDate":null,"dateOfBirth":null},"isActive":true},"correlationId":"safe-correlation-id","errors":null}

{"success":false,"message":"Employee not found.","data":null,"correlationId":"safe-correlation-id","errors":null}

Change employee status

• Operation / purpose: ChangeEmployeeStatusDirect; change the employee lifecycle status.
• Method / route/body: PATCH /employee/employees/{id}/status; GUID id; body {"status":"Active"}.
• Validation: employee exists; status is one of Active, OnLeave, Suspended, or Terminated.
• Response/status: 200 EmployeeResponse; 400/404. Side effects: changes active state consistently with status and records history/audit/outbox evidence; payloads excluded.
• Compatibility: compatibility exposes only a boolean active route that maps false to Terminated.

PATCH /employee/employees/11111111-1111-4111-8111-111111111111/status
Authorization: Bearer <approved-token>
Content-Type: application/json

{"status":"OnLeave"}

{"success":true,"message":"Success","data":{"id":"11111111-1111-4111-8111-111111111111","tenantId":1001,"employeeCode":"EMP-EXAMPLE-001","firstName":"Alex","lastName":"Example","displayName":"Alex Example","email":"alex@example.com","phone":null,"departmentId":null,"designationId":null,"reportingManagerId":null,"status":"OnLeave","gender":null,"employment":{"employmentType":"Full-time","workLocation":null,"joiningDate":"2026-07-15","confirmationDate":null,"dateOfBirth":null},"isActive":true},"correlationId":"safe-correlation-id","errors":null}

{"success":false,"message":"Employee status is invalid.","data":null,"correlationId":"safe-correlation-id","errors":{"validation":["Employee status is invalid."]}}

Change employee department

• Operation / purpose: ChangeEmployeeDepartmentDirect; assign or clear a department.
• Method / route/body: PATCH /employee/employees/{id}/department; GUID id; nullable GUID departmentId.
• Validation: employee exists; non-null department exists and is active.
• Response/status: 200 EmployeeResponse; 400/404. Side effects: changes assignment and records history/audit/outbox evidence; payloads excluded.
• Compatibility: combined into compatibility employee update.

PATCH /employee/employees/11111111-1111-4111-8111-111111111111/department
Authorization: Bearer <approved-token>
Content-Type: application/json

{"departmentId":"22222222-2222-4222-8222-222222222222"}

{"success":true,"message":"Success","data":{"id":"11111111-1111-4111-8111-111111111111","tenantId":1001,"employeeCode":"EMP-EXAMPLE-001","firstName":"Alex","lastName":"Example","displayName":"Alex Example","email":"alex@example.com","phone":null,"departmentId":"22222222-2222-4222-8222-222222222222","designationId":null,"reportingManagerId":null,"status":"Active","gender":null,"employment":{"employmentType":"Full-time","workLocation":null,"joiningDate":"2026-07-15","confirmationDate":null,"dateOfBirth":null},"isActive":true},"correlationId":"safe-correlation-id","errors":null}

{"success":false,"message":"Department must exist and be active.","data":null,"correlationId":"safe-correlation-id","errors":{"validation":["Department must exist and be active."]}}

Change employee manager

• Operation / purpose: ChangeEmployeeManagerDirect; assign or clear a reporting manager.
• Method / route/body: PATCH /employee/employees/{id}/manager; GUID id; nullable GUID reportingManagerId.
• Validation: employee exists; employee cannot manage self; non-null manager exists and is active.
• Response/status: 200 EmployeeResponse; 400/404. Side effects: changes reporting assignment and records history/audit/outbox evidence; payloads excluded.
• Compatibility: combined into compatibility employee update.

PATCH /employee/employees/11111111-1111-4111-8111-111111111111/manager
Authorization: Bearer <approved-token>
Content-Type: application/json

{"reportingManagerId":"44444444-4444-4444-8444-444444444444"}

{"success":true,"message":"Success","data":{"id":"11111111-1111-4111-8111-111111111111","tenantId":1001,"employeeCode":"EMP-EXAMPLE-001","firstName":"Alex","lastName":"Example","displayName":"Alex Example","email":"alex@example.com","phone":null,"departmentId":null,"designationId":null,"reportingManagerId":"44444444-4444-4444-8444-444444444444","status":"Active","gender":null,"employment":{"employmentType":"Full-time","workLocation":null,"joiningDate":"2026-07-15","confirmationDate":null,"dateOfBirth":null},"isActive":true},"correlationId":"safe-correlation-id","errors":null}

{"success":false,"message":"An employee cannot report to themselves.","data":null,"correlationId":"safe-correlation-id","errors":{"validation":["An employee cannot report to themselves."]}}

Add employee note

• Operation / purpose: AddEmployeeNoteDirect; append a non-empty note to an existing employee.
• Method / route/body: POST /employee/employees/{id}/notes; GUID id; body text string.
• Validation: employee exists and text is required.
• Response/status: 200 ApiResponse<bool> with message Note added; 400/404. Side effects: stores the note and records audit/timeline evidence.
• Compatibility: no extracted compatibility note endpoint.

POST /employee/employees/11111111-1111-4111-8111-111111111111/notes
Authorization: Bearer <approved-token>
Content-Type: application/json

{"text":"Example administrative note."}

{"success":true,"message":"Note added","data":true,"correlationId":"safe-correlation-id","errors":null}

{"success":false,"message":"Note text is required.","data":null,"correlationId":"safe-correlation-id","errors":{"validation":["Note text is required."]}}

Add employee document reference

• Operation / purpose: AddEmployeeDocumentReferenceDirect; attach document metadata, not file content, to an employee.
• Method / route/body: POST /employee/employees/{id}/documents; GUID id; required documentType, fileName, non-negative sizeBytes; optional storageKey, contentType, expiryDate.
• Validation: employee exists; document type and file name required; size cannot be negative.
• Response/status: 200 ApiResponse<bool> with message Document reference added; 400/404. Side effects: stores a reference and records audit/timeline evidence; no file upload is performed by this endpoint.
• Compatibility: legacy Employee Documents controller is a separate monolith surface and is not duplicated here.

POST /employee/employees/11111111-1111-4111-8111-111111111111/documents
Authorization: Bearer <approved-token>
Content-Type: application/json

{"documentType":"Example","fileName":"example.pdf","storageKey":null,"contentType":"application/pdf","sizeBytes":1024,"expiryDate":null}

{"success":true,"message":"Document reference added","data":true,"correlationId":"safe-correlation-id","errors":null}

{"success":false,"message":"Document type is required.","data":null,"correlationId":"safe-correlation-id","errors":{"validation":["Document type is required."]}}

Source References

• microservices/src/employee-service/Api/EmployeeDirectEndpoints.cs
• microservices/src/employee-service/Application/Commands/EmployeeApplicationCommands.cs
• microservices/src/employee-service/Application/Validators/EmployeeCommandValidators.cs
• microservices/src/employee-service/Application/Mappings/EmployeeMappings.cs

Related Articles

• Employee concepts
• Application layer
• Validation

See Also

• Employee search
• Employee timeline
• Response and error model

Keywords

• Employee commands
• Employee profile API
• Organization assignment API

Revision Information

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