Contractor Portal · API Referenceuser_type: contractor
Base URL — /api/contractor/
Auth — Authorization: Bearer {token} · user_type must be contractor
Scope — data is resolved via Subcontractor WHERE user_id = auth()->id(); the subcontractor record links to vouchers and ledger
🏢

Workspace & Dashboard

GET/api/contractor/workspaces

Returns the subcontractor profile for the logged-in user. Used to display company info on the home screen. Returns a placeholder if no Subcontractor record is linked to this user_id.

Auth required
contractor user_type
Response
JSON
{
  "success": true,
  "msg": "Workspace",
  "data": {
    "id": 3,
    "business_id": 1,
    "user_id": 6,
    "company_name": "RapidSteel Contractors",
    "trade_type": "steel_works",
    "contact_email": "rapidsteel@contractors.test",
    "contact_phone": "+92-321-0011223",
    "status": "active"
  }
}
Errors
401 Unauthenticated403 Forbidden
GET/api/contractor/dashboard

KPI dashboard: total voucher count for this subcontractor.

Auth required
contractor user_type
Response
JSON
{
  "success": true,
  "msg": "Dashboard",
  "data": {
    "voucher_count": 8,
    "welcome_message": "Contractor portal dashboard"
  }
}
Errors
401 Unauthenticated403 Forbidden
📋

Daily Logs

GET/api/contractor/daily-logs

Daily site logs submitted by this contractor user, ordered by log_date descending.

Auth required
contractor user_type
Response
JSON
{
  "success": true,
  "msg": "Daily logs",
  "data": [
    {
      "id": 4,
      "business_id": 1,
      "project_id": 4,
      "subcontractor_id": 3,
      "user_id": 6,
      "log_date": "2026-06-22",
      "work_summary": "Placed 3.2 tonnes TMT bars in columns B1-B6",
      "workers_count": 12,
      "status": "submitted"
    }
  ],
  "pagination": {"current_page": 1, "per_page": 20, "total": 4, "last_page": 1}
}
Errors
401 Unauthenticated403 Forbidden
POST/api/contractor/daily-logs

Submit a new daily log. Status is automatically set to submitted. The subcontractor_id is resolved automatically from the authenticated user.

Auth required
contractor user_type
Request body
JSON
{
  "log_date": "2026-06-23",
  "work_summary": "Completed column formwork for grid C; 10 workers on site",
  "project_id": 4,
  "workers_count": 10
}
Response
JSON
{
  "success": true,
  "msg": "Daily log submitted",
  "data": {
    "id": 5,
    "business_id": 1,
    "project_id": 4,
    "subcontractor_id": 3,
    "user_id": 6,
    "log_date": "2026-06-23",
    "work_summary": "Completed column formwork for grid C; 10 workers on site",
    "workers_count": 10,
    "status": "submitted"
  }
}
Errors
401 Unauthenticated403 Forbidden422 Validation failed
💰

Expenses

GET/api/contractor/expenses

Expenses submitted by this contractor, ordered by expense_date descending.

Auth required
contractor user_type
Response
JSON
{
  "success": true,
  "msg": "Expenses",
  "data": [
    {
      "id": 2,
      "business_id": 1,
      "project_id": 4,
      "subcontractor_id": 3,
      "user_id": 6,
      "category": "fuel",
      "amount": 8500.0,
      "description": "Diesel for crane — week of 16 Jun 2026",
      "expense_date": "2026-06-20",
      "status": "pending"
    }
  ],
  "pagination": {"current_page": 1, "per_page": 20, "total": 2, "last_page": 1}
}
Errors
401 Unauthenticated403 Forbidden
POST/api/contractor/expenses

Submit a new expense claim. Status defaults to pending — requires admin approval to become approved.

