{ "openapi": "3.0.0", "info": { "title": "Mpangaji Dashboard & Mobile API", "description": "A robust Laravel API for dashboard and mobile app with user management, authentication, and role-based permissions. All protected endpoints require both JWT Bearer token and API Key authentication. Public endpoints (login, registration, property viewing, reviews) do not require authentication.", "version": "1.0.0", "contact": { "name": "API Support", "email": "support@example.com" } }, "servers": [ { "url": "http://localhost:8000/api/v1", "description": "Development server" } ], "security": [ { "bearerAuth": [], "apiKeyAuth": [] } ], "paths": { "/auth/login": { "post": { "operationId": "loginUser", "tags": ["Authentication"], "summary": "User login", "description": "Authenticate user and return access token. Returns specific error messages for different scenarios: email not found, incorrect password, or account status issues.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/auth/logout": { "post": { "operationId": "logoutUser", "tags": ["Authentication"], "summary": "Logout user", "description": "Logout user from all devices", "responses": { "200": { "description": "Logout successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/logout/{tokenId}": { "post": { "operationId": "logoutFromDevice", "tags": ["Authentication"], "summary": "Logout from specific device", "description": "Logout user from a specific device using token ID", "parameters": [ { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Token ID to logout from" } ], "responses": { "200": { "description": "Logout from device successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/profile": { "get": { "operationId": "getUserProfile", "tags": ["Authentication"], "summary": "Get user profile", "description": "Get current authenticated user profile with permissions and roles", "responses": { "200": { "description": "Profile retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/users/register/tenant": { "post": { "operationId": "registerTenant", "tags": ["User Management"], "summary": "Register tenant", "description": "Register a new tenant account (public endpoint). The role_type is automatically set to 2 (tenant) and the account is immediately active. No role_type field is required in the request body.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantRegistrationRequest" } } } }, "responses": { "201": { "description": "Tenant account created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/users/register/landlord": { "post": { "operationId": "registerLandlord", "tags": ["User Management"], "summary": "Register landlord", "description": "Register a new landlord account (public endpoint). The role_type is automatically set to 1 (landlord) and the account status is set to inactive, requiring admin approval before activation. No role_type field is required in the request body.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandlordRegistrationRequest" } } } }, "responses": { "201": { "description": "Landlord account created successfully. Please wait for admin approval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/users": { "get": { "operationId": "getUsers", "tags": ["User Management"], "summary": "Get users with pagination", "description": "Get list of users with pagination and filtering (admin only)", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "Page number" }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 }, "description": "Number of users per page" }, { "name": "role_type", "in": "query", "schema": { "type": "integer", "enum": [1, 2, 3], "description": "1=landlord, 2=tenant, 3=admin" }, "description": "Filter by role type" }, { "name": "status", "in": "query", "schema": { "type": "integer", "enum": [1, 2, 3], "description": "1=ACTIVE, 2=INACTIVE, 3=SUSPENDED" }, "description": "Filter by status" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search by name, email, or phone" }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "default": "created_at" }, "description": "Sort by field" }, { "name": "sort_order", "in": "query", "schema": { "type": "integer", "enum": [1, 2], "description": "1=asc, 2=desc", "default": 2 }, "description": "Sort order" } ], "responses": { "200": { "description": "Users retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersListResponse" } } } }, "403": { "description": "Forbidden - Admin access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createUser", "tags": ["User Management"], "summary": "Create user (Admin only)", "description": "Create a new user account with specified role type (admin only). Supports all role types: 1=landlord, 2=tenant, 3=admin.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCreationRequest" } } } }, "responses": { "201": { "description": "User created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "403": { "description": "Forbidden - Admin access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/users/{id}": { "get": { "operationId": "getUserDetails", "tags": ["User Management"], "summary": "Get user details", "description": "Get specific user details by ID (admin only)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "User ID" } ], "responses": { "200": { "description": "User details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "403": { "description": "Forbidden - Admin access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "operationId": "updateUser", "tags": ["User Management"], "summary": "Update user", "description": "Update user information (admin only)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "User ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdateRequest" } } } }, "responses": { "200": { "description": "User updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "403": { "description": "Forbidden - Admin access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/users/pending-landlords": { "get": { "operationId": "getPendingLandlords", "tags": ["User Management"], "summary": "Get pending landlords", "description": "Get list of landlords pending approval (admin only)", "responses": { "200": { "description": "Pending landlords retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingLandlordsResponse" } } } }, "403": { "description": "Forbidden - Admin access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/users/{userId}/approve": { "post": { "operationId": "approveLandlord", "tags": ["User Management"], "summary": "Approve landlord", "description": "Approve a landlord account (admin only)", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "User ID to approve" } ], "responses": { "200": { "description": "Landlord approved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Admin access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/users/{userId}/reject": { "post": { "operationId": "rejectLandlord", "tags": ["User Management"], "summary": "Reject landlord", "description": "Reject a landlord account (admin only)", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "User ID to reject" } ], "responses": { "200": { "description": "Landlord rejected successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Admin access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/users/profile": { "put": { "operationId": "updateProfile", "tags": ["User Management"], "summary": "Update user profile", "description": "Update current user's profile information", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileUpdateRequest" } } } }, "responses": { "200": { "description": "Profile updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/user": { "get": { "operationId": "getCurrentUser", "tags": ["User Management"], "summary": "Get current user", "description": "Get current authenticated user information", "responses": { "200": { "description": "User information retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/properties": { "get": { "operationId": "getProperties", "tags": ["Property Management"], "summary": "Get properties with filtering", "description": "Get list of available and verified properties with filtering options (public endpoint)", "security": [], "parameters": [ { "name": "property_type", "in": "query", "schema": { "type": "integer", "enum": [1, 2, 3, 4, 5], "description": "1=house, 2=apartment, 3=room, 4=hostel, 5=office" }, "description": "Filter by property type" }, { "name": "min_price", "in": "query", "schema": { "type": "number", "format": "float" }, "description": "Minimum monthly rent" }, { "name": "max_price", "in": "query", "schema": { "type": "number", "format": "float" }, "description": "Maximum monthly rent" }, { "name": "bedrooms", "in": "query", "schema": { "type": "integer" }, "description": "Number of bedrooms" }, { "name": "bathrooms", "in": "query", "schema": { "type": "integer" }, "description": "Number of bathrooms" }, { "name": "is_furnished", "in": "query", "schema": { "type": "boolean" }, "description": "Furnished status" }, { "name": "address", "in": "query", "schema": { "type": "string" }, "description": "Search by address" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search by title, description, or address" }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "default": "created_at" }, "description": "Sort by field" }, { "name": "sort_order", "in": "query", "schema": { "type": "integer", "enum": [1, 2], "description": "1=asc, 2=desc", "default": 2 }, "description": "Sort order" }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "Page number" }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 }, "description": "Number of properties per page" } ], "responses": { "200": { "description": "Properties retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertiesListResponse" } } } } } }, "post": { "operationId": "createProperty", "tags": ["Property Management"], "summary": "Create property", "description": "Create a new property (landlord only)", "security": [{"bearerAuth": [], "apiKeyAuth": []}], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyRequest" } } } }, "responses": { "201": { "description": "Property created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Landlord role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/properties/{id}": { "get": { "operationId": "getProperty", "tags": ["Property Management"], "summary": "Get property details", "description": "Get single property details with images and landlord info (public endpoint)", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Property ID" } ], "responses": { "200": { "description": "Property details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyResponse" } } } }, "404": { "description": "Property not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "operationId": "updateProperty", "tags": ["Property Management"], "summary": "Update property", "description": "Update property information (landlord only)", "security": [{"bearerAuth": [], "apiKeyAuth": []}], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Property ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyRequest" } } } }, "responses": { "200": { "description": "Property updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Can only update own properties", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Property not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } }, "delete": { "operationId": "deleteProperty", "tags": ["Property Management"], "summary": "Delete property", "description": "Delete property (landlord only)", "security": [{"bearerAuth": [], "apiKeyAuth": []}], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Property ID" } ], "responses": { "200": { "description": "Property deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Can only delete own properties", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Property not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/properties/my": { "get": { "operationId": "getMyProperties", "tags": ["Property Management"], "summary": "Get landlord's properties", "description": "Get list of landlord's own properties. By default, returns ALL properties for the landlord regardless of status or verification. Optional filters can be applied to narrow down results.", "security": [{"bearerAuth": [], "apiKeyAuth": []}], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "integer", "enum": [1, 2, 3, 4], "description": "1=available, 2=occupied, 3=pending, 4=maintenance" }, "description": "Filter by status (optional - shows all statuses by default)" }, { "name": "property_type", "in": "query", "required": false, "schema": { "type": "integer", "enum": [1, 2, 3, 4, 5], "description": "1=house, 2=apartment, 3=room, 4=hostel, 5=office" }, "description": "Filter by property type (optional - shows all types by default)" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search by title, description, or address (optional)" }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "created_at" }, "description": "Sort by field (default: created_at)" }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "integer", "enum": [1, 2], "description": "1=asc, 2=desc", "default": 2 }, "description": "Sort order (default: desc)" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "Page number (default: 1)" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 }, "description": "Number of properties per page (default: 15)" } ], "responses": { "200": { "description": "Properties retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertiesListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Landlord role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/properties": { "get": { "operationId": "getAllPropertiesForAdmin", "tags": ["Admin Property Management"], "summary": "Get all properties for admin", "description": "Get all properties with comprehensive filtering options for administrators. Can view all properties regardless of status or verification.", "security": [{"bearerAuth": [], "apiKeyAuth": []}], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "integer", "enum": [1, 2, 3, 4], "description": "1=available, 2=occupied, 3=pending, 4=maintenance" }, "description": "Filter by property status (optional)" }, { "name": "property_type", "in": "query", "required": false, "schema": { "type": "integer", "enum": [1, 2, 3, 4, 5], "description": "1=house, 2=apartment, 3=room, 4=hostel, 5=office" }, "description": "Filter by property type (optional)" }, { "name": "is_verified", "in": "query", "required": false, "schema": { "type": "integer", "enum": [0, 1], "description": "0=false, 1=true" }, "description": "Filter by verification status (optional - 0=unverified, 1=verified)" }, { "name": "landlord_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filter by specific landlord ID (optional)" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search by property title, description, address, or landlord name/email (optional)" }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "created_at" }, "description": "Sort by field (default: created_at)" }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "integer", "enum": [1, 2], "description": "1=asc, 2=desc", "default": 2 }, "description": "Sort order (default: desc)" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "Page number (default: 1)" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 }, "description": "Number of properties per page (default: 15)" } ], "responses": { "200": { "description": "Properties retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertiesListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Admin role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/properties/{id}/verify": { "put": { "operationId": "verifyProperty", "tags": ["Admin Property Management"], "summary": "Verify property", "description": "Mark property as verified and create a verification record (admin only). The property's is_verified flag is set to true and a PropertyVerification record is created with the provided details.", "security": [{"bearerAuth": [], "apiKeyAuth": []}], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Property ID" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyPropertyRequest" } } } }, "responses": { "200": { "description": "Property verified successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyVerificationResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Admin role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Property not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/properties/{id}/status": { "put": { "operationId": "updatePropertyStatus", "tags": ["Admin Property Management"], "summary": "Update property status", "description": "Change property status (admin only)", "security": [{"bearerAuth": [], "apiKeyAuth": []}], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Property ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["status"], "properties": { "status": { "type": "integer", "enum": [1, 2, 3, 4], "description": "1=available, 2=occupied, 3=pending, 4=maintenance", "example": 1 } } } } } }, "responses": { "200": { "description": "Property status updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Admin role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Property not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/bookings": { "post": { "operationId": "createBooking", "tags": ["Booking Management", "Disabled"], "summary": "Create a new booking", "description": "Create a new booking request (tenant only)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBookingRequest" } } } }, "responses": { "201": { "description": "Booking created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/bookings/my": { "get": { "operationId": "getMyBookings", "tags": ["Booking Management", "Disabled"], "summary": "Get tenant's bookings", "description": "Get all bookings for the authenticated tenant", "parameters": [ { "name": "status", "in": "query", "description": "Filter by booking status", "required": false, "schema": { "type": "integer", "enum": [1, 2, 3, 4, 5], "description": "1=pending, 2=approved, 3=rejected, 4=cancelled, 5=completed" } }, { "name": "property_id", "in": "query", "description": "Filter by property ID", "required": false, "schema": { "type": "integer" } }, { "name": "check_in_from", "in": "query", "description": "Filter by check-in date from", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "check_in_to", "in": "query", "description": "Filter by check-in date to", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Bookings retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingsListResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/bookings/{id}": { "get": { "operationId": "getBooking", "tags": ["Booking Management", "Disabled"], "summary": "Get booking details", "description": "Get details of a specific booking", "parameters": [ { "name": "id", "in": "path", "description": "Booking ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Booking retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResponse" } } } }, "404": { "description": "Booking not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/bookings/{id}/cancel": { "post": { "operationId": "cancelBooking", "tags": ["Booking Management", "Disabled"], "summary": "Cancel a booking", "description": "Cancel a pending booking (tenant only)", "parameters": [ { "name": "id", "in": "path", "description": "Booking ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Booking cancelled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResponse" } } } }, "404": { "description": "Booking not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Cannot cancel booking", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/bookings/landlord/my": { "get": { "operationId": "getLandlordBookings", "tags": ["Landlord Booking Management"], "summary": "Get landlord's bookings", "description": "Get all bookings for the authenticated landlord", "parameters": [ { "name": "status", "in": "query", "description": "Filter by booking status", "required": false, "schema": { "type": "integer", "enum": [1, 2, 3, 4, 5], "description": "1=pending, 2=approved, 3=rejected, 4=cancelled, 5=completed" } }, { "name": "property_id", "in": "query", "description": "Filter by property ID", "required": false, "schema": { "type": "integer" } }, { "name": "tenant_id", "in": "query", "description": "Filter by tenant ID", "required": false, "schema": { "type": "integer" } }, { "name": "check_in_from", "in": "query", "description": "Filter by check-in date from", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "check_in_to", "in": "query", "description": "Filter by check-in date to", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Bookings retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingsListResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/bookings/landlord/{id}": { "get": { "operationId": "getLandlordBooking", "tags": ["Landlord Booking Management"], "summary": "Get landlord's booking details", "description": "Get details of a specific booking for landlord", "parameters": [ { "name": "id", "in": "path", "description": "Booking ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Booking retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResponse" } } } }, "404": { "description": "Booking not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/bookings/{id}/approve": { "post": { "operationId": "approveBooking", "tags": ["Landlord Booking Management"], "summary": "Approve a booking", "description": "Approve a pending booking (landlord only)", "parameters": [ { "name": "id", "in": "path", "description": "Booking ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Booking approved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResponse" } } } }, "404": { "description": "Booking not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Cannot approve booking", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/bookings/{id}/reject": { "post": { "operationId": "rejectBooking", "tags": ["Landlord Booking Management"], "summary": "Reject a booking", "description": "Reject a pending booking (landlord only)", "parameters": [ { "name": "id", "in": "path", "description": "Booking ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Booking rejected successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResponse" } } } }, "404": { "description": "Booking not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Cannot reject booking", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/bookings/{id}/complete": { "post": { "operationId": "completeBooking", "tags": ["Landlord Booking Management"], "summary": "Complete a booking", "description": "Mark a booking as completed (landlord only)", "parameters": [ { "name": "id", "in": "path", "description": "Booking ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Booking completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResponse" } } } }, "404": { "description": "Booking not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Cannot complete booking", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/bookings": { "get": { "operationId": "getAllBookings", "tags": ["Admin Booking Management"], "summary": "Get all bookings", "description": "Get all bookings with filtering (admin only)", "parameters": [ { "name": "status", "in": "query", "description": "Filter by booking status", "required": false, "schema": { "type": "integer", "enum": [1, 2, 3, 4, 5], "description": "1=pending, 2=approved, 3=rejected, 4=cancelled, 5=completed" } }, { "name": "property_id", "in": "query", "description": "Filter by property ID", "required": false, "schema": { "type": "integer" } }, { "name": "tenant_id", "in": "query", "description": "Filter by tenant ID", "required": false, "schema": { "type": "integer" } }, { "name": "landlord_id", "in": "query", "description": "Filter by landlord ID", "required": false, "schema": { "type": "integer" } }, { "name": "check_in_from", "in": "query", "description": "Filter by check-in date from", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "check_in_to", "in": "query", "description": "Filter by check-in date to", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Bookings retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingsListResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/bookings/{id}": { "get": { "operationId": "getAdminBooking", "tags": ["Admin Booking Management"], "summary": "Get booking details (admin)", "description": "Get details of a specific booking (admin only)", "parameters": [ { "name": "id", "in": "path", "description": "Booking ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Booking retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResponse" } } } }, "404": { "description": "Booking not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/bookings/{id}/status": { "put": { "operationId": "updateBookingStatus", "tags": ["Admin Booking Management"], "summary": "Update booking status", "description": "Update booking status (admin only)", "parameters": [ { "name": "id", "in": "path", "description": "Booking ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBookingStatusRequest" } } } }, "responses": { "200": { "description": "Booking status updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResponse" } } } }, "404": { "description": "Booking not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Invalid status or cannot update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/payments": { "post": { "operationId": "createPayment", "tags": ["Payment Management", "Disabled"], "summary": "Create a new payment", "description": "Create a new payment request (tenant only)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentRequest" } } } }, "responses": { "201": { "description": "Payment created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/payments/my": { "get": { "operationId": "getMyPayments", "tags": ["Payment Management", "Disabled"], "summary": "Get tenant's payments", "description": "Get all payments for the authenticated tenant", "parameters": [ { "name": "status", "in": "query", "description": "Filter by payment status", "required": false, "schema": { "type": "integer", "enum": [1, 2, 3, 4], "description": "1=pending, 2=completed, 3=failed, 4=refunded" } }, { "name": "booking_id", "in": "query", "description": "Filter by booking ID", "required": false, "schema": { "type": "integer" } }, { "name": "payment_type", "in": "query", "description": "Filter by payment type", "required": false, "schema": { "type": "integer", "enum": [1, 2, 3, 4], "description": "1=rent, 2=deposit, 3=partial, 4=recurring" } }, { "name": "payment_method", "in": "query", "description": "Filter by payment method", "required": false, "schema": { "type": "integer", "enum": [1, 2, 3], "description": "1=mobile_money, 2=bank, 3=cash" } }, { "name": "due_date_from", "in": "query", "description": "Filter by due date from", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "due_date_to", "in": "query", "description": "Filter by due date to", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Payments retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentsListResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/payments/overdue": { "get": { "operationId": "getOverduePayments", "tags": ["Payment Management", "Disabled"], "summary": "Get overdue payments", "description": "Get all overdue payments for the authenticated user", "responses": { "200": { "description": "Overdue payments retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentResponse" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/payments/due-today": { "get": { "operationId": "getDueTodayPayments", "tags": ["Payment Management", "Disabled"], "summary": "Get payments due today", "description": "Get all payments due today for the authenticated user", "responses": { "200": { "description": "Payments due today retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentResponse" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/payments/{id}": { "get": { "operationId": "getPayment", "tags": ["Payment Management", "Disabled"], "summary": "Get payment details", "description": "Get details of a specific payment", "parameters": [ { "name": "id", "in": "path", "description": "Payment ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payment retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/payments/landlord/my": { "get": { "operationId": "getLandlordPayments", "tags": ["Landlord Payment Management"], "summary": "Get landlord's payments", "description": "Get all payments for the authenticated landlord", "parameters": [ { "name": "status", "in": "query", "description": "Filter by payment status", "required": false, "schema": { "type": "integer", "enum": [1, 2, 3, 4], "description": "1=pending, 2=completed, 3=failed, 4=refunded" } }, { "name": "booking_id", "in": "query", "description": "Filter by booking ID", "required": false, "schema": { "type": "integer" } }, { "name": "tenant_id", "in": "query", "description": "Filter by tenant ID", "required": false, "schema": { "type": "integer" } }, { "name": "payment_type", "in": "query", "description": "Filter by payment type", "required": false, "schema": { "type": "integer", "enum": [1, 2, 3, 4], "description": "1=rent, 2=deposit, 3=partial, 4=recurring" } }, { "name": "payment_method", "in": "query", "description": "Filter by payment method", "required": false, "schema": { "type": "integer", "enum": [1, 2, 3], "description": "1=mobile_money, 2=bank, 3=cash" } }, { "name": "due_date_from", "in": "query", "description": "Filter by due date from", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "due_date_to", "in": "query", "description": "Filter by due date to", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Payments retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentsListResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/payments/landlord/overdue": { "get": { "operationId": "getLandlordOverduePayments", "tags": ["Landlord Payment Management"], "summary": "Get landlord's overdue payments", "description": "Get all overdue payments for the authenticated landlord", "responses": { "200": { "description": "Overdue payments retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentResponse" } } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/payments/landlord/due-today": { "get": { "operationId": "getLandlordDueTodayPayments", "tags": ["Landlord Payment Management"], "summary": "Get landlord's payments due today", "description": "Get all payments due today for the authenticated landlord", "responses": { "200": { "description": "Payments due today retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentResponse" } } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/payments/landlord/{id}": { "get": { "operationId": "getLandlordPayment", "tags": ["Landlord Payment Management"], "summary": "Get landlord's payment details", "description": "Get details of a specific payment for landlord", "parameters": [ { "name": "id", "in": "path", "description": "Payment ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payment retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/payments/{id}/confirm": { "post": { "operationId": "confirmPayment", "tags": ["Landlord Payment Management"], "summary": "Confirm a payment", "description": "Confirm a pending payment (landlord only)", "parameters": [ { "name": "id", "in": "path", "description": "Payment ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payment confirmed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Cannot confirm payment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/payments/{id}/reject": { "post": { "operationId": "rejectPayment", "tags": ["Landlord Payment Management"], "summary": "Reject a payment", "description": "Reject a pending payment (landlord only)", "parameters": [ { "name": "id", "in": "path", "description": "Payment ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payment rejected successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Cannot reject payment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/payments": { "get": { "operationId": "getAllPayments", "tags": ["Admin Payment Management"], "summary": "Get all payments", "description": "Get all payments with filtering (admin only)", "parameters": [ { "name": "status", "in": "query", "description": "Filter by payment status", "required": false, "schema": { "type": "integer", "enum": [1, 2, 3, 4], "description": "1=pending, 2=completed, 3=failed, 4=refunded" } }, { "name": "booking_id", "in": "query", "description": "Filter by booking ID", "required": false, "schema": { "type": "integer" } }, { "name": "tenant_id", "in": "query", "description": "Filter by tenant ID", "required": false, "schema": { "type": "integer" } }, { "name": "landlord_id", "in": "query", "description": "Filter by landlord ID", "required": false, "schema": { "type": "integer" } }, { "name": "payment_type", "in": "query", "description": "Filter by payment type", "required": false, "schema": { "type": "integer", "enum": [1, 2, 3, 4], "description": "1=rent, 2=deposit, 3=partial, 4=recurring" } }, { "name": "payment_method", "in": "query", "description": "Filter by payment method", "required": false, "schema": { "type": "integer", "enum": [1, 2, 3], "description": "1=mobile_money, 2=bank, 3=cash" } }, { "name": "due_date_from", "in": "query", "description": "Filter by due date from", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "due_date_to", "in": "query", "description": "Filter by due date to", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Payments retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentsListResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/payments/overdue": { "get": { "operationId": "getAdminOverduePayments", "tags": ["Admin Payment Management"], "summary": "Get overdue payments (admin)", "description": "Get all overdue payments (admin only)", "responses": { "200": { "description": "Overdue payments retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentResponse" } } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/payments/due-today": { "get": { "operationId": "getAdminDueTodayPayments", "tags": ["Admin Payment Management"], "summary": "Get payments due today (admin)", "description": "Get all payments due today (admin only)", "responses": { "200": { "description": "Payments due today retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentResponse" } } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/payments/{id}": { "get": { "operationId": "getAdminPayment", "tags": ["Admin Payment Management"], "summary": "Get payment details (admin)", "description": "Get details of a specific payment (admin only)", "parameters": [ { "name": "id", "in": "path", "description": "Payment ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payment retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/payments/{id}/status": { "put": { "operationId": "updatePaymentStatus", "tags": ["Admin Payment Management"], "summary": "Update payment status", "description": "Update payment status (admin only)", "parameters": [ { "name": "id", "in": "path", "description": "Payment ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePaymentStatusRequest" } } } }, "responses": { "200": { "description": "Payment status updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Invalid status or cannot update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/messages/contact": { "post": { "operationId": "contactLandlord", "tags": ["Messages"], "summary": "Contact landlord (public, no authentication)", "description": "Send a message to a landlord without creating an account. **No authentication required** — no Bearer token or API key. Call this endpoint as an unauthenticated user. Provide your name and at least one of email or phone.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name", "receiver_id", "message"], "properties": { "name": { "type": "string", "maxLength": 255, "description": "Your name" }, "email": { "type": "string", "format": "email", "maxLength": 255, "description": "Your email (required if phone not provided)" }, "phone": { "type": "string", "maxLength": 50, "description": "Your phone number (required if email not provided)" }, "receiver_id": { "type": "integer", "description": "ID of the landlord to contact" }, "property_id": { "type": "integer", "description": "ID of the property this message relates to (optional)" }, "message": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Message content" } } } } } }, "responses": { "201": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Message sent successfully" }, "data": { "type": "object" } } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/messages/send": { "post": { "operationId": "sendMessage", "tags": ["Messages"], "summary": "Send a message", "description": "Send a message to another user, optionally related to a property", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["receiver_id", "message"], "properties": { "receiver_id": { "type": "integer", "description": "ID of the user receiving the message" }, "property_id": { "type": "integer", "description": "ID of the property this message relates to (optional)" }, "message": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Message content" } } } } } }, "responses": { "201": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Message sent successfully" }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "sender_id": { "type": "integer", "example": 1 }, "receiver_id": { "type": "integer", "example": 2 }, "property_id": { "type": "integer", "example": 1, "nullable": true }, "message": { "type": "string", "example": "Hello, is this property still available?" }, "is_read": { "type": "boolean", "example": false }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/messages/conversations": { "get": { "operationId": "getConversations", "tags": ["Messages"], "summary": "Get user conversations", "description": "Get list of conversations for the authenticated user", "parameters": [ { "name": "per_page", "in": "query", "description": "Number of conversations per page", "required": false, "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Conversations retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Conversations retrieved successfully" }, "data": { "type": "object", "properties": { "conversations": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "integer", "example": 2 }, "user_name": { "type": "string", "example": "John Doe" }, "last_message": { "type": "string", "example": "Thank you for your interest!" }, "last_message_time": { "type": "string", "format": "date-time" }, "unread_count": { "type": "integer", "example": 2 }, "property_id": { "type": "integer", "example": 1, "nullable": true } } } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } } } }, "/messages/conversation/{userId}": { "get": { "operationId": "getConversation", "tags": ["Messages"], "summary": "Get conversation with specific user", "description": "Get conversation messages between authenticated user and specified user", "parameters": [ { "name": "userId", "in": "path", "description": "User ID to get conversation with", "required": true, "schema": { "type": "integer" } }, { "name": "property_id", "in": "query", "description": "Filter messages by property ID", "required": false, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "Number of messages per page", "required": false, "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Conversation retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Conversation retrieved successfully" }, "data": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "sender_id": { "type": "integer", "example": 1 }, "receiver_id": { "type": "integer", "example": 2 }, "property_id": { "type": "integer", "example": 1, "nullable": true }, "message": { "type": "string", "example": "Hello, is this property still available?" }, "is_read": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time" }, "sender": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Jane Doe" } } } } } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } } } }, "/messages/mark-read": { "put": { "operationId": "markMessagesAsRead", "tags": ["Messages"], "summary": "Mark messages as read", "description": "Mark messages as read for the authenticated user", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "sender_id": { "type": "integer", "description": "Mark messages from specific sender as read" }, "property_id": { "type": "integer", "description": "Mark messages related to specific property as read" } } } } } }, "responses": { "200": { "description": "Messages marked as read successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Messages marked as read successfully" }, "data": { "type": "object", "properties": { "marked_count": { "type": "integer", "example": 5 } } } } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/messages/unread-count": { "get": { "operationId": "getUnreadMessageCount", "tags": ["Messages"], "summary": "Get unread message count", "description": "Get count of unread messages for the authenticated user", "responses": { "200": { "description": "Unread count retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Unread count retrieved successfully" }, "data": { "type": "object", "properties": { "unread_count": { "type": "integer", "example": 3 } } } } } } } } } } }, "/messages/statistics": { "get": { "operationId": "getMessageStatistics", "tags": ["Messages"], "summary": "Get message statistics", "description": "Get message statistics for the authenticated user", "responses": { "200": { "description": "Message statistics retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Message statistics retrieved successfully" }, "data": { "type": "object", "properties": { "total_messages": { "type": "integer", "example": 150 }, "unread_messages": { "type": "integer", "example": 5 }, "sent_messages": { "type": "integer", "example": 75 }, "received_messages": { "type": "integer", "example": 75 }, "active_conversations": { "type": "integer", "example": 12 } } } } } } } } } } }, "/notifications": { "get": { "operationId": "getNotifications", "tags": ["Notifications"], "summary": "Get user notifications", "description": "Get notifications for the authenticated user with filtering options", "parameters": [ { "name": "type", "in": "query", "description": "Filter by notification type", "required": false, "schema": { "type": "integer", "enum": [1, 2, 3, 4], "description": "1=New Listing, 2=Booking Request, 3=Payment Reminder, 4=Message" } }, { "name": "unread_only", "in": "query", "description": "Show only unread notifications", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "recent_days", "in": "query", "description": "Show notifications from last N days", "required": false, "schema": { "type": "integer", "default": 30 } }, { "name": "per_page", "in": "query", "description": "Number of notifications per page", "required": false, "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Notifications retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Notifications retrieved successfully" }, "data": { "type": "object", "properties": { "notifications": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "user_id": { "type": "integer", "example": 1 }, "type": { "type": "integer", "example": 2, "description": "1=New Listing, 2=Booking Request, 3=Payment Reminder, 4=Message" }, "type_name": { "type": "string", "example": "Booking Request" }, "title": { "type": "string", "example": "New Booking Request" }, "body": { "type": "string", "example": "You have a new booking request for Property #123" }, "data": { "type": "object", "example": { "property_id": 123, "booking_id": 456 } }, "is_read": { "type": "boolean", "example": false }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } } } }, "/notifications/unread-count": { "get": { "operationId": "getUnreadNotificationCount", "tags": ["Notifications"], "summary": "Get unread notification count", "description": "Get count of unread notifications for the authenticated user", "responses": { "200": { "description": "Unread count retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Unread count retrieved successfully" }, "data": { "type": "object", "properties": { "unread_count": { "type": "integer", "example": 5 } } } } } } } } } } }, "/notifications/{id}/mark-read": { "put": { "operationId": "markNotificationAsRead", "tags": ["Notifications"], "summary": "Mark notification as read", "description": "Mark a specific notification as read", "parameters": [ { "name": "id", "in": "path", "description": "Notification ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Notification marked as read successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Notification marked as read successfully" }, "data": { "type": "object", "example": {} } } } } } }, "404": { "description": "Notification not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/notifications/mark-all-read": { "put": { "operationId": "markAllNotificationsAsRead", "tags": ["Notifications"], "summary": "Mark all notifications as read", "description": "Mark all notifications as read for the authenticated user", "responses": { "200": { "description": "All notifications marked as read successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "All notifications marked as read successfully" }, "data": { "type": "object", "properties": { "marked_count": { "type": "integer", "example": 10 } } } } } } } } } } }, "/notifications/{id}": { "delete": { "operationId": "deleteNotification", "tags": ["Notifications"], "summary": "Delete notification", "description": "Delete a specific notification", "parameters": [ { "name": "id", "in": "path", "description": "Notification ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Notification deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Notification deleted successfully" }, "data": { "type": "object", "example": {} } } } } } }, "404": { "description": "Notification not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/notifications/statistics": { "get": { "operationId": "getNotificationStatistics", "tags": ["Notifications"], "summary": "Get notification statistics", "description": "Get notification statistics for the authenticated user", "responses": { "200": { "description": "Notification statistics retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Notification statistics retrieved successfully" }, "data": { "type": "object", "properties": { "total_notifications": { "type": "integer", "example": 50 }, "unread_notifications": { "type": "integer", "example": 5 }, "by_type": { "type": "object", "properties": { "new_listing": { "type": "integer", "example": 10 }, "booking_request": { "type": "integer", "example": 15 }, "payment_reminder": { "type": "integer", "example": 20 }, "message": { "type": "integer", "example": 5 } } }, "recent_activity": { "type": "object", "properties": { "last_7_days": { "type": "integer", "example": 12 }, "last_30_days": { "type": "integer", "example": 35 } } } } } } } } } } } } }, "/reports": { "post": { "operationId": "createReport", "tags": ["Reports"], "summary": "Create a new report", "description": "Submit a report for a property, user, or service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["reported_item_type", "reported_item_id", "reason"], "properties": { "reported_item_type": { "type": "integer", "enum": [1, 2, 3], "description": "1=Property, 2=User, 3=Service" }, "reported_item_id": { "type": "integer", "description": "ID of the item being reported" }, "reason": { "type": "string", "maxLength": 255, "description": "Reason for the report" }, "description": { "type": "string", "maxLength": 1000, "description": "Additional details about the report" } } } } } }, "responses": { "201": { "description": "Report submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Report submitted successfully" }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "reporter_id": { "type": "integer", "example": 1 }, "reported_item_type": { "type": "integer", "example": 1 }, "reported_item_id": { "type": "integer", "example": 123 }, "reason": { "type": "string", "example": "Inappropriate content" }, "description": { "type": "string", "example": "The property listing contains misleading information" }, "status": { "type": "integer", "example": 1, "description": "1=Pending, 2=Investigating, 3=Resolved, 4=Dismissed" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/reports/my": { "get": { "operationId": "getUserReports", "tags": ["Reports"], "summary": "Get user's reports", "description": "Get reports submitted by the authenticated user", "parameters": [ { "name": "status", "in": "query", "description": "Filter by report status", "required": false, "schema": { "type": "integer", "enum": [1, 2, 3, 4], "description": "1=Pending, 2=Investigating, 3=Resolved, 4=Dismissed" } }, { "name": "item_type", "in": "query", "description": "Filter by reported item type", "required": false, "schema": { "type": "integer", "enum": [1, 2, 3], "description": "1=Property, 2=User, 3=Service" } }, { "name": "per_page", "in": "query", "description": "Number of reports per page", "required": false, "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "User reports retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "reports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "reporter_id": { "type": "integer", "example": 1 }, "reported_item_type": { "type": "integer", "example": 1 }, "reported_item_id": { "type": "integer", "example": 123 }, "reason": { "type": "string", "example": "Inappropriate content" }, "description": { "type": "string", "example": "The property listing contains misleading information" }, "status": { "type": "integer", "example": 1 }, "status_name": { "type": "string", "example": "Pending" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } } } }, "/reports/{id}": { "get": { "operationId": "getReportDetails", "tags": ["Reports"], "summary": "Get report details", "description": "Get detailed information about a specific report", "parameters": [ { "name": "id", "in": "path", "description": "Report ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Report details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "reporter_id": { "type": "integer", "example": 1 }, "reported_item_type": { "type": "integer", "example": 1 }, "reported_item_id": { "type": "integer", "example": 123 }, "reason": { "type": "string", "example": "Inappropriate content" }, "description": { "type": "string", "example": "The property listing contains misleading information" }, "status": { "type": "integer", "example": 1 }, "status_name": { "type": "string", "example": "Pending" }, "reporter": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" } } }, "reported_item": { "type": "object", "description": "Details about the reported item" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "404": { "description": "Report not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Report not found" } } } } } } } } }, "/reviews": { "post": { "operationId": "createReview", "tags": ["Reviews", "Disabled"], "summary": "Create a new review", "description": "Create a review for a property (tenant only)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["property_id", "rating"], "properties": { "property_id": { "type": "integer", "description": "ID of the property being reviewed" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Rating from 1 (very poor) to 5 (excellent)" }, "comment": { "type": "string", "maxLength": 1000, "description": "Optional comment about the property" } } } } } }, "responses": { "201": { "description": "Review created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Review created successfully" }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "property_id": { "type": "integer", "example": 123 }, "reviewer_id": { "type": "integer", "example": 1 }, "rating": { "type": "integer", "example": 5 }, "comment": { "type": "string", "example": "Great property with excellent location!" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/reviews/{id}": { "put": { "operationId": "updateReview", "tags": ["Reviews", "Disabled"], "summary": "Update a review", "description": "Update an existing review (tenant only)", "parameters": [ { "name": "id", "in": "path", "description": "Review ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rating": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Updated rating from 1 (very poor) to 5 (excellent)" }, "comment": { "type": "string", "maxLength": 1000, "description": "Updated comment about the property" } } } } } }, "responses": { "200": { "description": "Review updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Review updated successfully" }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "property_id": { "type": "integer", "example": 123 }, "reviewer_id": { "type": "integer", "example": 1 }, "rating": { "type": "integer", "example": 4 }, "comment": { "type": "string", "example": "Updated: Good property with minor issues" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "404": { "description": "Review not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Review not found" } } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } }, "delete": { "operationId": "deleteReview", "tags": ["Reviews", "Disabled"], "summary": "Delete a review", "description": "Delete a review (tenant only)", "parameters": [ { "name": "id", "in": "path", "description": "Review ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Review deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Review deleted successfully" } } } } } }, "404": { "description": "Review not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Review not found" } } } } } } } } }, "/reviews/my": { "get": { "operationId": "getUserReviews", "tags": ["Reviews", "Disabled"], "summary": "Get user's reviews", "description": "Get reviews created by the authenticated user (tenant only)", "parameters": [ { "name": "recent", "in": "query", "description": "Show only recent reviews", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "description": "Limit number of reviews", "required": false, "schema": { "type": "integer", "default": 10 } }, { "name": "per_page", "in": "query", "description": "Number of reviews per page", "required": false, "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "User reviews retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "reviews": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "property_id": { "type": "integer", "example": 123 }, "reviewer_id": { "type": "integer", "example": 1 }, "rating": { "type": "integer", "example": 5 }, "comment": { "type": "string", "example": "Great property with excellent location!" }, "property": { "type": "object", "properties": { "id": { "type": "integer", "example": 123 }, "title": { "type": "string", "example": "Beautiful Apartment in Downtown" }, "address": { "type": "string", "example": "123 Main St, City" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } } } }, "/reviews/property/{id}": { "get": { "operationId": "getPropertyReviews", "tags": ["Reviews"], "summary": "Get reviews for a property", "description": "Get all reviews for a specific property (public)", "security": [], "parameters": [ { "name": "id", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } }, { "name": "rating", "in": "query", "description": "Filter by specific rating", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5 } }, { "name": "recent", "in": "query", "description": "Show only recent reviews", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "description": "Limit number of reviews", "required": false, "schema": { "type": "integer", "default": 10 } }, { "name": "per_page", "in": "query", "description": "Number of reviews per page", "required": false, "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Property reviews retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "reviews": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "property_id": { "type": "integer", "example": 123 }, "reviewer_id": { "type": "integer", "example": 1 }, "rating": { "type": "integer", "example": 5 }, "comment": { "type": "string", "example": "Great property with excellent location!" }, "reviewer": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } } } }, "/reviews/property/{id}/stats": { "get": { "operationId": "getPropertyReviewStats", "tags": ["Reviews"], "summary": "Get review statistics for a property", "description": "Get aggregated review statistics for a specific property (public)", "security": [], "parameters": [ { "name": "id", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Property review statistics retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "total_reviews": { "type": "integer", "example": 25 }, "average_rating": { "type": "number", "format": "float", "example": 4.2 }, "rating_distribution": { "type": "object", "properties": { "5": { "type": "integer", "example": 10, "description": "Number of 5-star reviews" }, "4": { "type": "integer", "example": 8, "description": "Number of 4-star reviews" }, "3": { "type": "integer", "example": 4, "description": "Number of 3-star reviews" }, "2": { "type": "integer", "example": 2, "description": "Number of 2-star reviews" }, "1": { "type": "integer", "example": 1, "description": "Number of 1-star reviews" } } }, "recent_reviews_count": { "type": "integer", "example": 5, "description": "Reviews from last 30 days" } } } } } } } } } } }, "/admin/reports": { "get": { "operationId": "getAllReports", "tags": ["Admin Report Management"], "summary": "Get all reports (admin only)", "description": "Get all reports with filtering options for administrators", "parameters": [ { "name": "status", "in": "query", "description": "Filter by report status", "required": false, "schema": { "type": "integer", "enum": [1, 2, 3, 4], "description": "1=Pending, 2=Investigating, 3=Resolved, 4=Dismissed" } }, { "name": "item_type", "in": "query", "description": "Filter by reported item type", "required": false, "schema": { "type": "integer", "enum": [1, 2, 3], "description": "1=Property, 2=User, 3=Service" } }, { "name": "reporter_id", "in": "query", "description": "Filter by reporter ID", "required": false, "schema": { "type": "integer" } }, { "name": "pending_only", "in": "query", "description": "Show only pending reports", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "per_page", "in": "query", "description": "Number of reports per page", "required": false, "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Reports retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "reports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "reporter_id": { "type": "integer", "example": 1 }, "reported_item_type": { "type": "integer", "example": 1 }, "reported_item_id": { "type": "integer", "example": 123 }, "reason": { "type": "string", "example": "Inappropriate content" }, "description": { "type": "string", "example": "The property listing contains misleading information" }, "status": { "type": "integer", "example": 1 }, "status_name": { "type": "string", "example": "Pending" }, "reporter": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } } } }, "/admin/reports/pending": { "get": { "operationId": "getPendingReports", "tags": ["Admin Report Management"], "summary": "Get pending reports (admin only)", "description": "Get all pending reports for administrators", "parameters": [ { "name": "per_page", "in": "query", "description": "Number of reports per page", "required": false, "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Pending reports retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "reports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "reporter_id": { "type": "integer", "example": 1 }, "reported_item_type": { "type": "integer", "example": 1 }, "reported_item_id": { "type": "integer", "example": 123 }, "reason": { "type": "string", "example": "Inappropriate content" }, "description": { "type": "string", "example": "The property listing contains misleading information" }, "status": { "type": "integer", "example": 1 }, "status_name": { "type": "string", "example": "Pending" }, "reporter": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } } } }, "/admin/reports/statistics": { "get": { "operationId": "getReportStatistics", "tags": ["Admin Report Management"], "summary": "Get report statistics (admin only)", "description": "Get aggregated statistics about reports for administrators", "responses": { "200": { "description": "Report statistics retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "total_reports": { "type": "integer", "example": 150 }, "pending_reports": { "type": "integer", "example": 25 }, "resolved_reports": { "type": "integer", "example": 100 }, "dismissed_reports": { "type": "integer", "example": 25 }, "by_status": { "type": "object", "properties": { "pending": { "type": "integer", "example": 25 }, "investigating": { "type": "integer", "example": 10 }, "resolved": { "type": "integer", "example": 100 }, "dismissed": { "type": "integer", "example": 25 } } }, "by_item_type": { "type": "object", "properties": { "property": { "type": "integer", "example": 80 }, "user": { "type": "integer", "example": 50 }, "service": { "type": "integer", "example": 20 } } }, "recent_activity": { "type": "object", "properties": { "last_7_days": { "type": "integer", "example": 15 }, "last_30_days": { "type": "integer", "example": 45 } } } } } } } } } } } } }, "/admin/reports/{id}": { "get": { "operationId": "getAdminReportDetails", "tags": ["Admin Report Management"], "summary": "Get report details (admin only)", "description": "Get detailed information about a specific report for administrators", "parameters": [ { "name": "id", "in": "path", "description": "Report ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Report details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "reporter_id": { "type": "integer", "example": 1 }, "reported_item_type": { "type": "integer", "example": 1 }, "reported_item_id": { "type": "integer", "example": 123 }, "reason": { "type": "string", "example": "Inappropriate content" }, "description": { "type": "string", "example": "The property listing contains misleading information" }, "status": { "type": "integer", "example": 1 }, "status_name": { "type": "string", "example": "Pending" }, "reporter": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" }, "phone": { "type": "string", "example": "+1234567890" } } }, "reported_item": { "type": "object", "description": "Detailed information about the reported item" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "404": { "description": "Report not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Report not found" } } } } } } } }, "put": { "operationId": "updateReportStatus", "tags": ["Admin Report Management"], "summary": "Update report status (admin only)", "description": "Update the status of a report for administrators", "parameters": [ { "name": "id", "in": "path", "description": "Report ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["status"], "properties": { "status": { "type": "integer", "enum": [1, 2, 3, 4], "description": "1=Pending, 2=Investigating, 3=Resolved, 4=Dismissed" } } } } } }, "responses": { "200": { "description": "Report status updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Report status updated successfully" }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "reporter_id": { "type": "integer", "example": 1 }, "reported_item_type": { "type": "integer", "example": 1 }, "reported_item_id": { "type": "integer", "example": 123 }, "reason": { "type": "string", "example": "Inappropriate content" }, "description": { "type": "string", "example": "The property listing contains misleading information" }, "status": { "type": "integer", "example": 2 }, "status_name": { "type": "string", "example": "Investigating" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "404": { "description": "Report not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Report not found" } } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/admin/properties/{id}/verifications": { "get": { "operationId": "getPropertyVerifications", "tags": ["Admin Property Management"], "summary": "Get property verifications (admin only)", "description": "Get verification history for a specific property", "parameters": [ { "name": "id", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } }, { "name": "verifier_id", "in": "query", "description": "Filter by verifier ID", "required": false, "schema": { "type": "integer" } }, { "name": "date_from", "in": "query", "description": "Filter from date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Filter to date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "recent", "in": "query", "description": "Show only recent verifications", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "description": "Limit number of verifications", "required": false, "schema": { "type": "integer", "default": 10 } }, { "name": "per_page", "in": "query", "description": "Number of verifications per page", "required": false, "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Property verifications retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Property verifications retrieved successfully" }, "data": { "type": "object", "properties": { "verifications": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "property_id": { "type": "integer", "example": 123 }, "verifier_id": { "type": "integer", "example": 2 }, "documents_verified": { "type": "array", "items": { "type": "string" }, "example": ["title_deed", "ownership_certificate"] }, "notes": { "type": "string", "example": "All documents verified successfully" }, "verifier": { "type": "object", "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "Admin User" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } } } }, "/admin/properties/verifications": { "get": { "operationId": "getAllVerifications", "tags": ["Admin Property Management"], "summary": "Get all verifications (admin only)", "description": "Get all property verifications across the platform", "parameters": [ { "name": "verifier_id", "in": "query", "description": "Filter by verifier ID", "required": false, "schema": { "type": "integer" } }, { "name": "date_from", "in": "query", "description": "Filter from date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Filter to date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "recent", "in": "query", "description": "Show only recent verifications", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "description": "Limit number of verifications", "required": false, "schema": { "type": "integer", "default": 10 } }, { "name": "per_page", "in": "query", "description": "Number of verifications per page", "required": false, "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "All verifications retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "All verifications retrieved successfully" }, "data": { "type": "object", "properties": { "verifications": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "property_id": { "type": "integer", "example": 123 }, "verifier_id": { "type": "integer", "example": 2 }, "documents_verified": { "type": "array", "items": { "type": "string" }, "example": ["title_deed", "ownership_certificate"] }, "notes": { "type": "string", "example": "All documents verified successfully" }, "property": { "type": "object", "properties": { "id": { "type": "integer", "example": 123 }, "title": { "type": "string", "example": "Beautiful Apartment in Downtown" }, "address": { "type": "string", "example": "123 Main St, City" } } }, "verifier": { "type": "object", "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "Admin User" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } } } }, "/admin/properties/verifications/statistics": { "get": { "operationId": "getVerificationStatistics", "tags": ["Admin Property Management"], "summary": "Get verification statistics (admin only)", "description": "Get aggregated statistics about property verifications", "responses": { "200": { "description": "Verification statistics retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Verification statistics retrieved successfully" }, "data": { "type": "object", "properties": { "total_verifications": { "type": "integer", "example": 150 }, "verified_properties": { "type": "integer", "example": 120 }, "pending_verifications": { "type": "integer", "example": 30 }, "verification_rate": { "type": "number", "format": "float", "example": 80.0, "description": "Percentage of properties verified" }, "by_verifier": { "type": "array", "items": { "type": "object", "properties": { "verifier_id": { "type": "integer", "example": 2 }, "verifier_name": { "type": "string", "example": "Admin User" }, "verifications_count": { "type": "integer", "example": 45 } } } }, "recent_activity": { "type": "object", "properties": { "last_7_days": { "type": "integer", "example": 12 }, "last_30_days": { "type": "integer", "example": 35 } } }, "average_verification_time": { "type": "number", "format": "float", "example": 2.5, "description": "Average days to verify a property" } } } } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API Key for mobile application authentication" } }, "schemas": { "LoginRequest": { "type": "object", "required": ["email", "password"], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" }, "password": { "type": "string", "minLength": 8, "example": "password123" } } }, "LoginResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Login successful" }, "data": { "type": "object", "properties": { "token": { "type": "string", "example": "1|abc123def456..." }, "token_type": { "type": "string", "example": "Bearer" }, "expires_in": { "type": "integer", "example": 3600 }, "user": { "$ref": "#/components/schemas/User" }, "permissions": { "type": "array", "items": { "type": "string" }, "example": ["create-properties", "read-properties"] }, "roles": { "type": "array", "items": { "type": "string" }, "example": ["landlord"] } } } } }, "ProfileResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Profile retrieved successfully" }, "data": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "permissions": { "type": "array", "items": { "type": "string" }, "example": ["create-properties", "read-properties"] }, "roles": { "type": "array", "items": { "type": "string" }, "example": ["landlord"] } } } } }, "TenantRegistrationRequest": { "type": "object", "required": ["name", "email", "password"], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 255, "description": "Full name of the tenant", "example": "John Doe" }, "email": { "type": "string", "format": "email", "maxLength": 255, "description": "Unique email address for the tenant account", "example": "tenant@example.com" }, "password": { "type": "string", "minLength": 8, "maxLength": 255, "description": "Password for the tenant account (minimum 8 characters)", "example": "password123" }, "phone": { "type": "string", "minLength": 10, "maxLength": 15, "description": "Optional phone number (must be unique if provided)", "example": "1234567890" }, "profile_photo": { "type": "string", "maxLength": 255, "description": "Optional URL to profile photo", "example": "https://example.com/photo.jpg" } } }, "LandlordRegistrationRequest": { "type": "object", "required": ["name", "email", "password"], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 255, "description": "Full name of the landlord", "example": "Jane Smith" }, "email": { "type": "string", "format": "email", "maxLength": 255, "description": "Unique email address for the landlord account", "example": "landlord@example.com" }, "password": { "type": "string", "minLength": 8, "maxLength": 255, "description": "Password for the landlord account (minimum 8 characters)", "example": "password123" }, "phone": { "type": "string", "minLength": 10, "maxLength": 15, "description": "Optional phone number (must be unique if provided)", "example": "1234567890" }, "profile_photo": { "type": "string", "maxLength": 255, "description": "Optional URL to profile photo", "example": "https://example.com/photo.jpg" } } }, "UserCreationRequest": { "type": "object", "required": ["name", "email", "password", "role_type"], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 255, "example": "Admin User" }, "email": { "type": "string", "format": "email", "example": "admin@example.com" }, "password": { "type": "string", "minLength": 8, "example": "password123" }, "phone": { "type": "string", "pattern": "^[0-9+\\-\\s()]+$", "example": "+1234567892" }, "role_type": { "type": "integer", "enum": [1, 2, 3], "description": "1=landlord, 2=tenant, 3=admin", "example": 3 }, "profile_photo": { "type": "string", "maxLength": 255, "example": "https://example.com/photo.jpg" }, "status": { "type": "integer", "enum": [1, 2, 3], "description": "1=ACTIVE, 2=INACTIVE, 3=SUSPENDED", "default": 1, "example": 1 } } }, "User": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "user@example.com" }, "phone": { "type": "string", "nullable": true, "example": "+1234567890" }, "role_type": { "type": "integer", "enum": [1, 2, 3], "description": "1=landlord, 2=tenant, 3=admin", "example": 2 }, "profile_photo": { "type": "string", "nullable": true, "example": "https://example.com/photo.jpg" }, "status": { "type": "integer", "enum": [1, 2, 3], "description": "1=ACTIVE, 2=INACTIVE, 3=SUSPENDED", "example": 1 }, "email_verified_at": { "type": "string", "format": "date-time", "nullable": true, "example": "2024-01-01T00:00:00.000000Z" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00.000000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00.000000Z" } } }, "UserResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "User created successfully" }, "data": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" } } } } }, "PendingLandlordsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Pending landlords retrieved successfully" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } }, "SuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Operation successful" } } }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Error message" } } }, "ValidationErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "example": { "email": ["Invalid credentials."], "password": ["Invalid credentials."] } } } }, "UsersListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Users retrieved successfully" }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 15 }, "total": { "type": "integer", "example": 100 }, "last_page": { "type": "integer", "example": 7 }, "from": { "type": "integer", "example": 1 }, "to": { "type": "integer", "example": 15 } } } } } } }, "UserUpdateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 255, "example": "Updated Name" }, "email": { "type": "string", "format": "email", "example": "updated@example.com" }, "phone": { "type": "string", "pattern": "^[0-9+\\-\\s()]+$", "example": "+1234567890" }, "role_type": { "type": "integer", "enum": [1, 2, 3], "description": "1=landlord, 2=tenant, 3=admin", "example": 2 }, "profile_photo": { "type": "string", "maxLength": 255, "example": "https://example.com/photo.jpg" }, "status": { "type": "integer", "enum": [1, 2, 3], "description": "1=ACTIVE, 2=INACTIVE, 3=SUSPENDED", "example": 1 } } }, "ProfileUpdateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 255, "example": "Updated Name" }, "email": { "type": "string", "format": "email", "example": "updated@example.com" }, "phone": { "type": "string", "pattern": "^[0-9+\\-\\s()]+$", "example": "+1234567890" }, "profile_photo": { "type": "string", "maxLength": 255, "example": "https://example.com/photo.jpg" } } }, "Property": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "property_type": { "type": "integer", "enum": [1, 2, 3, 4, 5], "description": "1=house, 2=apartment, 3=room, 4=hostel, 5=office", "example": 2 }, "property_type_name": { "type": "string", "example": "Apartment" }, "title": { "type": "string", "example": "Beautiful 2BR Apartment" }, "description": { "type": "string", "nullable": true, "example": "Spacious apartment with modern amenities" }, "monthly_rent": { "type": "number", "format": "float", "example": 1500.00 }, "deposit_amount": { "type": "number", "format": "float", "example": 3000.00 }, "address": { "type": "string", "example": "123 Main Street, City" }, "latitude": { "type": "number", "format": "float", "nullable": true, "example": -6.2088 }, "longitude": { "type": "number", "format": "float", "nullable": true, "example": 106.8456 }, "bedrooms": { "type": "integer", "nullable": true, "example": 2 }, "bathrooms": { "type": "integer", "nullable": true, "example": 2 }, "size_sqm": { "type": "integer", "nullable": true, "example": 80 }, "is_furnished": { "type": "boolean", "example": true }, "status": { "type": "integer", "enum": [1, 2, 3, 4], "description": "1=available, 2=occupied, 3=pending, 4=maintenance", "example": 1 }, "status_name": { "type": "string", "example": "Available" }, "is_verified": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00.000000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00.000000Z" }, "landlord": { "$ref": "#/components/schemas/PropertyLandlord" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/PropertyImage" } }, "hostel": { "allOf": [ { "$ref": "#/components/schemas/Hostel" } ], "nullable": true } } }, "PropertyLandlord": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "landlord@example.com" }, "phone": { "type": "string", "nullable": true, "example": "+1234567890" } } }, "PropertyImage": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "image_url": { "type": "string", "example": "https://example.com/image1.jpg" }, "is_primary": { "type": "boolean", "example": true } } }, "Hostel": { "type": "object", "properties": { "university_nearby": { "type": "string", "example": "University of Technology" }, "distance_to_university": { "type": "number", "format": "float", "example": 2.5 }, "room_sharing": { "type": "integer", "enum": [1, 2, 3], "description": "1=single, 2=double, 3=triple", "example": 2 }, "room_sharing_name": { "type": "string", "example": "Double" }, "gender_restriction": { "type": "integer", "enum": [1, 2, 3], "description": "1=male, 2=female, 3=mixed", "example": 3 }, "gender_restriction_name": { "type": "string", "example": "Mixed" }, "meal_plan_available": { "type": "boolean", "example": true }, "study_room_available": { "type": "boolean", "example": true }, "curfew_time": { "type": "string", "nullable": true, "example": "22:00" } } }, "PropertyRequest": { "type": "object", "required": ["property_type", "title", "monthly_rent", "deposit_amount", "address"], "properties": { "property_type": { "type": "integer", "enum": [1, 2, 3, 4, 5], "description": "1=house, 2=apartment, 3=room, 4=hostel, 5=office", "example": 2 }, "title": { "type": "string", "minLength": 3, "maxLength": 255, "example": "Beautiful 2BR Apartment" }, "description": { "type": "string", "maxLength": 2000, "nullable": true, "example": "Spacious apartment with modern amenities" }, "monthly_rent": { "type": "number", "format": "float", "minimum": 0, "example": 1500.00 }, "deposit_amount": { "type": "number", "format": "float", "minimum": 0, "example": 3000.00 }, "address": { "type": "string", "minLength": 5, "maxLength": 500, "example": "123 Main Street, City" }, "latitude": { "type": "number", "format": "float", "nullable": true, "example": -6.2088 }, "longitude": { "type": "number", "format": "float", "nullable": true, "example": 106.8456 }, "bedrooms": { "type": "integer", "minimum": 0, "nullable": true, "example": 2 }, "bathrooms": { "type": "integer", "minimum": 0, "nullable": true, "example": 2 }, "size_sqm": { "type": "integer", "minimum": 0, "nullable": true, "example": 80 }, "is_furnished": { "type": "boolean", "default": false, "example": true }, "status": { "type": "integer", "enum": [1, 2, 3, 4], "description": "1=available, 2=occupied, 3=pending, 4=maintenance", "default": 3, "example": 3 }, "images": { "type": "array", "items": { "type": "object", "properties": { "image_url": { "type": "string", "example": "https://example.com/image1.jpg" }, "is_primary": { "type": "boolean", "default": false, "example": true } }, "required": ["image_url"] } }, "hostel": { "type": "object", "properties": { "university_nearby": { "type": "string", "minLength": 2, "maxLength": 255, "example": "University of Technology" }, "distance_to_university": { "type": "number", "format": "float", "minimum": 0, "example": 2.5 }, "room_sharing": { "type": "integer", "enum": [1, 2, 3], "description": "1=single, 2=double, 3=triple", "example": 2 }, "gender_restriction": { "type": "integer", "enum": [1, 2, 3], "description": "1=male, 2=female, 3=mixed", "example": 3 }, "meal_plan_available": { "type": "boolean", "default": false, "example": true }, "study_room_available": { "type": "boolean", "default": false, "example": true }, "curfew_time": { "type": "string", "nullable": true, "example": "22:00" } }, "required": ["university_nearby", "distance_to_university", "room_sharing", "gender_restriction"] } } }, "PropertyResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Property retrieved successfully" }, "data": { "type": "object", "properties": { "property": { "$ref": "#/components/schemas/Property" } } } } }, "VerifyPropertyRequest": { "type": "object", "properties": { "documents_verified": { "type": "array", "items": { "type": "string" }, "description": "Optional array of document types that were verified", "example": ["title_deed", "identity_card", "business_license"] }, "notes": { "type": "string", "maxLength": 1000, "description": "Optional notes about the verification", "example": "All documents verified. Property meets all requirements." } } }, "PropertyVerificationResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Property verified successfully" }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "Verification record ID", "example": 1 }, "property_id": { "type": "integer", "description": "ID of the verified property", "example": 5 }, "property": { "type": "object", "properties": { "id": { "type": "integer", "example": 5 }, "title": { "type": "string", "example": "Modern 2BR Apartment" }, "address": { "type": "string", "example": "123 Main Street, City" } } }, "verified_by": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Admin User" }, "email": { "type": "string", "format": "email", "example": "admin@example.com" } } }, "verification_date": { "type": "string", "format": "date-time", "description": "Date and time when the property was verified", "example": "2025-09-20T18:30:00.000000Z" }, "documents_verified": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Array of document types that were verified", "example": ["title_deed", "identity_card"] }, "notes": { "type": "string", "nullable": true, "description": "Notes about the verification", "example": "All documents verified. Property meets all requirements." }, "created_at": { "type": "string", "format": "date-time", "example": "2025-09-20T18:30:00.000000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-09-20T18:30:00.000000Z" } } } } }, "PropertiesListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Properties retrieved successfully" }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Property" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } }, "Pagination": { "type": "object", "properties": { "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 15 }, "total": { "type": "integer", "example": 100 }, "last_page": { "type": "integer", "example": 7 }, "from": { "type": "integer", "example": 1 }, "to": { "type": "integer", "example": 15 } } }, "CreateBookingRequest": { "type": "object", "required": ["property_id", "check_in_date"], "properties": { "property_id": { "type": "integer", "description": "ID of the property to book", "example": 1 }, "check_in_date": { "type": "string", "format": "date", "description": "Check-in date (must be today or future)", "example": "2025-10-01" }, "check_out_date": { "type": "string", "format": "date", "description": "Check-out date (optional for long-term rentals)", "example": "2025-10-31" } } }, "BookingResponse": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "property_id": { "type": "integer", "example": 1 }, "tenant_id": { "type": "integer", "example": 3 }, "landlord_id": { "type": "integer", "example": 2 }, "check_in_date": { "type": "string", "format": "date", "example": "2025-10-01" }, "check_out_date": { "type": "string", "format": "date", "nullable": true, "example": "2025-10-31" }, "status": { "type": "integer", "enum": [1, 2, 3, 4, 5], "description": "1=pending, 2=approved, 3=rejected, 4=cancelled, 5=completed", "example": 1 }, "status_text": { "type": "string", "enum": ["pending", "approved", "rejected", "cancelled", "completed"], "example": "pending" }, "created_at": { "type": "string", "format": "date-time", "example": "2025-09-20 18:30:00" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-09-20 18:30:00" }, "property": { "allOf": [ { "$ref": "#/components/schemas/PropertyResponse" } ], "nullable": true }, "tenant": { "allOf": [ { "$ref": "#/components/schemas/UserResponse" } ], "nullable": true }, "landlord": { "allOf": [ { "$ref": "#/components/schemas/UserResponse" } ], "nullable": true }, "rental_agreement": { "allOf": [ { "$ref": "#/components/schemas/RentalAgreementResponse" } ], "nullable": true } } }, "RentalAgreementResponse": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "booking_id": { "type": "integer", "example": 1 }, "property_id": { "type": "integer", "example": 1 }, "tenant_id": { "type": "integer", "example": 3 }, "landlord_id": { "type": "integer", "example": 2 }, "start_date": { "type": "string", "format": "date", "example": "2025-10-01" }, "end_date": { "type": "string", "format": "date", "nullable": true, "example": "2025-10-31" }, "monthly_rent": { "type": "number", "format": "decimal", "example": 1000.00 }, "deposit_amount": { "type": "number", "format": "decimal", "example": 500.00 }, "contract_document_url": { "type": "string", "nullable": true, "example": "https://example.com/contracts/agreement_1.pdf" }, "is_active": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time", "example": "2025-09-20 18:30:00" } } }, "BookingsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BookingResponse" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "UpdateBookingStatusRequest": { "type": "object", "required": ["status"], "properties": { "status": { "type": "integer", "enum": [1, 2, 3, 4, 5], "description": "1=pending, 2=approved, 3=rejected, 4=cancelled, 5=completed", "example": 2 } } }, "CreatePaymentRequest": { "type": "object", "required": ["booking_id", "amount", "payment_method", "payment_type", "transaction_reference"], "properties": { "booking_id": { "type": "integer", "description": "ID of the booking", "example": 1 }, "amount": { "type": "number", "format": "decimal", "description": "Payment amount", "example": 1500.00 }, "payment_method": { "type": "integer", "enum": [1, 2, 3], "description": "1=mobile_money, 2=bank, 3=cash", "example": 1 }, "payment_type": { "type": "integer", "enum": [1, 2, 3, 4], "description": "1=rent, 2=deposit, 3=partial, 4=recurring", "example": 1 }, "transaction_reference": { "type": "string", "description": "Transaction reference number", "example": "TXN123456789" }, "due_date": { "type": "string", "format": "date", "description": "Due date for the payment (optional)", "example": "2025-10-01" } } }, "PaymentResponse": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "booking_id": { "type": "integer", "example": 1 }, "tenant_id": { "type": "integer", "example": 3 }, "landlord_id": { "type": "integer", "example": 2 }, "amount": { "type": "number", "format": "decimal", "example": 1500.00 }, "payment_method": { "type": "integer", "enum": [1, 2, 3], "description": "1=mobile_money, 2=bank, 3=cash", "example": 1 }, "payment_method_text": { "type": "string", "enum": ["mobile_money", "bank", "cash"], "example": "mobile_money" }, "payment_type": { "type": "integer", "enum": [1, 2, 3, 4], "description": "1=rent, 2=deposit, 3=partial, 4=recurring", "example": 1 }, "payment_type_text": { "type": "string", "enum": ["rent", "deposit", "partial", "recurring"], "example": "rent" }, "transaction_reference": { "type": "string", "example": "TXN123456789" }, "status": { "type": "integer", "enum": [1, 2, 3, 4], "description": "1=pending, 2=completed, 3=failed, 4=refunded", "example": 1 }, "status_text": { "type": "string", "enum": ["pending", "completed", "failed", "refunded"], "example": "pending" }, "due_date": { "type": "string", "format": "date", "nullable": true, "example": "2025-10-01" }, "paid_at": { "type": "string", "format": "date-time", "nullable": true, "example": "2025-09-20 18:30:00" }, "created_at": { "type": "string", "format": "date-time", "example": "2025-09-20 18:30:00" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-09-20 18:30:00" }, "booking": { "allOf": [ { "$ref": "#/components/schemas/BookingResponse" } ], "nullable": true }, "tenant": { "allOf": [ { "$ref": "#/components/schemas/UserResponse" } ], "nullable": true }, "landlord": { "allOf": [ { "$ref": "#/components/schemas/UserResponse" } ], "nullable": true }, "receipt": { "allOf": [ { "$ref": "#/components/schemas/PaymentReceiptResponse" } ], "nullable": true } } }, "PaymentReceiptResponse": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "payment_id": { "type": "integer", "example": 1 }, "receipt_number": { "type": "string", "example": "RCP202509201234" }, "issued_date": { "type": "string", "format": "date-time", "example": "2025-09-20 18:30:00" }, "pdf_url": { "type": "string", "nullable": true, "example": "https://example.com/receipts/receipt_1.pdf" } } }, "PaymentsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentResponse" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "UpdatePaymentStatusRequest": { "type": "object", "required": ["status"], "properties": { "status": { "type": "integer", "enum": [1, 2, 3, 4], "description": "1=pending, 2=completed, 3=failed, 4=refunded", "example": 2 } } } } }, "tags": [ { "name": "Authentication", "description": "User authentication and session management" }, { "name": "User Management", "description": "User registration, management, and approval workflows" }, { "name": "Property Management", "description": "Property CRUD operations, search, and filtering for landlords and tenants" }, { "name": "Admin Property Management", "description": "Property verification and status management for administrators" }, { "name": "Booking Management", "description": "Booking creation, viewing, and cancellation for tenants" }, { "name": "Landlord Booking Management", "description": "Booking approval, rejection, and management for landlords" }, { "name": "Admin Booking Management", "description": "Comprehensive booking management and status updates for administrators" }, { "name": "Payment Management", "description": "Payment creation, viewing, and tracking for tenants" }, { "name": "Landlord Payment Management", "description": "Payment confirmation, rejection, and management for landlords" }, { "name": "Admin Payment Management", "description": "Comprehensive payment management and status updates for administrators" } ] }