Hugging Face's logo

Spaces:
cuatrolabs
/
cuatrolabs-scm-ms
Running

App Files Community
cuatrolabs-scm-ms / docs /api-guides /EMPLOYEE_API_ENDPOINTS.md
MukeshKapoor25's picture
MukeshKapoor25
refactor(database): reorganize database scripts and examples into docs directory
f24ee1d
preview code
|
raw
history blame contribute delete
11.6 kB

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: 
    {
  "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:
    {
  "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:
    {
  "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:
    {
  "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:
    {
  "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:
    {
  "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