Auth required
contractor user_type
Request body
JSON
{
  "category": "materials",
  "amount": 24500,
  "description": "Binding wire 200kg",
  "expense_date": "2026-06-23",
  "project_id": 4
}
Response
JSON
{
  "success": true,
  "msg": "Expense submitted",
  "data": {
    "id": 3,
    "business_id": 1,
    "project_id": 4,
    "subcontractor_id": 3,
    "user_id": 6,
    "category": "materials",
    "amount": 24500.0,
    "description": "Binding wire 200kg",
    "expense_date": "2026-06-23",
    "status": "pending"
  }
}
Errors
401 Unauthenticated403 Forbidden422 Validation failed
📦

Materials

GET/api/contractor/materials

Read-only view of material stock for the business this contractor is associated with. Helps contractors see available stock before requesting materials.

Auth required
contractor user_type
Response
JSON
{
  "success": true,
  "msg": "Materials",
  "data": [
    {
      "id": 1,
      "project_id": 4,
      "material_name": "OPC Cement 50kg",
      "unit": "bags",
      "quantity_on_hand": 240.0,
      "quantity_reserved": 60.0
    },
    {
      "id": 2,
      "project_id": 4,
      "material_name": "TMT Rebar 12mm",
      "unit": "kg",
      "quantity_on_hand": 8400.0,
      "quantity_reserved": 3200.0
    }
  ],
  "pagination": {"current_page": 1, "per_page": 20, "total": 5, "last_page": 1}
}
Errors
401 Unauthenticated403 Forbidden
🖼

Gallery

🧾

Vouchers

GET/api/contractor/vouchers

All vouchers for this contractor (filtered by subcontractor_id). Read-only; vouchers are created by admin.

Auth required
contractor user_type
If no Subcontractor record is linked to this user, returns an empty array rather than a 404.
Response
JSON
{
  "success": true,
  "msg": "Vouchers",
  "data": [
    {
      "id": 8,
      "project_id": 4,
      "subcontractor_id": 3,
      "voucher_no": "VCH-2026-0008",
      "voucher_type": "subcontractor",
      "status": "draft",
      "amount": 220000.0,
      "week_ending": "2026-06-28"
    },
    {
      "id": 7,
      "project_id": 4,
      "subcontractor_id": 3,
      "voucher_no": "VCH-2026-0007",
      "voucher_type": "subcontractor",
      "status": "approved",
      "amount": 185000.0,
      "week_ending": "2026-06-21"
    }
  ],
  "pagination": {"current_page": 1, "per_page": 20, "total": 8, "last_page": 1}
}
Errors
401 Unauthenticated403 Forbidden
📒

Ledger

GET/api/contractor/ledger

Ledger entries where party_type=subcontractor and party_id matches this user. Credit = money paid to contractor; debit = deductions.

Auth required
contractor user_type
Read-only. Entries are created by admin.
Response
JSON
{
  "success": true,
  "msg": "Ledger",
  "data": [
    {
      "id": 4,
      "project_id": 4,
      "party_type": "subcontractor",
      "party_id": 3,
      "entry_type": "payment",
      "debit": 0.0,
      "credit": 220000.0,
      "reference": "VCH-2026-0008",
      "description": "Payment for week 28 Jun 2026",
      "entry_date": "2026-06-28"
    },
    {
      "id": 3,
      "project_id": 4,
      "party_type": "subcontractor",
      "party_id": 3,
      "entry_type": "payment",
      "debit": 0.0,
      "credit": 185000.0,
      "reference": "VCH-2026-0007",
      "description": "Payment for week 21 Jun 2026",
      "entry_date": "2026-06-22"
    }
  ],
  "pagination": {"current_page": 1, "per_page": 20, "total": 8, "last_page": 1}
}
Errors
401 Unauthenticated403 Forbidden
🔔

Notifications

GET/api/contractor/notifications

In-app notifications for this contractor user.

Auth required
contractor user_type
Response
JSON
{
  "success": true,
  "msg": "Notifications",
  "data": [
    {
      "id": 4,
      "title": "Voucher approved",
      "body": "VCH-2026-0007 has been approved and payment is being processed",
      "is_read": false
    }
  ],
  "pagination": {"current_page": 1, "per_page": 20, "total": 1, "last_page": 1}
}
Errors
401 Unauthenticated403 Forbidden