docs/api-guides/EMPLOYEE_API_ENDPOINTS.md

# Employee API Endpoints - Complete Reference

## Base Path: `/employees`

---

## Core CRUD Operations

### 1. Create Employee
- **Method:** `POST /employees`
- **Status:** 201 Created
- **Auth:** Required
- **Description:** Create a new employee with comprehensive validation
- **Request Body:** `EmployeeCreate` schema
- **Response:** `EmployeeResponse`
- **Validations:**
  - Employee code uniqueness
  - Email/phone uniqueness among active employees
  - Manager hierarchy rules
  - Age requirements (minimum 18 years)
  - 2FA enforcement for Admin/Finance/HR
  - Location tracking consent requirements

### 2. List Employees ✅ Projection Support
- **Method:** `POST /employees/list`
- **Auth:** Required
- **Description:** List employees with filters, pagination, and field projection
- **Request Body:** `EmployeeListRequest`
  - `designation`: Filter by role
  - `manager_id`: Filter by manager
  - `status`: Filter by status
  - `region`: Filter by region
  - `skip`: Pagination offset (default: 0)
  - `limit`: Page size (default: 100, max: 500)
  - `projection_list`: Optional field projection
- **Response:** List of employees (dict if projection, full model otherwise)

### 3. Get Employee by ID
- **Method:** `GET /employees/{user_id}`
- **Auth:** Required
- **Description:** Retrieve detailed information about a specific employee
- **Response:** `EmployeeResponse`

### 4. Get Employee by Code
- **Method:** `GET /employees/code/{employee_code}`
- **Auth:** Required
- **Description:** Retrieve employee by their employee code (case-insensitive)
- **Response:** `EmployeeResponse`

### 5. Update Employee
- **Method:** `PUT /employees/{user_id}`
- **Auth:** Required
- **Headers:** `x-user-id` (for audit)
- **Description:** Update employee information (partial updates supported)
- **Request Body:** `EmployeeUpdate` schema
- **Response:** `EmployeeResponse`

### 6. Delete Employee (Soft)
- **Method:** `DELETE /employees/{user_id}`
- **Auth:** Required
- **Headers:** `x-user-id` (for audit)
- **Description:** Soft delete (sets status to terminated)
- **Validation:** Cannot delete employees with active direct reports
- **Response:** Success message

---

## Onboarding

### 7. Start Onboarding
- **Method:** `POST /employees/{user_id}/onboarding/start`
- **Auth:** Required
- **Headers:** `x-user-id`
- **Description:** Initialize onboarding workflow for a new employee
- **Response:** `EmployeeResponse`

---

## Roles & Hierarchy

### 8. Update Employee Roles
- **Method:** `PUT /employees/{user_id}/roles`
- **Auth:** Required
- **Headers:** `x-user-id`
- **Description:** Update RBAC roles assigned to an employee
- **Request Body:** `{ "roles": ["role1", "role2"] }`
- **Response:** `EmployeeResponse`

### 9. Update Employee Manager
- **Method:** `PUT /employees/{user_id}/manager`
- **Auth:** Required
- **Headers:** `x-user-id`
- **Description:** Change the reporting manager for an employee
- **Request Body:** `{ "manager_id": "usr_xxx" }`
- **Validation:** Manager hierarchy rules enforced
- **Response:** `EmployeeResponse`

### 10. Get Direct Reports
- **Method:** `GET /employees/{user_id}/reports`
- **Auth:** Required
- **Query Params:**
  - `status`: Filter by status
  - `skip`: Pagination offset
  - `limit`: Page size
- **Description:** Get all direct reports of a specific employee
- **Response:** List of `EmployeeResponse`

### 11. Get Management Hierarchy
- **Method:** `GET /employees/{user_id}/hierarchy`
- **Auth:** Required
- **Description:** Get the full management chain from top to employee
- **Response:** 
  ```json
  {
    "user_id": "usr_xxx",
    "depth": 3,
    "hierarchy": [...]
  }
  ```

---

## Mobile & Location

