Staff Management API Endpoints
This page provides the complete API reference for the Staff Management API.
OpenAPI Specification
The complete OpenAPI specification for the Staff Management API is available at openapi.yaml.
Common Staff Management Workflows
Staff Account Management
// Create new staff member
const newStaff = await fetch('/api/v1/staff/users', {
method: 'POST',
headers: {
'Authorization': `Bearer ${adminToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
email: 'new.staff@hotel.com',
first_name: 'John',
last_name: 'Smith',
department: 'housekeeping',
role: 'housekeeper',
shift_preferences: ['morning', 'afternoon'],
emergency_contact: {
name: 'Jane Smith',
phone: '+1-555-0123',
relationship: 'spouse'
},
start_date: '2024-01-15'
})
});
// Update staff information
const staffUpdate = await fetch(`/api/v1/staff/users/${staffId}`, {
method: 'PUT',
headers: {
'Authorization': `Bearer ${managerToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
role: 'senior_housekeeper',
hourly_rate: 18.50,
permissions: ['assign_tasks', 'view_reports'],
certification_status: 'certified'
})
});
Task Management Operations
// Create housekeeping task
const task = await fetch('/api/v1/staff/tasks', {
method: 'POST',
headers: {
'Authorization': `Bearer ${supervisorToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
title: 'Clean Room 205',
description: 'Guest checkout - VIP cleaning required',
category: 'housekeeping',
priority: 'high',
assigned_to: 'staff_123',
room_number: '205',
estimated_duration: 45,
special_instructions: 'Extra attention to bathroom - guest complaint',
checklist: [
'Replace all linens',
'Deep clean bathroom',
'Vacuum and mop floors',
'Restock all amenities',
'Check and clean all surfaces'
],
due_date: '2024-01-15T14:00:00Z'
})
});
// Update task progress
const taskUpdate = await fetch(`/api/v1/staff/tasks/${taskId}`, {
method: 'PUT',
headers: {
'Authorization': `Bearer ${staffToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
status: 'in_progress',
progress_notes: 'Started cleaning, found additional maintenance issue',
estimated_completion: '2024-01-15T14:45:00Z',
issues_found: ['Leaky shower head', 'Burnt out bulb in reading lamp']
})
});
// Complete task with verification
const taskCompletion = await fetch(`/api/v1/staff/tasks/${taskId}/complete`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${staffToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
completion_notes: 'Room fully cleaned and inspected',
actual_duration: 50,
quality_photos: [
'https://storage.stayzr.com/tasks/room205_completed_1.jpg',
'https://storage.stayzr.com/tasks/room205_completed_2.jpg'
],
checklist_status: {
'Replace all linens': true,
'Deep clean bathroom': true,
'Vacuum and mop floors': true,
'Restock all amenities': true,
'Check and clean all surfaces': true
},
maintenance_requests: ['shower_head_repair']
})
});
Schedule Management
// Create weekly schedule for department
const weeklySchedule = await fetch('/api/v1/staff/schedules', {
method: 'POST',
headers: {
'Authorization': `Bearer ${managerToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
week_start: '2024-01-15',
department: 'housekeeping',
shifts: [
{
staff_id: 'staff_123',
date: '2024-01-15',
start_time: '08:00',
end_time: '16:00',
position: 'senior_housekeeper',
break_times: ['12:00-12:30'],
assigned_floors: [2, 3]
},
{
staff_id: 'staff_124',
date: '2024-01-15',
start_time: '09:00',
end_time: '17:00',
position: 'housekeeper',
break_times: ['13:00-13:30'],
assigned_floors: [1, 4]
}
]
})
});
// Request shift swap
const shiftSwap = await fetch('/api/v1/staff/schedules/swap-request', {
method: 'POST',
headers: {
'Authorization': `Bearer ${staffToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
original_shift_id: 'shift_789',
requested_with_staff_id: 'staff_125',
reason: 'Medical appointment',
urgency: 'high',
compensation_offered: 'Take their Friday evening shift'
})
});
// Approve/deny shift swap (manager)
const swapApproval = await fetch(`/api/v1/staff/schedules/swap-requests/${swapRequestId}/approve`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${managerToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
approved: true,
manager_notes: 'Approved - adequate coverage maintained'
})
});
Communication and Messaging
// Send department-wide message
const departmentMessage = await fetch('/api/v1/staff/messages', {
method: 'POST',
headers: {
'Authorization': `Bearer ${managerToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
recipients: {
type: 'department',
department: 'housekeeping'
},
priority: 'urgent',
title: 'VIP Guest Early Arrival',
message: 'Presidential suite must be ready by 11 AM for VIP guest early check-in. Please prioritize.',
requires_acknowledgment: true,
expires_at: '2024-01-15T11:00:00Z',
attachments: ['vip_preferences.pdf']
})
});
// Send individual message
const individualMessage = await fetch('/api/v1/staff/messages', {
method: 'POST',
headers: {
'Authorization': `Bearer ${staffToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
recipients: {
type: 'individual',
staff_ids: ['staff_456']
},
priority: 'normal',
title: 'Shift Coverage Request',
message: 'Hi Sarah, could you cover the front desk for 30 minutes while I handle the group check-in?',
requires_acknowledgment: true
})
});
// Mark message as read/acknowledged
const messageAck = await fetch(`/api/v1/staff/messages/${messageId}/acknowledge`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${staffToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
acknowledged: true,
response: 'Understood, will prioritize Presidential suite'
})
});
Performance and Analytics
// Get individual staff performance
const staffPerformance = await fetch(`/api/v1/staff/users/${staffId}/performance?period=last_month`, {
headers: { 'Authorization': `Bearer ${managerToken}` }
});
const performanceData = await staffPerformance.json();
// Returns: task completion rates, quality scores, punctuality, guest feedback
// Get department analytics
const departmentAnalytics = await fetch('/api/v1/staff/analytics/department?department=housekeeping&period=last_week', {
headers: { 'Authorization': `Bearer ${managerToken}` }
});
const analytics = await departmentAnalytics.json();
// Returns: team performance, productivity metrics, workload distribution
// Get operational insights
const operationalInsights = await fetch('/api/v1/staff/analytics/operations?metrics=efficiency,workload&period=current_month', {
headers: { 'Authorization': `Bearer ${adminToken}` }
});
Role and Permission Management
// Create custom role
const customRole = await fetch('/api/v1/staff/roles', {
method: 'POST',
headers: {
'Authorization': `Bearer ${adminToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'Night Auditor',
description: 'Front desk night shift supervisor with additional security responsibilities',
department: 'front_desk',
is_supervisory: true,
permissions: [
'view_all_guests',
'handle_checkins_checkouts',
'assign_maintenance_tasks',
'access_security_systems',
'view_financial_reports',
'override_room_rates'
],
shift_restrictions: ['night'],
hourly_rate_range: { min: 22.00, max: 28.00 }
})
});
// Assign role to staff member
const roleAssignment = await fetch(`/api/v1/staff/users/${staffId}/roles`, {
method: 'PUT',
headers: {
'Authorization': `Bearer ${adminToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
primary_role: 'night_auditor',
secondary_roles: ['security_backup'],
effective_date: '2024-01-20',
probation_period: 90
})
});
Real-time Communication via WebSocket
const staffWs = new WebSocket('wss://api.stayzr.com/v1/staff/ws');
staffWs.onopen = () => {
// Authenticate and subscribe to relevant channels
staffWs.send(JSON.stringify({
type: 'auth',
token: staffToken,
subscriptions: [
'task_assignments',
'schedule_updates',
'department_messages',
'urgent_notifications'
]
}));
};
staffWs.onmessage = (event) => {
const update = JSON.parse(event.data);
switch(update.type) {
case 'task_assigned':
showNewTaskAlert(update.data);
updateTaskList(update.data);
break;
case 'schedule_changed':
updateScheduleDisplay(update.data);
showScheduleNotification(update.data);
break;
case 'urgent_message':
showUrgentAlert(update.data);
markAsRequiringAcknowledgment(update.data);
break;
case 'shift_swap_request':
showShiftSwapRequest(update.data);
break;
}
};
Error Handling
Staff Management API errors include context-specific information:
{
"error": {
"code": "INSUFFICIENT_PERMISSIONS",
"message": "Staff member does not have permission to assign tasks to other departments",
"required_permission": "cross_department_task_assignment",
"current_roles": ["housekeeper"],
"suggested_action": "Contact your department manager for task assignment"
}
}
Common Error Codes
INSUFFICIENT_PERMISSIONS(403) - User lacks required permission for actionSTAFF_NOT_FOUND(404) - Invalid staff member identifierSCHEDULE_CONFLICT(409) - Shift assignment conflicts with existing scheduleTASK_ALREADY_ASSIGNED(409) - Task is already assigned to another staff memberINVALID_TIME_SLOT(422) - Requested time slot is invalid or unavailableDEPARTMENT_MISMATCH(422) - Action not allowed across different departmentsSHIFT_LOCKED(423) - Schedule is locked and cannot be modifiedQUOTA_EXCEEDED(429) - Too many requests or operations