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)
```json
{
  "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
```json
{
  "designation": "ASM",
  "status": "active",
  "skip": 0,
  "limit": 50,
  "projection_list": ["user_id", "first_name", "email", "phone"]
}
```

### Update Roles
```json
{
  "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

```bash
# 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`