### 12. Update App Access
- **Method:** `PUT /employees/{user_id}/app-access`
- **Auth:** Required
- **Headers:** `x-user-id`
- **Description:** Update mobile app access and 2FA settings
- **Request Body:**
  ```json
  {
    "has_mobile_app": true,
    "requires_2fa": false
  }
  ```
- **Response:** `EmployeeResponse`

### 13. Update Location Settings
- **Method:** `PUT /employees/{user_id}/location`
- **Auth:** Required
- **Headers:** `x-user-id`
- **Description:** Update comprehensive location tracking settings
- **Request Body:** `LocationSettingsSchema`
- **Response:** `EmployeeResponse`

### 14. Update Location Consent (Legacy)
- **Method:** `PATCH /employees/{user_id}/location-consent`
- **Auth:** Required
- **Headers:** `x-user-id`
- **Description:** Update location tracking consent (simplified endpoint)
- **Query Params:**
  - `location_tracking_consent`: bool
  - `background_tracking_opt_in`: bool
  - `consent_ip`: string (optional)
  - `consent_device`: string (optional)
- **Response:** `EmployeeResponse`

---

## System Access

### 15. Enable System Access
- **Method:** `PUT /employees/{user_id}/system-access/enable`
- **Auth:** Required
- **Headers:** `x-user-id`
- **Description:** Enable system access for an employee
- **Response:** `EmployeeResponse`

### 16. Disable System Access
- **Method:** `PUT /employees/{user_id}/system-access/disable`
- **Auth:** Required
- **Headers:** `x-user-id`
- **Description:** Disable system access for an employee
- **Response:** `EmployeeResponse`

### 17. Get System Access Status
- **Method:** `GET /employees/{user_id}/system-access/status`
- **Auth:** Required
- **Description:** Check if employee has active system access
- **Response:**
  ```json
  {
    "user_id": "usr_xxx",
    "has_system_access": true,
    "status": "active",
    "has_mobile_app": true,
    "requires_2fa": false
  }
  ```

---

## Documents & Compliance

### 18. Add Employee Document
- **Method:** `POST /employees/{user_id}/documents`
- **Auth:** Required
- **Headers:** `x-user-id`
- **Description:** Add a new identity document to employee record
- **Request Body:** `IDDocumentSchema`
- **Response:** `EmployeeResponse`

### 19. Get Employee Documents
- **Method:** `GET /employees/{user_id}/documents`
- **Auth:** Required
- **Description:** Retrieve all documents for an employee
- **Response:**
  ```json
  {
    "user_id": "usr_xxx",
    "documents": [...]
  }
  ```

### 20. Delete Employee Document
- **Method:** `DELETE /employees/{user_id}/documents/{doc_type}`
- **Auth:** Required
- **Headers:** `x-user-id`
- **Description:** Remove a document from employee record
- **Path Params:** `doc_type` (e.g., 'PAN', 'AADHAAR')
- **Response:** `EmployeeResponse`

### 21. Verify Employee Document
- **Method:** `POST /employees/{user_id}/documents/verify`
- **Auth:** Required
- **Headers:** `x-user-id`
- **Description:** Mark a document as verified
- **Query Params:**
  - `doc_type`: Document type to verify
  - `verified`: bool (default: true)
- **Response:** Success message

---

## Security & Devices

### 22. Get Employee Devices
- **Method:** `GET /employees/{user_id}/devices`
- **Auth:** Required
- **Description:** List all devices bound to employee
- **Response:**
  ```json
  {
    "user_id": "usr_xxx",
    "devices": [...],
    "device_count": 2
  }
  ```

### 23. Block Employee Device
- **Method:** `POST /employees/{user_id}/devices/block`
- **Auth:** Required
- **Headers:** `x-user-id`
- **Description:** Block a specific device from accessing the system
- **Query Params:** `device_id`
- **Response:** Success message

### 24. Logout All Sessions
- **Method:** `POST /employees/{user_id}/sessions/logout-all`
- **Auth:** Required
- **Headers:** `x-user-id`
- **Description:** Force logout from all active sessions
- **Response:** Success message
- **Note:** Integrates with auth service to invalidate tokens

---

## Status & Offboarding

