Employee — API Reference · Engineering Services

Base URL — /api/employee/
Auth — Authorization: Bearer {token} · user_type must be employee
Scope — all data is filtered to the authenticated user only (assigned_user_id = auth()->id())

📊

Dashboard

GET/api/employee/dashboard

KPI summary for the logged-in employee. Returns personal assignment count and open task count.

Auth required

employee user_type

Response

JSON

{
  "success": true,
  "msg": "Dashboard",
  "data": {
    "assignment_count": 2,
    "open_task_count": 5,
    "welcome_message": "Employee portal dashboard"
  }
}

Errors

401 Unauthenticated403 Forbidden

✅

Tasks

GET/api/employee/tasks

Paginated list of tasks assigned to this employee, newest first.

Auth required

employee user_type

Parameters

Param	Description
per_page	Default 20

Response

JSON

{
  "success": true,
  "msg": "Tasks",
  "data": [
    {
      "id": 3,
      "business_id": 1,
      "project_id": 4,
      "project_name": "Block A",
      "assigned_user_id": 7,
      "title": "Inspect column formwork — Grid B",
      "description": "Check alignment and plumb before concrete pour",
      "status": "pending",
      "priority": "high",
      "due_date": "2026-06-25"
    },
    {
      "id": 2,
      "business_id": 1,
      "project_id": 4,
      "project_name": "Block A",
      "assigned_user_id": 7,
      "title": "Submit rebar delivery sign-off",
      "description": "",
      "status": "completed",
      "priority": "normal",
      "due_date": "2026-06-20"
    }
  ],
  "pagination": {"current_page": 1, "per_page": 20, "total": 5, "last_page": 1}
}

Errors

401 Unauthenticated403 Forbidden

🕐

Time Clock

GET/api/employee/clock

All clock entries for this employee ordered by clock_in_at descending.

Auth required

employee user_type

Response

JSON

{
  "success": true,
  "msg": "Clock entries",
  "data": [
    {
      "id": 12,
      "business_id": 1,
      "user_id": 7,
      "project_id": 4,
      "project_name": "Block A",
      "clock_in_at": "2026-06-23T07:45:00+05:00",
      "clock_out_at": "2026-06-23T17:00:00+05:00",
      "notes": "Foundation inspection and rebar check"
    },
    {
      "id": 11,
      "business_id": 1,
      "user_id": 7,
      "project_id": 4,
      "project_name": "Block A",
      "clock_in_at": "2026-06-22T08:00:00+05:00",
      "clock_out_at": "2026-06-22T16:30:00+05:00",
      "notes": ""
    }
  ],
  "pagination": {"current_page": 1, "per_page": 20, "total": 28, "last_page": 2}
}

Errors

401 Unauthenticated403 Forbidden

POST/api/employee/clock/in

Start a new time clock entry. Returns 422 if employee is already clocked in (open entry exists with null clock_out_at).

Auth required

employee user_type

Only one active clock entry allowed at a time. The guard checks for a TimeClockEntry with clock_out_at IS NULL before allowing clock-in.

Request body

JSON

{
  "project_id": 4,
  "notes": "Starting foundation inspection — Block A"
}

Response

JSON

{
  "success": true,
  "msg": "Clocked in",
  "data": {
    "id": 13,
    "business_id": 1,
    "user_id": 7,
    "project_id": 4,
    "project_name": "Block A",
    "clock_in_at": "2026-06-23T07:48:00+05:00",
    "clock_out_at": null,
    "notes": "Starting foundation inspection — Block A"
  }
}

Errors

401 Unauthenticated403 Forbidden422 Validation failed

POST/api/employee/clock/out

Close the open clock entry. Returns 422 if no open entry exists.

Auth required

employee user_type

Request body

JSON

{
  "notes": "Completed column alignment check; all good"
}

Response

JSON

{
  "success": true,
  "msg": "Clocked out",
  "data": {
    "id": 13,
    "business_id": 1,
    "user_id": 7,
    "project_id": 4,
    "project_name": "Block A",
    "clock_in_at": "2026-06-23T07:48:00+05:00",
    "clock_out_at": "2026-06-23T17:05:00+05:00",
    "notes": "Completed column alignment check; all good"
  }
}

Errors

401 Unauthenticated403 Forbidden422 Validation failed

