{"openapi":"3.0.0","info":{"title":"FlowOS HR Module API","version":"0.1.0","description":"HR Module API for managing employees, leave, attendance, and vendor integrations","contact":{"name":"ScrumDesk s r.o."}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"Employee":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the employee"},"work_number":{"type":"string","description":"Employee work number"},"account_type":{"type":"string","description":"Type of account"},"status":{"type":"string","description":"Employee status"},"first_name":{"type":"string","description":"Employee first name"},"last_name":{"type":"string","description":"Employee last name"},"middle_name":{"type":"string","nullable":true,"description":"Employee middle name"},"title":{"type":"string","nullable":true,"description":"Employee title"},"email":{"type":"string","format":"email","description":"Primary email address"},"email_secondary":{"type":"string","format":"email","nullable":true,"description":"Secondary email address"},"phone_primary":{"type":"string","nullable":true,"description":"Primary phone number"},"phone_secondary":{"type":"string","nullable":true,"description":"Secondary phone number"},"address_street":{"type":"string","nullable":true,"description":"Street address"},"address_city":{"type":"string","nullable":true,"description":"City"},"address_postal_code":{"type":"string","nullable":true,"description":"Postal code"},"address_country":{"type":"string","nullable":true,"description":"Country"},"note":{"type":"string","nullable":true,"description":"Additional notes"},"organization_uuid":{"type":"string","format":"uuid","description":"Organization UUID"},"organization_unit_id":{"type":"string","nullable":true,"description":"Primary organization unit ID"},"manager_id":{"type":"string","nullable":true,"description":"Manager employee ID"},"hire_date":{"type":"string","format":"date","nullable":true,"description":"Hire date"},"employment_type":{"type":"string","nullable":true,"description":"Type of employment"},"is_active":{"type":"boolean","description":"Whether the employee is active"},"flowos_user_id":{"type":"string","nullable":true,"description":"FlowOS user ID"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp"},"organization_units":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Organization unit ID"},"name":{"type":"string","description":"Organization unit name"},"code":{"type":"string","nullable":true,"description":"Organization unit code"},"is_primary":{"type":"boolean","description":"Whether this is the primary unit"},"parent_unit":{"type":"object","nullable":true,"properties":{"id":{"type":"string","description":"Parent unit ID"},"name":{"type":"string","description":"Parent unit name"}}}}}}},"required":["id","work_number","account_type","status","first_name","last_name","email","organization_uuid","is_active","created_at","updated_at","organization_units"]},"LeaveType":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the leave type"},"name":{"type":"string","description":"Name of the leave type"},"description":{"type":"string","nullable":true,"description":"Description of the leave type"},"isPaid":{"type":"boolean","description":"Whether this leave type is paid"},"maxDaysPerYear":{"type":"integer","nullable":true,"description":"Maximum days allowed per year"},"requiresApproval":{"type":"boolean","description":"Whether this leave type requires approval"},"color":{"type":"string","nullable":true,"description":"Color code for UI display"},"isActive":{"type":"boolean","description":"Whether this leave type is active"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","name","isPaid","requiresApproval","isActive"]},"LeaveRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the leave request"},"employeeId":{"type":"string","format":"uuid","description":"Employee ID"},"leaveTypeId":{"type":"string","format":"uuid","description":"Leave type ID"},"startDate":{"type":"string","format":"date","description":"Start date of leave"},"endDate":{"type":"string","format":"date","description":"End date of leave"},"daysRequested":{"type":"number","description":"Number of days requested"},"reason":{"type":"string","nullable":true,"description":"Reason for leave"},"status":{"type":"string","enum":["pending","approved","rejected","cancelled"],"description":"Status of the leave request"},"approvedBy":{"type":"string","format":"uuid","nullable":true,"description":"ID of the approver"},"approvedAt":{"type":"string","format":"date-time","nullable":true,"description":"Approval timestamp"},"rejectionReason":{"type":"string","nullable":true,"description":"Reason for rejection"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","employeeId","leaveTypeId","startDate","endDate","daysRequested","status"]},"AttendanceRecord":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the attendance record"},"employeeId":{"type":"string","format":"uuid","description":"Employee ID"},"date":{"type":"string","format":"date","description":"Attendance date"},"checkInTime":{"type":"string","format":"date-time","nullable":true,"description":"Check-in timestamp"},"checkOutTime":{"type":"string","format":"date-time","nullable":true,"description":"Check-out timestamp"},"hoursWorked":{"type":"number","nullable":true,"description":"Total hours worked"},"status":{"type":"string","enum":["present","absent","late","half_day","holiday"],"description":"Attendance status"},"notes":{"type":"string","nullable":true,"description":"Additional notes"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","employeeId","date","status"]},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"details":{"type":"object","description":"Additional error details"}},"required":["error"]}}},"tags":[{"name":"Employees","description":"Employee management operations"},{"name":"Accounts","description":"Employee account operations"},{"name":"Leave","description":"Leave management and requests"},{"name":"Attendance","description":"Employee attendance tracking"}],"security":[{"bearerAuth":[]}],"paths":{"/accounts":{"get":{"summary":"List accounts","description":"Get a paginated list of employee accounts with filtering, sorting, and search capabilities","tags":["Accounts"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"work_number","schema":{"type":"string"},"description":"Filter by work number"},{"in":"query","name":"account_type","schema":{"type":"string"},"description":"Filter by account type"},{"in":"query","name":"status","schema":{"type":"string"},"description":"Filter by account status"},{"in":"query","name":"organization_uuid","schema":{"type":"string","format":"uuid"},"description":"Filter by organization UUID"},{"in":"query","name":"search","schema":{"type":"string"},"description":"Search term for name, email, or work number"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Number of items per page"},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"default":0},"description":"Number of items to skip"},{"in":"query","name":"sort_by","schema":{"type":"string","enum":["created_at","first_name","last_name","email","work_number","status","account_type","hire_date"],"default":"created_at"},"description":"Field to sort by"},{"in":"query","name":"sort_order","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort order"}],"responses":{"200":{"description":"List of accounts","content":{"application/json":{"schema":{"type":"object","properties":{"accounts":{"type":"array","items":{"$ref":"#/components/schemas/Employee"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create account","description":"Create a new employee account","tags":["Accounts"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"work_number":{"type":"string","description":"Employee work number (auto-generated if not provided)"},"account_type":{"type":"string","description":"Type of account"},"status":{"type":"string","description":"Account status"},"first_name":{"type":"string","description":"Employee first name"},"last_name":{"type":"string","description":"Employee last name"},"middle_name":{"type":"string","description":"Employee middle name"},"title":{"type":"string","description":"Employee title"},"email":{"type":"string","format":"email","description":"Primary email address"},"email_secondary":{"type":"string","format":"email","description":"Secondary email address"},"phone_primary":{"type":"string","description":"Primary phone number"},"phone_secondary":{"type":"string","description":"Secondary phone number"},"address_street":{"type":"string","description":"Street address"},"address_city":{"type":"string","description":"City"},"address_postal_code":{"type":"string","description":"Postal code"},"address_country":{"type":"string","description":"Country"},"note":{"type":"string","description":"Additional notes"},"organization_uuid":{"type":"string","format":"uuid","description":"Organization UUID"},"organization_unit_id":{"type":"string","description":"Primary organization unit ID"},"manager_id":{"type":"string","description":"Manager employee ID"},"hire_date":{"type":"string","format":"date","description":"Hire date"},"employment_type":{"type":"string","description":"Type of employment"},"emergency_contacts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Emergency contact name"},"phone":{"type":"string","description":"Emergency contact phone"},"relationship":{"type":"string","description":"Relationship to employee"}}}}},"required":["first_name","last_name","email","organization_uuid"]}}}},"responses":{"201":{"description":"Account created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Employee"}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Account with this email or work number already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/accounts/{id}":{"get":{"summary":"Get account by ID","description":"Get detailed information about a specific employee account","tags":["Accounts"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Account ID (can be UUID or work number)"}],"responses":{"200":{"description":"Account details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Employee"}}}},"400":{"description":"Invalid account ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Update account","description":"Update an existing employee account","tags":["Accounts"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Account ID (can be UUID or work number)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"account_type":{"type":"string","description":"Type of account"},"status":{"type":"string","description":"Account status"},"first_name":{"type":"string","description":"Employee first name"},"last_name":{"type":"string","description":"Employee last name"},"middle_name":{"type":"string","nullable":true,"description":"Employee middle name"},"title":{"type":"string","nullable":true,"description":"Employee title"},"email":{"type":"string","format":"email","description":"Primary email address"},"email_secondary":{"type":"string","format":"email","nullable":true,"description":"Secondary email address"},"phone_primary":{"type":"string","nullable":true,"description":"Primary phone number"},"phone_secondary":{"type":"string","nullable":true,"description":"Secondary phone number"},"address_street":{"type":"string","nullable":true,"description":"Street address"},"address_city":{"type":"string","nullable":true,"description":"City"},"address_postal_code":{"type":"string","nullable":true,"description":"Postal code"},"address_country":{"type":"string","nullable":true,"description":"Country"},"note":{"type":"string","nullable":true,"description":"Additional notes"},"organization_unit_id":{"type":"string","nullable":true,"description":"Primary organization unit ID"},"manager_id":{"type":"string","nullable":true,"description":"Manager employee ID"},"hire_date":{"type":"string","format":"date","nullable":true,"description":"Hire date"},"employment_type":{"type":"string","nullable":true,"description":"Type of employment"},"emergency_contacts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Emergency contact name"},"phone":{"type":"string","description":"Emergency contact phone"},"relationship":{"type":"string","nullable":true,"description":"Relationship to employee"}}}}}}}}},"responses":{"200":{"description":"Account updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Employee"}}}},"400":{"description":"Invalid account ID or request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete account","description":"Soft-delete an employee account","tags":["Accounts"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Account ID (can be UUID or work number)"}],"responses":{"200":{"description":"Account deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Account deleted successfully"}}}}}},"400":{"description":"Invalid account ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/employees/{employeeId}/attendance":{"get":{"summary":"Get employee attendance","description":"Get attendance records for a specific employee within a date range","tags":["Attendance"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"employeeId","required":true,"schema":{"type":"string","format":"uuid"},"description":"Employee UUID"},{"in":"query","name":"start_date","schema":{"type":"string","format":"date"},"description":"Start date for attendance records (YYYY-MM-DD)"},{"in":"query","name":"end_date","schema":{"type":"string","format":"date"},"description":"End date for attendance records (YYYY-MM-DD)"}],"responses":{"200":{"description":"List of attendance records","content":{"application/json":{"schema":{"type":"object","properties":{"attendanceRecords":{"type":"array","items":{"$ref":"#/components/schemas/AttendanceRecord"}}}}}}},"400":{"description":"Invalid employee ID or date format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Record attendance","description":"Record check-in/check-out or manual attendance entry for an employee","tags":["Attendance"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"employeeId","required":true,"schema":{"type":"string","format":"uuid"},"description":"Employee UUID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Attendance date (YYYY-MM-DD)"},"checkInTime":{"type":"string","format":"date-time","description":"Check-in timestamp"},"checkOutTime":{"type":"string","format":"date-time","description":"Check-out timestamp"},"status":{"type":"string","enum":["present","absent","late","half_day","holiday"],"description":"Attendance status"},"locationLat":{"type":"number","format":"float","description":"GPS latitude for check-in/out location"},"locationLng":{"type":"number","format":"float","description":"GPS longitude for check-in/out location"},"notes":{"type":"string","description":"Additional notes"}},"required":["date"]}}}},"responses":{"201":{"description":"Attendance recorded successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttendanceRecord"}}}},"400":{"description":"Invalid request data or employee ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/employees/batch":{"get":{"summary":"Get employees by work numbers (batch)","description":"Retrieve multiple employees by their work numbers","tags":["Employees"],"parameters":[{"in":"query","name":"codes","schema":{"type":"string"},"description":"Comma-separated list of work numbers","example":"EMP001,EMP002,EMP003"}],"responses":{"200":{"description":"Employees retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Employee"}},"notFound":{"type":"array","items":{"type":"string"},"description":"Work numbers that were not found"},"timestamp":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Too many codes requested","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/employees/by-uuids":{"get":{"summary":"Get employees by UUIDs","description":"Retrieve multiple employees by their UUIDs","tags":["Employees"],"parameters":[{"in":"query","name":"uuids","schema":{"type":"string"},"description":"Comma-separated list of employee UUIDs","example":"5fac8bca-11a4-43d3-bc1e-86445968c612,6bac8bca-11a4-43d3-bc1e-86445968c613"}],"responses":{"200":{"description":"Employees retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"work_number":{"type":"string"},"email":{"type":"string","format":"email"},"account_type":{"type":"string"},"status":{"type":"string"}}}}}}}}},"400":{"description":"Invalid UUID format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/employees/validate":{"post":{"summary":"Validate employee work numbers","description":"Check which employee work numbers exist in the system","tags":["Employees"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"codes":{"type":"array","items":{"type":"string"},"description":"Array of work numbers to validate","example":["EMP001","EMP002","INVALID"]}},"required":["codes"]}}}},"responses":{"200":{"description":"Validation results","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"array","items":{"type":"string"},"description":"Work numbers that exist"},"invalid":{"type":"array","items":{"type":"string"},"description":"Work numbers that do not exist"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/employees":{"get":{"summary":"List employees","description":"Get a list of employees with optional filtering and pagination","tags":["Employees"],"parameters":[{"in":"query","name":"organization_uuid","schema":{"type":"string","format":"uuid"},"description":"Filter by organization UUID"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Maximum number of employees to return","default":100},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0},"description":"Number of employees to skip","default":0},{"in":"query","name":"search","schema":{"type":"string"},"description":"Search term for employee names or work numbers"}],"responses":{"200":{"description":"Employees retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Employee"}},"total":{"type":"integer","description":"Total number of employees matching the criteria"},"timestamp":{"type":"string","format":"date-time"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a new employee","description":"Create a new employee record","tags":["Employees"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"work_number":{"type":"string","description":"Employee work number","example":"EMP001"},"account_type":{"type":"string","description":"Type of account","example":"employee"},"status":{"type":"string","description":"Employee status","example":"active"},"first_name":{"type":"string","description":"Employee first name","example":"John"},"last_name":{"type":"string","description":"Employee last name","example":"Doe"},"middle_name":{"type":"string","description":"Employee middle name","example":"Michael"},"title":{"type":"string","description":"Employee title","example":"Software Engineer"},"email":{"type":"string","format":"email","description":"Primary email address","example":"john.doe@company.com"},"email_secondary":{"type":"string","format":"email","description":"Secondary email address"},"phone_primary":{"type":"string","description":"Primary phone number","example":"+1-555-123-4567"},"phone_secondary":{"type":"string","description":"Secondary phone number"},"address_street":{"type":"string","description":"Street address"},"address_city":{"type":"string","description":"City"},"address_postal_code":{"type":"string","description":"Postal code"},"address_country":{"type":"string","description":"Country"},"note":{"type":"string","description":"Additional notes"},"organization_uuid":{"type":"string","format":"uuid","description":"Organization UUID"},"organization_unit_id":{"type":"string","description":"Primary organization unit ID"},"manager_id":{"type":"string","description":"Manager employee ID"},"hire_date":{"type":"string","format":"date","description":"Hire date"},"employment_type":{"type":"string","description":"Type of employment"},"is_active":{"type":"boolean","description":"Whether the employee is active","default":true},"flowos_user_id":{"type":"string","description":"FlowOS user ID"}},"required":["work_number","account_type","status","first_name","last_name","email","organization_uuid"]}}}},"responses":{"201":{"description":"Employee created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"employee":{"$ref":"#/components/schemas/Employee"}}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/employees/{id}":{"get":{"summary":"Get employee by ID","description":"Retrieve a single employee by their UUID","tags":["Employees"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Employee UUID","example":"5fac8bca-11a4-43d3-bc1e-86445968c612"}],"responses":{"200":{"description":"Employee retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"employee":{"$ref":"#/components/schemas/Employee"}}}}}},"400":{"description":"Invalid employee ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Employee not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Update an employee","description":"Update an existing employee record","tags":["Employees"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Employee UUID","example":"5fac8bca-11a4-43d3-bc1e-86445968c612"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"work_number":{"type":"string","description":"Employee work number"},"account_type":{"type":"string","description":"Type of account"},"status":{"type":"string","description":"Employee status"},"first_name":{"type":"string","description":"Employee first name"},"last_name":{"type":"string","description":"Employee last name"},"middle_name":{"type":"string","description":"Employee middle name"},"title":{"type":"string","description":"Employee title"},"email":{"type":"string","format":"email","description":"Primary email address"},"email_secondary":{"type":"string","format":"email","description":"Secondary email address"},"phone_primary":{"type":"string","description":"Primary phone number"},"phone_secondary":{"type":"string","description":"Secondary phone number"},"address_street":{"type":"string","description":"Street address"},"address_city":{"type":"string","description":"City"},"address_postal_code":{"type":"string","description":"Postal code"},"address_country":{"type":"string","description":"Country"},"note":{"type":"string","description":"Additional notes"},"organization_uuid":{"type":"string","format":"uuid","description":"Organization UUID"},"organization_unit_id":{"type":"string","description":"Primary organization unit ID"},"manager_id":{"type":"string","description":"Manager employee ID"},"hire_date":{"type":"string","format":"date","description":"Hire date"},"employment_type":{"type":"string","description":"Type of employment"},"is_active":{"type":"boolean","description":"Whether the employee is active"},"flowos_user_id":{"type":"string","description":"FlowOS user ID"}}}}}},"responses":{"200":{"description":"Employee updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"employee":{"$ref":"#/components/schemas/Employee"}}}}}},"400":{"description":"Invalid request data or employee ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Employee not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete an employee","description":"Delete an employee record by UUID","tags":["Employees"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Employee UUID","example":"5fac8bca-11a4-43d3-bc1e-86445968c612"}],"responses":{"204":{"description":"Employee deleted successfully"},"400":{"description":"Invalid employee ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Employee not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leave-types":{"get":{"summary":"List leave types","description":"Get all available leave types","tags":["Leave"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of leave types","content":{"application/json":{"schema":{"type":"object","properties":{"leaveTypes":{"type":"array","items":{"$ref":"#/components/schemas/LeaveType"}}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create leave type","description":"Create a new leave type","tags":["Leave"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name of the leave type"},"code":{"type":"string","description":"Unique code for the leave type"},"description":{"type":"string","description":"Description of the leave type"},"isPaid":{"type":"boolean","description":"Whether this leave type is paid"},"maxDaysPerYear":{"type":"integer","description":"Maximum days allowed per year"},"requiresApproval":{"type":"boolean","description":"Whether this leave type requires approval"},"color":{"type":"string","description":"Color code for UI display"}},"required":["name","code","isPaid","requiresApproval"]}}}},"responses":{"201":{"description":"Leave type created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeaveType"}}}},"400":{"description":"Invalid request data or duplicate code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/employees/{employeeId}/leave-requests":{"get":{"summary":"Get employee leave requests","description":"Get leave requests for a specific employee","tags":["Leave"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"employeeId","required":true,"schema":{"type":"string","format":"uuid"},"description":"Employee UUID"},{"in":"query","name":"status","schema":{"type":"string","enum":["pending","approved","rejected","cancelled"]},"description":"Filter by leave request status"}],"responses":{"200":{"description":"List of leave requests","content":{"application/json":{"schema":{"type":"object","properties":{"leaveRequests":{"type":"array","items":{"$ref":"#/components/schemas/LeaveRequest"}}}}}}},"400":{"description":"Invalid employee ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"servers":[{"url":"https://flowos.scrumdesk.com/api/hr","description":"Production (third parties — use in Postman)"},{"url":"http://localhost:3001/api/hr","description":"Local module backend (direct on module port)"}]}