### 25. Update Employee Status
- **Method:** `PATCH /employees/{user_id}/status`
- **Auth:** Required
- **Headers:** `x-user-id`
- **Description:** Update only the employee's status
- **Query Params:** `new_status` (EmployeeStatus enum)
- **Response:** `EmployeeResponse`
- **Status Transitions:**
  - onboarding → active
  - active → inactive
  - active → suspended
  - active/inactive/suspended → terminated

### 26. Suspend Employee
- **Method:** `POST /employees/{user_id}/suspend`
- **Auth:** Required
- **Headers:** `x-user-id`
- **Description:** Suspend an employee (disciplinary action)
- **Query Params:** `reason` (optional)
- **Response:** `EmployeeResponse`

### 27. Terminate Employee
- **Method:** `POST /employees/{user_id}/terminate`
- **Auth:** Required
- **Headers:** `x-user-id`
- **Description:** Terminate an employee
- **Query Params:** `reason` (optional)
- **Validation:** Cannot terminate employees with active direct reports
- **Response:** `EmployeeResponse`

### 28. Complete Offboarding
- **Method:** `POST /employees/{user_id}/offboarding/complete`
- **Auth:** Required
- **Headers:** `x-user-id`
- **Description:** Mark offboarding process as complete
- **Validation:** Employee must be terminated first
- **Response:** Success message

---

## Self-Service

### 29. Get My Profile
- **Method:** `GET /employees/me`
- **Auth:** Required
- **Headers:** `x-user-id` (from auth token)
- **Description:** Get the profile of the currently authenticated employee
- **Response:** `EmployeeResponse`

### 30. Get My Team
- **Method:** `GET /employees/me/team`
- **Auth:** Required
- **Headers:** `x-user-id` (from auth token)
- **Query Params:**
  - `status`: Filter by status
  - `skip`: Pagination offset
  - `limit`: Page size
- **Description:** Get all direct reports of the current employee
- **Response:** List of `EmployeeResponse`

---

## Audit

### 31. Get Employee Audit Logs
- **Method:** `GET /employees/{user_id}/audit-logs`
- **Auth:** Required
- **Query Params:**
  - `skip`: Pagination offset
  - `limit`: Page size
- **Description:** Retrieve audit trail for employee changes
- **Response:** List of audit log entries
- **Status:** 🚧 Placeholder - needs implementation

### 32. Export Employee Audit Logs
- **Method:** `GET /employees/{user_id}/audit-logs/export`
- **Auth:** Required
- **Query Params:** `format` (json or csv)
- **Description:** Export audit trail as CSV or JSON
- **Response:** Audit logs in requested format
- **Status:** 🚧 Placeholder - needs implementation

---

## Dashboard & Analytics

### 33. Get Employee Widgets
- **Method:** `GET /employees/info/widgets`
- **Auth:** Required
- **Description:** Get all employee dashboard widgets data in one response
- **Response:**
  ```json
  {
    "total_employees": {...},
    "active_employees": {...},
    "by_designation": {...},
    "recent_hires": {...}
  }
  ```

---

## Summary

**Total Endpoints:** 33

**Breakdown by Category:**
- Core CRUD: 6 endpoints
- Onboarding: 1 endpoint
- Roles & Hierarchy: 4 endpoints
- Mobile & Location: 3 endpoints
- System Access: 3 endpoints
- Documents & Compliance: 4 endpoints
- Security & Devices: 3 endpoints
- Status & Offboarding: 4 endpoints
- Self-Service: 2 endpoints
- Audit: 2 endpoints (placeholders)
- Dashboard: 1 endpoint

**API Standards Compliance:**
- ✅ Projection list support on `/employees/list`
- ✅ POST method for list endpoints
- ✅ Consistent error handling
- ✅ Audit trail via `x-user-id` headers
- ✅ Soft delete pattern
- ✅ Comprehensive validation

**Authentication:**
All endpoints require authentication. The `x-user-id` header is used for audit trails and is typically extracted from the JWT token by middleware.

**Next Steps:**
1. Implement actual audit log collection and retrieval
2. Integrate session management with auth service
3. Add rate limiting for sensitive operations
4. Implement webhook notifications for status changes
5. Add bulk operations support