📅

Calendar

GET/api/employee/calendar

Calendar events assigned to this employee, ordered by starts_at ascending.

Auth required

employee user_type

Response

JSON

{
  "success": true,
  "msg": "Calendar",
  "data": [
    {
      "id": 5,
      "project_id": 4,
      "project_name": "Block A",
      "assigned_user_id": 7,
      "title": "Foundation inspection",
      "description": "Structural engineer site visit",
      "starts_at": "2026-07-05T09:00:00+05:00",
      "ends_at": "2026-07-05T12:00:00+05:00",
      "event_type": "inspection"
    }
  ],
  "pagination": {"current_page": 1, "per_page": 20, "total": 3, "last_page": 1}
}

Errors

401 Unauthenticated403 Forbidden

📍

Site Visits

GET/api/employee/site-visits

Site visit log for this employee, newest first.

Auth required

employee user_type

Response

JSON

{
  "success": true,
  "msg": "Site visits",
  "data": [
    {
      "id": 4,
      "business_id": 1,
      "project_id": 4,
      "project_name": "Block A",
      "user_id": 7,
      "title": "Footing pour inspection",
      "notes": "All columns poured; no issues",
      "visited_at": "2026-06-21T10:00:00+05:00",
      "status": "completed"
    }
  ],
  "pagination": {"current_page": 1, "per_page": 20, "total": 4, "last_page": 1}
}

Errors

401 Unauthenticated403 Forbidden

POST/api/employee/site-visits

Log a new site visit. Status is automatically set to completed.

Auth required

employee user_type

Request body

JSON

{
  "title": "Steel delivery inspection",
  "notes": "24 tonnes TMT bars received; checked against delivery note",
  "project_id": 4,
  "visited_at": "2026-06-23T11:30:00+05:00"
}

Response

JSON

{
  "success": true,
  "msg": "Site visit logged",
  "data": {
    "id": 5,
    "business_id": 1,
    "project_id": 4,
    "project_name": "Block A",
    "user_id": 7,
    "title": "Steel delivery inspection",
    "notes": "24 tonnes TMT bars received; checked against delivery note",
    "visited_at": "2026-06-23T11:30:00+05:00",
    "status": "completed"
  }
}

Errors

401 Unauthenticated403 Forbidden422 Validation failed

🖼

Gallery

GET/api/employee/gallery

Gallery items uploaded by this employee, newest first.

Auth required

employee user_type

Response

JSON

{
  "success": true,
  "msg": "Gallery",
  "data": [
    {
      "id": 8,
      "business_id": 1,
      "project_id": 4,
      "project_name": "Block A",
      "uploaded_by": 7,
      "title": "Column formwork Grid B",
      "file_path": "gallery/proj4/col-formwork-b.jpg",
      "visibility": "internal"
    }
  ],
  "pagination": {"current_page": 1, "per_page": 20, "total": 12, "last_page": 1}
}

Errors

401 Unauthenticated403 Forbidden

🔔

Notifications

GET/api/employee/notifications

Bell-dropdown endpoint. Returns up to 20 most recent unread notifications for the authenticated employee. No pagination key.

Auth required

employee user_type

No query parameters

Response 200

JSON

{
  "success": true,
  "msg": "Notifications",
  "data": [
    {
      "id": 7,
      "type": "task_assigned",
      "title": "Task Assigned to You",
      "body": "Inspect column formwork — Grid B is due 25 Jun 2026.",
      "is_read": false,
      "data": { "task_id": 34, "project_id": 5 },
      "created_at": "2026-07-01T08:00:00+05:00"
    },
    {
      "id": 6,
      "type": "site_visit_approved",
      "title": "Site Visit Log Approved",
      "body": "Your site visit log for Al-Noor Tower (30 Jun) has been approved.",
      "is_read": false,
      "data": { "site_visit_id": 12 },
      "created_at": "2026-06-30T17:45:00+05:00"
    }
  ]
}

Errors

401 Unauthenticated403 Non-employee role

PATCH/api/employee/notifications/read-all

Marks all unread notifications as read for the authenticated employee.

Auth required

employee user_type

No request body required

Response 200

JSON

{ "success": true, "msg": "All marked read", "data": null }

Errors

401 Unauthenticated403 Non-employee role