docs/api-guides/EMPLOYEE_API_QUICK_REFERENCE.md

Employee API - Quick Reference

Base URL: /employees

---

Quick Lookup Table

Method	Endpoint	Purpose	Auth Header
CORE
POST	/employees	Create employee	x-user-id
POST	/employees/list	List with filters & projection	-
GET	/employees/{id}	Get by ID	-
GET	/employees/code/{code}	Get by code	-
PUT	/employees/{id}	Update employee	x-user-id
DELETE	/employees/{id}	Soft delete	x-user-id
ONBOARDING
POST	/employees/{id}/onboarding/start	Start onboarding	x-user-id
ROLES & HIERARCHY
PUT	/employees/{id}/roles	Update roles	x-user-id
PUT	/employees/{id}/manager	Change manager	x-user-id
GET	/employees/{id}/reports	Get direct reports	-
GET	/employees/{id}/hierarchy	Get management chain	-
MOBILE & LOCATION
PUT	/employees/{id}/app-access	Update app access	x-user-id
PUT	/employees/{id}/location	Update location settings	x-user-id
PATCH	/employees/{id}/location-consent	Update consent	x-user-id
SYSTEM ACCESS
PUT	/employees/{id}/system-access/enable	Enable access	x-user-id
PUT	/employees/{id}/system-access/disable	Disable access	x-user-id
GET	/employees/{id}/system-access/status	Check access status	-
DOCUMENTS
POST	/employees/{id}/documents	Add document	x-user-id
GET	/employees/{id}/documents	List documents	-
DELETE	/employees/{id}/documents/{type}	Remove document	x-user-id
POST	/employees/{id}/documents/verify	Verify document	x-user-id
SECURITY
GET	/employees/{id}/devices	List devices	-
POST	/employees/{id}/devices/block	Block device	x-user-id
POST	/employees/{id}/sessions/logout-all	Logout all	x-user-id
STATUS
PATCH	/employees/{id}/status	Update status	x-user-id
POST	/employees/{id}/suspend	Suspend	x-user-id
POST	/employees/{id}/terminate	Terminate	x-user-id
POST	/employees/{id}/offboarding/complete	Complete offboarding	x-user-id
SELF-SERVICE
GET	/employees/me	My profile	x-user-id
GET	/employees/me/team	My team	x-user-id
AUDIT
GET	/employees/{id}/audit-logs	Get audit logs	-
GET	/employees/{id}/audit-logs/export	Export logs	-
DASHBOARD
GET	/employees/info/widgets	Dashboard widgets	-

---

Common Request Bodies

Create Employee (Minimal)

{
  "employee_code": "EMP-001",
  "first_name": "John",
  "email": "john@company.com",
  "phone": "+919876543210",
  "designation": "BDE",
  "manager_id": "usr_asm_001",
  "base_city": "Mumbai",
  "base_state": "Maharashtra",
  "doj": "2024-01-15",
  "emergency_contact": {
    "name": "Jane Doe",
    "phone": "+919876543211"
  },
  "created_by": "admin_001"
}

List with Projection

{
  "designation": "ASM",
  "status": "active",
  "skip": 0,
  "limit": 50,
  "projection_list": ["user_id", "first_name", "email", "phone"]
}

Update Roles

{
  "roles": ["field_sales", "order_create"]
}

---

Status Values

• onboarding - New employee, not yet active
• active - Active employee
• inactive - Temporarily inactive (leave, etc.)
• suspended - Suspended (disciplinary)
• terminated - Terminated/offboarded

---

Designation Values

• RSM - Regional Sales Manager
• ASM - Area Sales Manager
• BDE - Business Development Executive
• Head_Trainer - Head Trainer
• Trainer - Trainer
• HR - Human Resources
• Finance - Finance
• Admin - Administrator
• Field_Sales - Field Sales

---

Manager Hierarchy Rules

Employee Role	Allowed Managers
ASM	RSM
BDE	ASM, RSM
Trainer	ASM, RSM, Head_Trainer
Field_Sales	ASM, RSM, BDE

---

Common Response Codes

Code	Meaning
200	Success
201	Created
400	Validation error / Business rule violation
404	Employee not found
500	Server error

---

Quick Tips

1. Projection for Performance: Always use projection_list when you don't need full employee data
2. Audit Trail: Include x-user-id header for all mutations
3. Soft Delete: DELETE endpoint sets status to terminated, doesn't remove data
4. Manager Validation: System enforces hierarchy rules automatically
5. 2FA Required: Admin/Finance/HR roles must have 2FA enabled
6. Location Consent: Must have mobile app access to enable location tracking

---

Testing Endpoints

# Health check (if available)
curl http://localhost:8000/health

# List all active employees
curl -X POST http://localhost:8000/employees/list \
  -H "Content-Type: application/json" \
  -d '{"status": "active", "limit": 10}'

# Get my profile
curl http://localhost:8000/employees/me \
  -H "x-user-id: usr_123"

# Get system access status
curl http://localhost:8000/employees/usr_123/system-access/status

---

Need More Details?

• Full API Reference: EMPLOYEE_API_ENDPOINTS.md
• Implementation Summary: EMPLOYEE_ENDPOINTS_IMPLEMENTATION_SUMMARY.md
• Test Script: test_employee_endpoints.py