Authenticated API

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

Employees API

Employee management, onboarding, time tracking, and labor compliance.

Overview

Attribute	Value
Base Path	`/api/v1/employees`
Authentication	Bearer Token
Required Roles	`manager`, `restaurant_manager`, `hr_manager`, `tenant_admin`, `platform_admin`, `system_admin`, `super_admin`

Employee Management

List Employees

GET /api/v1/employees

Query Parameters

Parameter	Type	Description
`status`	string	`active`, `inactive`, `terminated`
`role`	string	Filter by role
`location_id`	uuid	Filter by location
`department`	string	Filter by department
`search`	string	Search name/email

Response

{
  "employees": [
    {
      "id": "emp_001",
      "employee_number": "EMP-2024-0042",
      "first_name": "Sarah",
      "last_name": "Johnson",
      "email": "sarah.johnson@example.com",
      "phone": "+15551234567",
      "status": "active",
      "role": {
        "id": "role_server",
        "name": "Server"
      },
      "department": "front_of_house",
      "location": {
        "id": "loc_123",
        "name": "Downtown Location"
      },
      "hire_date": "2024-06-15",
      "employment_type": "full_time",
      "pay_rate": {
        "type": "hourly",
        "rate": 15.00,
        "currency": "USD"
      },
      "certifications": [
        {
          "name": "Food Handler",
          "expires_at": "2027-06-15"
        }
      ],
      "created_at": "2024-06-15T00:00:00Z"
    }
  ],
  "total": 45,
  "pagination": {
    "page": 1,
    "limit": 20
  }
}

Create Employee

POST /api/v1/employees

Request Body

{
  "first_name": "Michael",
  "last_name": "Chen",
  "email": "michael.chen@example.com",
  "phone": "+15559876543",
  "role_id": "role_cook",
  "department": "back_of_house",
  "location_id": "loc_123",
  "hire_date": "2026-02-01",
  "employment_type": "full_time",
  "pay_rate": {
    "type": "hourly",
    "rate": 18.00
  },
  "emergency_contact": {
    "name": "Jane Chen",
    "relationship": "spouse",
    "phone": "+15551112222"
  },
  "start_onboarding": true
}

Response

{
  "id": "emp_050",
  "employee_number": "EMP-2026-0050",
  "status": "onboarding",
  "onboarding": {
    "checklist_id": "onboard_001",
    "progress": 0,
    "due_date": "2026-02-15"
  },
  "created_at": "2026-01-24T19:30:00Z"
}

Get Employee

GET /api/v1/employees/{employee_id}

Response

{
  "id": "emp_001",
  "employee_number": "EMP-2024-0042",
  "first_name": "Sarah",
  "last_name": "Johnson",
  "email": "sarah.johnson@example.com",
  "phone": "+15551234567",
  "address": {
    "street": "456 Oak Ave",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94102"
  },
  "date_of_birth": "1995-03-15",
  "ssn_last_four": "4567",
  "status": "active",
  "role": {
    "id": "role_server",
    "name": "Server",
    "permissions": ["orders:read", "orders:write", "tables:read"]
  },
  "department": "front_of_house",
  "location": {
    "id": "loc_123",
    "name": "Downtown Location"
  },
  "hire_date": "2024-06-15",
  "employment_type": "full_time",
  "pay_rate": {
    "type": "hourly",
    "rate": 15.00,
    "currency": "USD"
  },
  "pay_history": [
    {"effective_date": "2024-06-15", "rate": 14.00},
    {"effective_date": "2025-06-15", "rate": 15.00}
  ],
  "certifications": [
    {
      "id": "cert_001",
      "name": "Food Handler",
      "issued_at": "2024-06-20",
      "expires_at": "2027-06-15",
      "status": "valid",
      "document_url": "https://..."
    },
    {
      "id": "cert_002",
      "name": "Alcohol Service (TIPS)",
      "issued_at": "2024-07-01",
      "expires_at": "2026-07-01",
      "status": "expiring_soon"
    }
  ],
  "emergency_contact": {
    "name": "John Johnson",
    "relationship": "father",
    "phone": "+15559998888"
  },
  "documents": [
    {"type": "w4", "uploaded_at": "2024-06-15"},
    {"type": "i9", "uploaded_at": "2024-06-15"},
    {"type": "direct_deposit", "uploaded_at": "2024-06-16"}
  ],
  "metrics": {
    "hours_this_week": 32.5,
    "hours_this_pay_period": 65.0,
    "avg_hours_per_week": 35.2,
    "performance_score": 4.5
  }
}

