Authenticated API

This endpoint requires a valid JWT Bearer token. Accessible via the API gateway.

Workforce API

Manage employee schedules, track time entries, and generate labor reports.

Overview

Attribute	Value
Base Path	/api/v1/workforce
Authentication	Bearer Token
Required Roles	restaurant_staff, manager, restaurant_manager, tenant_admin, platform_admin, system_admin, super_admin

Endpoints

List Schedules

Retrieve employee schedules.

GET /api/v1/workforce/schedules

Query Parameters

Parameter	Type	Description
location_id	uuid	Filter by location
staff_id	uuid	Filter by specific employee
start_date	date	Start of date range
end_date	date	End of date range
status	string	scheduled, in_progress, completed, cancelled
department	string	Filter by department
page	integer	Page number
limit	integer	Results per page

Response

{
  "data": [
    {
      "id": "sched_001",
      "staff_id": "staff_abc",
      "staff_name": "Jane Smith",
      "location_id": "loc_123",
      "department": "Front of House",
      "role": "Server",
      "shift_start": "2026-01-25T11:00:00Z",
      "shift_end": "2026-01-25T19:00:00Z",
      "break_duration_minutes": 30,
      "status": "scheduled",
      "notes": ""
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45
  }
}

Schedule Status Values

Status	Description
scheduled	Upcoming shift
in_progress	Currently working
completed	Shift completed
cancelled	Shift cancelled

---

List Time Entries

Retrieve time clock entries.

GET /api/v1/workforce/time-entries

Query Parameters

Parameter	Type	Description
location_id	uuid	Filter by location
staff_id	uuid	Filter by employee
start_date	date	Start of date range
end_date	date	End of date range
status	string	pending, active, completed, missed
page	integer	Page number
limit	integer	Results per page

Response

{
  "data": [
    {
      "id": "time_001",
      "staff_id": "staff_abc",
      "staff_name": "Jane Smith",
      "location_id": "loc_123",
      "schedule_id": "sched_001",
      "clock_in": "2026-01-25T10:58:00Z",
      "clock_out": "2026-01-25T19:05:00Z",
      "breaks": [
        {
          "start": "2026-01-25T14:00:00Z",
          "end": "2026-01-25T14:30:00Z",
          "type": "meal"
        }
      ],
      "total_hours": 7.62,
      "overtime_hours": 0,
      "status": "completed",
      "tips_declared": 125.50
    }
  ]
}

Time Entry Status Values

Status	Description
pending	Scheduled but not clocked in
active	Currently clocked in
completed	Clocked out
missed	Scheduled but never clocked in

---

Get Labor Report

Generate a labor cost report.

GET /api/v1/workforce/reports/labor

Query Parameters

Parameter	Type	Description
location_id	uuid	Filter by location
start_date	date	Report start date
end_date	date	Report end date
group_by	string	day, week, employee, department

Response

{
  "period": {
    "start": "2026-01-20",
    "end": "2026-01-26"
  },
  "location_id": "loc_123",
  "summary": {
    "total_hours": 542.5,
    "regular_hours": 520.0,
    "overtime_hours": 22.5,
    "total_labor_cost": 8750.00,
    "avg_hourly_rate": 16.12
  },
  "by_department": [
    {
      "department": "Front of House",
      "hours": 320.5,
      "cost": 5128.00,
      "headcount": 12
    },
    {
      "department": "Back of House",
      "hours": 222.0,
      "cost": 3622.00,
      "headcount": 8
    }
  ],
  "labor_percentage": {
    "of_revenue": 28.5,
    "target": 30.0,
    "status": "good"
  }
}

---

Staff Endpoints

Get Staff Profile

Retrieve staff member details.

GET /api/v1/staff/{staff_id}

Response

{
  "id": "staff_abc",
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane.smith@restaurant.com",
  "phone": "+1234567890",
  "role": "Server",
  "department": "Front of House",
  "locations": ["loc_123", "loc_456"],
  "hire_date": "2025-03-15",
  "hourly_rate": 16.00,
  "status": "active",
  "certifications": [
    {"type": "food_handler", "expires": "2027-03-15"},
    {"type": "alcohol_service", "expires": "2026-06-01"}
  ],
  "schedule_preferences": {
    "max_hours_per_week": 40,
    "preferred_days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
    "unavailable_dates": ["2026-02-14", "2026-02-15"]
  }
}

---

Clock In/Out

Clock In

POST /api/v1/workforce/clock-in

Request Body

{
  "staff_id": "staff_abc",
  "location_id": "loc_123",
  "pin": "1234",
  "photo_verification": "base64_image_optional"
}

Response

{
  "time_entry_id": "time_002",
  "staff_id": "staff_abc",
  "clock_in": "2026-01-25T10:58:00Z",
  "scheduled_start": "2026-01-25T11:00:00Z",
  "early_clock_in_minutes": 2,
  "location_id": "loc_123",
  "status": "active"
}

Clock Out

POST /api/v1/workforce/clock-out

Request Body

{
  "time_entry_id": "time_002",
  "tips_declared": 125.50,
  "cash_drop": 350.00
}

---

Break Management

Start Break

POST /api/v1/workforce/breaks/start

Request Body

{
  "time_entry_id": "time_002",
  "break_type": "meal"
}

End Break

POST /api/v1/workforce/breaks/end

Request Body

{
  "time_entry_id": "time_002"
}

Break Types

Type	Typical Duration
meal	30 minutes
rest	10-15 minutes
paid	Varies

---

Schedule Management

Create Schedule

POST /api/v1/workforce/schedules

Request Body

{
  "staff_id": "staff_abc",
  "location_id": "loc_123",
  "shift_start": "2026-01-26T11:00:00Z",
  "shift_end": "2026-01-26T19:00:00Z",
  "department": "Front of House",
  "role": "Server",
  "notes": "Training new hire"
}

Update Schedule

PUT /api/v1/workforce/schedules/{schedule_id}

Delete Schedule

DELETE /api/v1/workforce/schedules/{schedule_id}

---

Webhooks

Event	Description
workforce.clock_in	Employee clocked in
workforce.clock_out	Employee clocked out
workforce.break_start	Break started
workforce.break_end	Break ended
workforce.schedule_created	New schedule created
workforce.schedule_updated	Schedule modified
workforce.overtime_alert	Employee approaching overtime

---

Error Responses

Status	Code	Description
400	invalid_date_range	End date before start date
400	invalid_status	Status value not recognized
401	invalid_pin	Clock in PIN incorrect
403	not_scheduled	No schedule for this time
404	staff_not_found	Staff ID not found
409	already_clocked_in	Staff already has active entry

---

Related Documentation

• Workforce Staff Chat - Staff communication
• Employees API - Employee management
• Labor Reports - Labor reporting