{
  "openapi": "3.0.3",
  "info": {
    "title": "NeedNow API Documentation",
    "description": "Official OpenAPI 3.0 RESTful API specification for the **NeedNow** On-Demand Local Services Platform.\n\n### Platform Overview:\n- **Customer App**: Browse categories, create service needs (Phase 3), receive matching nearby verified providers & competitive quotes (Phase 4), compare offers, and book service.\n- **Provider App**: Registration, multi-step KYC submission, live job dispatch, availability toggle, earnings & performance tracking.\n- **Admin & SuperAdmin**: System verification, user status management, role-based access control.",
    "version": "1.0.0",
    "contact": {
      "name": "NeedNow Support",
      "url": "https://neednowdt.com/contact",
      "email": "support@neednowdt.com"
    }
  },
  "servers": [
    {
      "url": "https://neednowdt.com/api/v1",
      "description": "Production Server (Hostinger Live)"
    },
    {
      "url": "http://127.0.0.1:8000/api/v1",
      "description": "Local Development Server (Artisan Serve)"
    },
    {
      "url": "/api/v1",
      "description": "Current Host (Relative URL)"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Sanctum Token",
        "description": "Enter your Sanctum Bearer token: `Bearer {token}`"
      }
    },
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "example": 1 },
          "name": { "type": "string", "example": "Alex Johnson" },
          "email": { "type": "string", "example": "customer@neednow.com" },
          "phone": { "type": "string", "example": "+91 98401 23456" },
          "role": { "type": "string", "enum": ["superadmin", "admin", "customer", "provider"], "example": "customer" },
          "status": { "type": "string", "enum": ["active", "inactive", "suspended", "pending_approval"], "example": "active" },
          "avatar": { "type": "string", "nullable": true },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "Category": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "example": 9 },
          "name": { "type": "string", "example": "AC Service & Repair" },
          "icon": { "type": "string", "example": "ac_unit" },
          "description": { "type": "string", "example": "AC installation, gas refill & deep cleaning service" },
          "is_popular": { "type": "boolean", "example": true }
        }
      },
      "Need": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "example": 1 },
          "service_title": { "type": "string", "example": "My AC is not cooling. Need someone to check and fix it." },
          "category": { "type": "string", "example": "AC Service & Repair" },
          "description": { "type": "string", "example": "AC not cooling properly and making a buzzing noise." },
          "more_details": { "type": "string", "example": "1.5 Ton Split AC, 3 years old" },
          "when_needed": { "type": "string", "example": "ASAP" },
          "photos": { "type": "array", "items": { "type": "string" }, "example": ["uploads/ac_issue.jpg"] },
          "voice_duration": { "type": "string", "example": "18s" },
          "voice_note": { "type": "string", "example": "uploads/voice_note.m4a" },
          "location": { "type": "string", "example": "Anna Nagar, Chennai - 600040" },
          "address": { "type": "string", "example": "Door No. 12, 4th Main Road" },
          "urgency": { "type": "string", "example": "high" },
          "status": { "type": "string", "example": "active" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "NeedOffer": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "example": 1 },
          "need_id": { "type": "integer", "example": 1 },
          "provider_name": { "type": "string", "example": "Cool Care Solutions" },
          "rating": { "type": "number", "format": "float", "example": 4.8 },
          "reviews_count": { "type": "integer", "example": 120 },
          "distance_km": { "type": "number", "format": "float", "example": 5.2 },
          "price_range": { "type": "string", "example": "₹350 - ₹600" },
          "offer_price": { "type": "number", "format": "float", "example": 450.0 },
          "is_recommended": { "type": "boolean", "example": true },
          "response_time": { "type": "string", "example": "1-2 hrs" },
          "warranty": { "type": "string", "example": "30 days" },
          "estimated_time": { "type": "string", "example": "1-3 hours" },
          "status": { "type": "string", "enum": ["pending", "accepted", "rejected"], "example": "pending" }
        }
      },
      "Provider": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "example": 1 },
          "name": { "type": "string", "example": "Cool Care Solutions" },
          "service_category": { "type": "string", "example": "AC Service & Repair" },
          "rating": { "type": "number", "format": "float", "example": 4.8 },
          "reviews_count": { "type": "integer", "example": 120 },
          "distance": { "type": "string", "example": "5.2 km away" },
          "price_range": { "type": "string", "example": "₹350 - ₹600" },
          "is_verified": { "type": "boolean", "example": true },
          "is_available": { "type": "boolean", "example": true },
          "availability_text": { "type": "string", "example": "Available Now" }
        }
      },
      "ProviderJob": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "example": 1 },
          "job_code": { "type": "string", "example": "NN-CONF-20261018-0001" },
          "service_title": { "type": "string", "example": "AC Repair Service" },
          "location": { "type": "string", "example": "Anna Nagar, Chennai" },
          "customer_name": { "type": "string", "example": "Alex Johnson" },
          "customer_phone": { "type": "string", "example": "+91 98401 23456" },
          "scheduled_slot": { "type": "string", "example": "ASAP" },
          "amount": { "type": "number", "format": "float", "example": 450.0 },
          "status": { "type": "string", "enum": ["Upcoming", "In Progress", "Completed", "Cancelled"], "example": "Upcoming" },
          "payment_method": { "type": "string", "example": "Cash / Online UPI" }
        }
      }
    }
  },
  "paths": {
    "/auth/send-otp": {
      "post": {
        "tags": ["Authentication"],
        "summary": "Send mobile OTP via SMS",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["phone"],
                "properties": {
                  "phone": { "type": "string", "example": "+91 98401 23456" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OTP sent successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "success" },
                    "message": { "type": "string", "example": "OTP sent successfully" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/auth/verify-otp": {
      "post": {
        "tags": ["Authentication"],
        "summary": "Verify mobile OTP and authenticate/login user",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["phone", "otp"],
                "properties": {
                  "phone": { "type": "string", "example": "+91 98401 23456" },
                  "otp": { "type": "string", "example": "1234" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OTP verified, returns user data and Sanctum token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "success" },
                    "token": { "type": "string", "example": "1|sanctum_token_string..." },
                    "user": { "$ref": "#/components/schemas/User" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/auth/register": {
      "post": {
        "tags": ["Authentication"],
        "summary": "Register a new user (Customer or Provider)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "email", "password", "role"],
                "properties": {
                  "name": { "type": "string", "example": "Ramesh Kumar" },
                  "email": { "type": "string", "example": "ramesh@example.com" },
                  "phone": { "type": "string", "example": "+91 98765 43210" },
                  "password": { "type": "string", "example": "password123" },
                  "role": { "type": "string", "enum": ["customer", "provider"], "example": "customer" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "User created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "success" },
                    "access_token": { "type": "string", "example": "2|sanctum_token_string..." },
                    "user": { "$ref": "#/components/schemas/User" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/auth/login": {
      "post": {
        "tags": ["Authentication"],
        "summary": "Email & Password login for SuperAdmin, Admin, Customer, or Provider",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email", "password"],
                "properties": {
                  "email": { "type": "string", "example": "customer@neednow.com" },
                  "password": { "type": "string", "example": "password123" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Login successful, returns Bearer token and user profile"
          }
        }
      }
    },
    "/auth/me": {
      "get": {
        "tags": ["Authentication"],
        "summary": "Get authenticated user profile",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": {
            "description": "Authenticated user profile data"
          }
        }
      }
    },
    "/auth/logout": {
      "post": {
        "tags": ["Authentication"],
        "summary": "Revoke current authentication token",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": { "description": "Logged out successfully" }
        }
      }
    },
    "/categories": {
      "get": {
        "tags": ["Categories"],
        "summary": "List all active service categories",
        "responses": {
          "200": {
            "description": "List of categories with icons and descriptions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "success" },
                    "categories": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/search/suggestions": {
      "get": {
        "tags": ["Search & Suggestions"],
        "summary": "Get AI suggestions, recent searches, and popular searches",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search keyword query" }
        ],
        "responses": {
          "200": { "description": "AI suggestions and search keywords" }
        }
      }
    },
    "/search": {
      "get": {
        "tags": ["Search & Suggestions"],
        "summary": "Search across categories, services, and local providers",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query keyword" }
        ],
        "responses": {
          "200": { "description": "Search results matching query" }
        }
      }
    },
    "/emergency-services": {
      "get": {
        "tags": ["Emergency 24x7 Services"],
        "summary": "Get list of available 24x7 emergency services and 24x7 hotline",
        "responses": {
          "200": { "description": "24x7 emergency options and helpline" }
        }
      }
    },
    "/emergency-services/request": {
      "post": {
        "tags": ["Emergency 24x7 Services"],
        "summary": "Urgent dispatch request for 24x7 emergency service",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["service_type"],
                "properties": {
                  "service_type": { "type": "string", "example": "Plumber (Emergency)" },
                  "location": { "type": "string", "example": "Anna Nagar, Chennai" },
                  "notes": { "type": "string", "example": "Severe water pipe burst under sink" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Emergency service dispatched" }
        }
      }
    },
    "/needs": {
      "get": {
        "tags": ["Phase 3 - Need Creation"],
        "summary": "List all customer posted service needs (Latest first)",
        "responses": {
          "200": {
            "description": "List of needs with received offers count",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "success" },
                    "count": { "type": "integer", "example": 5 },
                    "needs": { "type": "array", "items": { "$ref": "#/components/schemas/Need" } }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Phase 3 - Need Creation"],
        "summary": "Post a new Service Need (Screen 15: Review & Submit). Automatically generates Phase 4 matching offers.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["service_title"],
                "properties": {
                  "service_title": { "type": "string", "example": "My AC is not cooling. Need someone to check and fix it." },
                  "category": { "type": "string", "example": "AC Service & Repair" },
                  "description": { "type": "string", "example": "AC not cooling properly and making a strange buzzing sound." },
                  "more_details": { "type": "string", "example": "1.5 Ton Split AC, brand Voltas" },
                  "when_needed": { "type": "string", "enum": ["ASAP", "Within 24 hours", "Custom Date & Time"], "example": "ASAP" },
                  "photos": { "type": "array", "items": { "type": "string" }, "example": [] },
                  "voice_duration": { "type": "string", "example": "18s" },
                  "voice_note": { "type": "string", "example": "" },
                  "location": { "type": "string", "example": "Anna Nagar, Chennai - 600040" },
                  "address": { "type": "string", "example": "Door No. 12, 4th Main Road" },
                  "urgency": { "type": "string", "example": "normal" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Service need posted and Phase 4 offers generated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "success" },
                    "message": { "type": "string", "example": "Service request posted successfully! Local providers matching now." },
                    "need": { "$ref": "#/components/schemas/Need" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/needs/{id}": {
      "get": {
        "tags": ["Phase 3 - Need Creation"],
        "summary": "Get details of a specific service need by ID",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "Need details" },
          "404": { "description": "Need not found" }
        }
      }
    },
    "/needs/{id}/nearby-providers": {
      "get": {
        "tags": ["Phase 4 - Provider Matching"],
        "summary": "Screen 17: Get Nearby Matching Providers for a Need (12 professionals found)",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": {
            "description": "List of nearby verified professionals with distance, rating, price range, and availability status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "success" },
                    "need_id": { "type": "integer", "example": 1 },
                    "total_found": { "type": "integer", "example": 12 },
                    "professionals_found_text": { "type": "string", "example": "12 professionals found" },
                    "providers": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/needs/{id}/offers": {
      "get": {
        "tags": ["Phase 4 - Provider Matching"],
        "summary": "Screen 18 & 19: Get Received Competitive Offers for a Need (Compare Offers)",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": {
            "description": "List of 4 received offers including Recommended provider, prices, warranty, response times",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "success" },
                    "need_id": { "type": "integer", "example": 1 },
                    "offers_count": { "type": "integer", "example": 4 },
                    "title": { "type": "string", "example": "Offers Received" },
                    "subtitle": { "type": "string", "example": "You have received 4 offers" },
                    "offers": { "type": "array", "items": { "$ref": "#/components/schemas/NeedOffer" } }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/needs/{id}/accept-offer": {
      "post": {
        "tags": ["Phase 4 - Provider Matching"],
        "summary": "Screen 19: Choose Best Offer, confirm service booking, and assign job to provider",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["offer_id"],
                "properties": {
                  "offer_id": { "type": "integer", "example": 1 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Offer accepted, booking confirmed, and provider assigned",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "success" },
                    "message": { "type": "string", "example": "Offer accepted successfully! Cool Care Solutions has been assigned to your service." },
                    "booking": {
                      "type": "object",
                      "properties": {
                        "job_code": { "type": "string", "example": "NN-CONF-20261018-0001" },
                        "provider_name": { "type": "string", "example": "Cool Care Solutions" },
                        "provider_phone": { "type": "string", "example": "+91 98765 43210" },
                        "accepted_price": { "type": "number", "example": 450.0 },
                        "formatted_price": { "type": "string", "example": "₹450" },
                        "estimated_time": { "type": "string", "example": "1-3 hours" },
                        "warranty": { "type": "string", "example": "30 days" },
                        "status": { "type": "string", "example": "Confirmed" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/providers": {
      "get": {
        "tags": ["Providers Directory & KYC"],
        "summary": "List all service providers with filters",
        "parameters": [
          { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Filter by service category" },
          { "name": "is_available", "in": "query", "schema": { "type": "boolean" }, "description": "Filter by online/available status" },
          { "name": "min_rating", "in": "query", "schema": { "type": "number" }, "description": "Filter by minimum rating (e.g. 4.5)" }
        ],
        "responses": {
          "200": { "description": "Paginated list of providers" }
        }
      }
    },
    "/providers/{id}": {
      "get": {
        "tags": ["Providers Directory & KYC"],
        "summary": "Get specific provider profile by ID",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "Provider details and ratings" },
          "404": { "description": "Provider not found" }
        }
      }
    },
    "/provider/kyc/submit": {
      "post": {
        "tags": ["Providers Directory & KYC"],
        "summary": "Submit 6-Step Registration & KYC payload from Provider App",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string", "example": "Ramesh Kumar" },
                  "phone": { "type": "string", "example": "+91 98765 43210" },
                  "dob": { "type": "string", "example": "15 - 08 - 1992" },
                  "gender": { "type": "string", "example": "Male" },
                  "experience_years": { "type": "integer", "example": 5 },
                  "primary_profession": { "type": "string", "example": "AC Repair" },
                  "service_area": { "type": "string", "example": "Chennai, Tamil Nadu" },
                  "aadhaar_card": { "type": "string", "example": "Aadhaar_Front.jpg" },
                  "pan_card": { "type": "string", "example": "PAN_Card.jpg" },
                  "bank_name": { "type": "string", "example": "State Bank of India" },
                  "account_number": { "type": "string", "example": "1234 5678 9012" },
                  "ifsc_code": { "type": "string", "example": "SBIN0001234" },
                  "hourly_rate": { "type": "number", "example": 350.0 }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "KYC submitted and set under review" }
        }
      }
    },
    "/provider/kyc-status": {
      "get": {
        "tags": ["Providers Directory & KYC"],
        "summary": "Check current KYC verification status",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": { "description": "KYC approval status (approved / under_review)" }
        }
      }
    },
    "/provider/dashboard": {
      "get": {
        "tags": ["Provider Dashboard & Jobs"],
        "summary": "Provider home dashboard metrics, availability status, and earnings overview",
        "responses": {
          "200": { "description": "Provider dashboard data" }
        }
      }
    },
    "/provider/toggle-availability": {
      "post": {
        "tags": ["Provider Dashboard & Jobs"],
        "summary": "Toggle provider online / offline availability switch",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "is_available": { "type": "boolean", "example": true }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Availability toggled successfully" }
        }
      }
    },
    "/provider/jobs/today": {
      "get": {
        "tags": ["Provider Dashboard & Jobs"],
        "summary": "Get today's jobs dispatched to this provider",
        "responses": {
          "200": { "description": "List of jobs for today" }
        }
      }
    },
    "/provider/jobs/{id}": {
      "get": {
        "tags": ["Provider Dashboard & Jobs"],
        "summary": "Get full details, price breakdown, and customer info for a job",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "Job details" }
        }
      }
    },
    "/provider/jobs/{id}/status": {
      "post": {
        "tags": ["Provider Dashboard & Jobs"],
        "summary": "Update job status (Upcoming -> In Progress -> Completed)",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["status"],
                "properties": {
                  "status": { "type": "string", "enum": ["Upcoming", "In Progress", "Completed", "Cancelled"], "example": "Completed" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Job status updated" }
        }
      }
    },
    "/provider/earnings/today": {
      "get": {
        "tags": ["Provider Dashboard & Jobs"],
        "summary": "Get today's earnings and completed jobs total",
        "responses": {
          "200": { "description": "Today's earnings breakdown" }
        }
      }
    },
    "/provider/performance": {
      "get": {
        "tags": ["Provider Dashboard & Jobs"],
        "summary": "Provider rating, total reviews, on-time rate, and completion metrics",
        "responses": {
          "200": { "description": "Performance report" }
        }
      }
    },
    "/users": {
      "get": {
        "tags": ["Admin & SuperAdmin"],
        "summary": "List all registered users across all 4 roles",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "role", "in": "query", "schema": { "type": "string", "enum": ["superadmin", "admin", "customer", "provider"] } },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["active", "inactive", "suspended"] } }
        ],
        "responses": {
          "200": { "description": "List of users" }
        }
      }
    },
    "/users/{id}/status": {
      "patch": {
        "tags": ["Admin & SuperAdmin"],
        "summary": "Update user account status (SuperAdmin / Admin control)",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["status"],
                "properties": {
                  "status": { "type": "string", "enum": ["active", "inactive", "suspended"], "example": "active" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "User status updated" }
        }
      }
    },
    "/providers/{id}/verify": {
      "patch": {
        "tags": ["Admin & SuperAdmin"],
        "summary": "Toggle KYC verification status for a provider",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "Provider verification toggled" }
        }
      }
    }
  }
}