Update Employee

PUT /api/v1/employees/{employee_id}

Terminate Employee

POST /api/v1/employees/{employee_id}/terminate

Request Body

{
  "termination_date": "2026-02-15",
  "reason": "voluntary_resignation",
  "notes": "Moving to another city",
  "final_pay_date": "2026-02-15",
  "eligible_for_rehire": true
}

Time Clock

Clock In

POST /api/v1/employees/{employee_id}/clock-in

Request Body

{
  "location_id": "loc_123",
  "position": "server",
  "timestamp": "2026-01-24T16:00:00Z",
  "verification": {
    "method": "pin",
    "value": "1234"
  }
}

Response

{
  "time_entry_id": "time_001",
  "employee_id": "emp_001",
  "clock_in": "2026-01-24T16:00:00Z",
  "scheduled_shift": {
    "start": "2026-01-24T16:00:00Z",
    "end": "2026-01-24T23:00:00Z",
    "position": "server"
  },
  "early_clock_in": false,
  "alerts": []
}

Clock Out

POST /api/v1/employees/{employee_id}/clock-out

Request Body

{
  "timestamp": "2026-01-24T23:15:00Z",
  "tip_declaration": {
    "cash_tips": 85.00,
    "credit_tips_override": null
  }
}

Response

{
  "time_entry_id": "time_001",
  "clock_in": "2026-01-24T16:00:00Z",
  "clock_out": "2026-01-24T23:15:00Z",
  "total_hours": 7.25,
  "breaks_taken": [
    {
      "start": "2026-01-24T19:00:00Z",
      "end": "2026-01-24T19:30:00Z",
      "type": "meal",
      "duration_minutes": 30
    }
  ],
  "overtime_hours": 0,
  "tips": {
    "cash_declared": 85.00,
    "credit_card": 125.50,
    "total": 210.50
  },
  "alerts": [
    {
      "type": "late_clock_out",
      "message": "Clocked out 15 minutes after scheduled end"
    }
  ]
}

Start Break

POST /api/v1/employees/{employee_id}/break/start

Request Body

{
  "break_type": "meal",
  "timestamp": "2026-01-24T19:00:00Z"
}

End Break

POST /api/v1/employees/{employee_id}/break/end

Get Time Entries

GET /api/v1/employees/{employee_id}/time-entries

Query Parameters

Parameter	Type	Description
`start_date`	date	Period start
`end_date`	date	Period end
`status`	string	`pending`, `approved`, `disputed`

Response

{
  "entries": [
    {
      "id": "time_001",
      "date": "2026-01-24",
      "clock_in": "2026-01-24T16:00:00Z",
      "clock_out": "2026-01-24T23:15:00Z",
      "position": "server",
      "location_id": "loc_123",
      "regular_hours": 7.25,
      "overtime_hours": 0,
      "breaks": [
        {"type": "meal", "duration_minutes": 30}
      ],
      "status": "approved",
      "tips": {
        "cash": 85.00,
        "credit": 125.50
      }
    }
  ],
  "summary": {
    "total_hours": 35.5,
    "regular_hours": 35.5,
    "overtime_hours": 0,
    "total_tips": 850.00
  }
}

Edit Time Entry

PUT /api/v1/employees/time-entries/{entry_id}

Request Body

{
  "clock_in": "2026-01-24T15:55:00Z",
  "clock_out": "2026-01-24T23:15:00Z",
  "reason": "Forgot to clock in on time",
  "manager_approval_required": true
}

Labor Compliance

Get Compliance Status

GET /api/v1/employees/{employee_id}/compliance

Response

{
  "employee_id": "emp_001",
  "status": "compliant",
  "checks": [
    {
      "type": "meal_break",
      "status": "compliant",
      "rule": "30-minute break required for shifts over 5 hours",
      "last_shift_compliance": true
    },
    {
      "type": "rest_break",
      "status": "compliant",
      "rule": "10-minute break every 4 hours"
    },
    {
      "type": "weekly_overtime",
      "status": "compliant",
      "current_hours": 35.5,
      "overtime_threshold": 40
    },
    {
      "type": "daily_overtime",
      "status": "compliant",
      "rule": "Overtime after 8 hours/day"
    },
    {
      "type": "minor_restrictions",
      "status": "not_applicable",
      "reason": "Employee is over 18"
    }
  ],
  "certifications": {
    "status": "warning",
    "expiring_soon": [
      {
        "name": "Alcohol Service (TIPS)",
        "expires_at": "2026-07-01",
        "days_remaining": 158
      }
    ]
  }
}

Get Overtime Report

GET /api/v1/employees/overtime

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Filter by location
`week_of`	date	Week to report on
`approaching`	boolean	Show those approaching OT

Response

{
  "week_of": "2026-01-20",
  "employees": [
    {
      "employee_id": "emp_005",
      "name": "John Smith",
      "hours_worked": 42.5,
      "overtime_hours": 2.5,
      "overtime_cost": 56.25,
      "scheduled_remaining": 8.0,
      "projected_overtime": 10.5
    },
    {
      "employee_id": "emp_012",
      "name": "Maria Garcia",
      "hours_worked": 38.0,
      "overtime_hours": 0,
      "scheduled_remaining": 8.0,
      "projected_overtime": 6.0,
      "alert": "Approaching overtime"
    }
  ],
  "summary": {
    "total_overtime_hours": 25.5,
    "total_overtime_cost": 573.75,
    "employees_in_overtime": 5,
    "employees_approaching": 3
  }
}

Documents

Upload Document

POST /api/v1/employees/{employee_id}/documents

Request (multipart/form-data)

file: w4_form.pdf
type: w4
effective_date: 2026-01-24

List Documents

GET /api/v1/employees/{employee_id}/documents

Get Document

GET /api/v1/employees/{employee_id}/documents/{document_id}

Performance

Get Performance Metrics

GET /api/v1/employees/{employee_id}/performance

Response

{
  "employee_id": "emp_001",
  "period": "2026-01",
  "metrics": {
    "attendance": {
      "score": 95,
      "shifts_scheduled": 20,
      "shifts_worked": 19,
      "late_arrivals": 1,
      "no_shows": 0
    },
    "sales_performance": {
      "score": 88,
      "total_sales": 12500.00,
      "avg_ticket": 45.50,
      "upsell_rate": 0.35,
      "rank": 3,
      "total_servers": 15
    },
    "customer_feedback": {
      "score": 92,
      "avg_rating": 4.6,
      "reviews_received": 12,
      "compliments": 5,
      "complaints": 0
    },
    "speed_of_service": {
      "score": 85,
      "avg_table_time_minutes": 48,
      "target_minutes": 45
    }
  },
  "overall_score": 90,
  "trend": "+3 vs last month"
}

Add Performance Note

POST /api/v1/employees/{employee_id}/performance/notes

Request Body

{
  "type": "commendation",
  "note": "Handled a difficult customer situation excellently",
  "date": "2026-01-24",
  "visibility": "manager_only"
}

Webhooks

Event	Description
`employee.created`	New employee added
`employee.updated`	Employee info updated
`employee.terminated`	Employee terminated
`employee.clocked_in`	Employee clocked in
`employee.clocked_out`	Employee clocked out
`employee.overtime_approaching`	Nearing overtime threshold
`employee.certification_expiring`	Certification expiring soon
`employee.break_missed`	Required break not taken

Error Responses

Status	Code	Description
400	`invalid_clock_in`	Already clocked in
400	`invalid_clock_out`	Not clocked in
400	`shift_not_scheduled`	No scheduled shift
404	`employee_not_found`	Employee ID not found
409	`break_in_progress`	Break already started
422	`compliance_violation`	Would violate labor rules

Workforce API - Scheduling
Payroll Integration - Payroll export
Training API - Employee training

Overview​

Employee Management​

List Employees​

Create Employee​

Get Employee​

Update Employee​

Terminate Employee​

Time Clock​

Clock In​

Clock Out​

Start Break​

End Break​

Get Time Entries​

Edit Time Entry​

Labor Compliance​

Get Compliance Status​

Get Overtime Report​

Documents​

Upload Document​

List Documents​

Get Document​

Performance​

Get Performance Metrics​

Add Performance Note​

Webhooks​

Error Responses​

Related Documentation​

Overview

Employee Management

List Employees

Create Employee

Get Employee

Update Employee

Terminate Employee

Time Clock

Clock In

Clock Out

Start Break

End Break

Get Time Entries

Edit Time Entry

Labor Compliance

Get Compliance Status

Get Overtime Report

Documents

Upload Document

List Documents

Get Document

Performance

Get Performance Metrics

Add Performance Note

Webhooks

Error Responses

Related Documentation