# SureRightStay API Documentation

**Base URL:** `http://localhost:8000/api`  
**Version:** 1.0  
**Authentication:** JWT Bearer Token

---

## 📑 Table of Contents

1. [Authentication](#authentication)
2. [User Management](#user-management)
3. [Property Management](#property-management)
4. [Search & Discovery](#search--discovery)
5. [Bookings & Requests](#bookings--requests)
6. [Agency Management](#agency-management)
7. [Payments & Subscriptions](#payments--subscriptions)
8. [Notifications](#notifications)
9. [Dashboard & Analytics](#dashboard--analytics)
10. [Support & Audit](#support--audit)
11. [Error Handling](#error-handling)

---

## 🔐 Authentication

All authenticated endpoints require a JWT token in the Authorization header:

```
Authorization: Bearer {your-jwt-token}
```

### Register User

**Endpoint:** `POST /api/auth/register`

**Request Body:**
```json
{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "SecurePass123!",
  "password_confirmation": "SecurePass123!",
  "role_id": 2
}
```

**Response (201):**
```json
{
  "message": "User registered successfully",
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "email_verified_at": null,
    "created_at": "2026-02-15T10:00:00.000000Z"
  },
  "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "token_type": "bearer",
  "expires_in": 3600
}
```

### Login

**Endpoint:** `POST /api/auth/login`

**Request Body:**
```json
{
  "email": "john@example.com",
  "password": "SecurePass123!"
}
```

**Response (200):**
```json
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "token_type": "bearer",
  "expires_in": 3600,
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
  }
}
```

### Logout

**Endpoint:** `POST /api/auth/logout`  
**Auth Required:** Yes

**Response (200):**
```json
{
  "message": "Successfully logged out"
}
```

### Get Current User

**Endpoint:** `GET /api/auth/me` or `GET /api/me`  
**Auth Required:** Yes

**Response (200):**
```json
{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "email_verified_at": "2026-02-15T10:30:00.000000Z",
  "userData": {
    "id": 1,
    "user_id": 1,
    "phone": "+234801234567",
    "address": "123 Main St, Lagos",
    "profile_picture": "https://example.com/images/profile.jpg"
  },
  "roles": [
    {
      "id": 2,
      "name": "tenant",
      "description": "Tenant user"
    }
  ]
}
```

### Forgot Password

**Endpoint:** `POST /api/auth/forgot-password`

**Request Body:**
```json
{
  "email": "john@example.com"
}
```

**Response (200):**
```json
{
  "message": "Password reset link sent to your email"
}
```

### Reset Password

**Endpoint:** `POST /api/auth/reset-password`

**Request Body:**
```json
{
  "email": "john@example.com",
  "token": "reset-token-from-email",
  "password": "NewSecurePass123!",
  "password_confirmation": "NewSecurePass123!"
}
```

---

## 👥 User Management

### Get All Users

**Endpoint:** `GET /api/users-data`

**Query Parameters:**
- `page` (optional): Page number
- `per_page` (optional): Items per page

**Response (200):**
```json
{
  "data": [
    {
      "id": 1,
      "user_id": 1,
      "phone": "+234801234567",
      "address": "123 Main St",
      "created_at": "2026-02-15T10:00:00.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "total": 50,
    "per_page": 15
  }
}
```

### Get User by ID

**Endpoint:** `GET /api/users-data/{id}`

### Get Users by Role

**Endpoint:** `GET /api/users-data/role/{roleId}`

### Update User Profile

**Endpoint:** `PUT /api/profile`  
**Auth Required:** Yes

**Request Body:**
```json
{
  "name": "John Updated",
  "phone": "+234801234567",
  "address": "456 New Street, Lagos"
}
```

### Change Password

**Endpoint:** `POST /api/profile/change-password`  
**Auth Required:** Yes

**Request Body:**
```json
{
  "current_password": "OldPass123!",
  "new_password": "NewPass123!",
  "new_password_confirmation": "NewPass123!"
}
```

### Upload Profile Picture

**Endpoint:** `POST /api/profile/upload-picture`  
**Auth Required:** Yes  
**Content-Type:** `multipart/form-data`

**Request Body:**
```
picture: [file]
```

---

## 🏠 Property Management

### List All Properties

**Endpoint:** `GET /api/property-data`

**Query Parameters:**
- `page`: Page number
- `per_page`: Items per page
- `purpose`: rent|sale|shortlet
- `state_id`: Filter by state
- `area_id`: Filter by area
- `property_type_id`: Filter by type
- `min_price`: Minimum price
- `max_price`: Maximum price

**Response (200):**
```json
{
  "data": [
    {
      "id": 1,
      "title": "Luxury 3 Bedroom Apartment",
      "purpose": "rent",
      "price": "500000.00",
      "currency": "NGN",
      "bedrooms": 3,
      "bathrooms": 2,
      "address": "Lekki Phase 1, Lagos",
      "listing_status": "active",
      "is_verified": true,
      "images": [
        {
          "id": 1,
          "image_url": "https://example.com/property1.jpg",
          "is_primary": true
        }
      ],
      "state": {
        "id": 1,
        "name": "Lagos"
      },
      "propertyType": {
        "id": 1,
        "name": "Apartment"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "total": 150,
    "per_page": 20
  }
}
```

### Get Single Property

**Endpoint:** `GET /api/property-data/{id}`

**Response (200):**
```json
{
  "id": 1,
  "title": "Luxury 3 Bedroom Apartment",
  "description": "Beautiful apartment with modern amenities...",
  "purpose": "rent",
  "price": "500000.00",
  "currency": "NGN",
  "bedrooms": 3,
  "bathrooms": 2,
  "toilets": 2,
  "parking": 2,
  "area_size": 120,
  "area_type": "sqm",
  "address": "Lekki Phase 1, Lagos",
  "listing_status": "active",
  "is_verified": true,
  "creator": {
    "id": 5,
    "name": "Property Owner",
    "email": "owner@example.com"
  },
  "images": [...],
  "features": [
    {
      "id": 1,
      "feature": {
        "id": 1,
        "name": "Swimming Pool",
        "icon": "pool"
      }
    }
  ]
}
```

### Create Property

**Endpoint:** `POST /api/property-data`  
**Auth Required:** Yes

**Request Body:**
```json
{
  "title": "Modern 2 Bedroom Flat",
  "purpose": "rent",
  "state_id": 1,
  "area_id": 5,
  "address": "Victoria Island, Lagos",
  "property_type_id": 1,
  "property_category_id": 2,
  "price": 350000,
  "currency": "NGN",
  "bedrooms": 2,
  "bathrooms": 2,
  "toilets": 2,
  "parking": 1,
  "area_size": 85,
  "area_type": "sqm",
  "description": "Newly renovated apartment...",
  "denomination": "per annum"
}
```

**Response (201):**
```json
{
  "message": "Property created successfully",
  "data": {
    "id": 25,
    "title": "Modern 2 Bedroom Flat",
    "listing_status": "pending",
    "is_verified": false,
    ...
  }
}
```

### Update Property

**Endpoint:** `PUT /api/property-data/{id}`  
**Auth Required:** Yes

### Delete Property

**Endpoint:** `DELETE /api/property-data/{id}`  
**Auth Required:** Yes

### Approve Property

**Endpoint:** `PUT /api/property-data/approve/{id}`  
**Auth Required:** Yes (Admin only)

### Reject Property

**Endpoint:** `PUT /api/property-data/reject/{id}`  
**Auth Required:** Yes (Admin only)

**Request Body:**
```json
{
  "reason": "Incomplete documentation"
}
```

### Get Properties by Owner

**Endpoint:** `GET /api/property-data/owner/{userId}`

### Get Properties by Agent

**Endpoint:** `GET /api/property-data/agent/{agentId}`

---

## 🔍 Search & Discovery

### Basic Property Search

**Endpoint:** `GET /api/property-search`

**Query Parameters:**
- `q`: Search query
- `purpose`: rent|sale|shortlet
- `state_id`: State ID
- `min_price`, `max_price`: Price range
- `bedrooms`: Number of bedrooms
- `property_type_id`: Property type

### Advanced Search

**Endpoint:** `GET /api/search/advanced`

**Query Parameters:**
- All basic search params plus:
- `bathrooms`: Number of bathrooms
- `parking`: Parking spaces
- `min_area`, `max_area`: Area size range
- `features[]`: Array of feature IDs
- `verified_only`: true|false

**Response (200):**
```json
{
  "data": [...],
  "filters_applied": {
    "purpose": "rent",
    "state_id": 1,
    "min_price": 200000,
    "max_price": 600000,
    "bedrooms": 3
  },
  "total_results": 45
}
```

### Location-based Search

**Endpoint:** `GET /api/search/location`

**Query Parameters:**
- `latitude`: Latitude
- `longitude`: Longitude
- `radius`: Search radius in km

### Save Search

**Endpoint:** `POST /api/search/save`  
**Auth Required:** Yes

**Request Body:**
```json
{
  "name": "My Lagos Search",
  "criteria": {
    "purpose": "rent",
    "state_id": 1,
    "min_price": 300000,
    "max_price": 500000,
    "bedrooms": 3
  },
  "notify_on_new": true
}
```

### Get Saved Searches

**Endpoint:** `GET /api/search/saved`  
**Auth Required:** Yes

### Delete Saved Search

**Endpoint:** `DELETE /api/search/saved/{id}`  
**Auth Required:** Yes

---

## 📅 Bookings & Requests

### Create Tenant Property Request

**Endpoint:** `POST /api/property-requests`  
**Auth Required:** Yes

**Request Body:**
```json
{
  "property_id": 15,
  "move_in_date": "2026-03-01",
  "duration_months": 12,
  "message": "I am interested in this property..."
}
```

**Response (201):**
```json
{
  "message": "Request submitted successfully",
  "data": {
    "id": 10,
    "property_id": 15,
    "tenant_id": 3,
    "status": "pending",
    "move_in_date": "2026-03-01",
    "created_at": "2026-02-15T12:00:00.000000Z"
  }
}
```

### Get All Requests

**Endpoint:** `GET /api/property-requests`  
**Auth Required:** Yes

### Get Single Request

**Endpoint:** `GET /api/property-requests/{id}`  
**Auth Required:** Yes

### Update Request Status

**Endpoint:** `PUT /api/property-requests/{id}/status`  
**Auth Required:** Yes

**Request Body:**
```json
{
  "status": "approved",
  "notes": "Request approved, please proceed with payment"
}
```

---

## 🏢 Agency Management

### List Agents by Agency

**Endpoint:** `GET /api/agency/{agencyId}/agents`  
**Auth Required:** Yes

### Add Agent to Agency

**Endpoint:** `POST /api/agency/agents`  
**Auth Required:** Yes

**Request Body:**
```json
{
  "agency_id": 5,
  "user_id": 20,
  "commission_rate": 5.5,
  "role": "field_agent"
}
```

### Activate Agent

**Endpoint:** `POST /api/agency/agents/{id}/activate`  
**Auth Required:** Yes

### Deactivate Agent

**Endpoint:** `POST /api/agency/agents/{id}/deactivate`  
**Auth Required:** Yes

### Get Agent Properties

**Endpoint:** `GET /api/agency/agents/{agentId}/properties`  
**Auth Required:** Yes

### Get Agent Statistics

**Endpoint:** `GET /api/agency/agents/{agentId}/stats`  
**Auth Required:** Yes

**Response (200):**
```json
{
  "total_properties": 25,
  "active_properties": 18,
  "total_bookings": 42,
  "total_commission": "125000.00",
  "this_month": {
    "properties_added": 3,
    "bookings": 5,
    "commission": "15000.00"
  }
}
```

---

## 💳 Payments & Subscriptions

### Create Payment

**Endpoint:** `POST /api/payments`  
**Auth Required:** Yes

**Request Body:**
```json
{
  "booking_id": 10,
  "amount": 500000,
  "payment_method": "card",
  "payment_reference": "TXN-123456789"
}
```

### Get Payment History

**Endpoint:** `GET /api/payments/history`  
**Auth Required:** Yes

### Get Payment Statistics

**Endpoint:** `GET /api/payments/stats`  
**Auth Required:** Yes

### List Subscription Plans

**Endpoint:** `GET /api/subscriptions/plans`

**Response (200):**
```json
{
  "data": [
    {
      "id": 1,
      "name": "Basic Plan",
      "description": "List up to 5 properties",
      "price": "5000.00",
      "duration_days": 30,
      "features": {
        "max_properties": 5,
        "verification_included": true,
        "priority_support": false
      }
    },
    {
      "id": 2,
      "name": "Premium Plan",
      "description": "Unlimited properties",
      "price": "15000.00",
      "duration_days": 30,
      "features": {
        "max_properties": -1,
        "verification_included": true,
        "priority_support": true,
        "featured_listings": true
      }
    }
  ]
}
```

### Subscribe to Plan

**Endpoint:** `POST /api/subscriptions/subscribe`  
**Auth Required:** Yes

**Request Body:**
```json
{
  "pricing_plan_id": 2,
  "payment_method": "card"
}
```

### Get Active Subscription

**Endpoint:** `GET /api/subscriptions/active`  
**Auth Required:** Yes

### Cancel Subscription

**Endpoint:** `POST /api/subscriptions/{id}/cancel`  
**Auth Required:** Yes

---

## 🔔 Notifications

### Get All Notifications

**Endpoint:** `GET /api/notifications`  
**Auth Required:** Yes

**Response (200):**
```json
{
  "data": [
    {
      "id": "abc123",
      "type": "PropertyApproved",
      "data": {
        "property_id": 15,
        "property_title": "Luxury Apartment",
        "message": "Your property has been approved"
      },
      "read_at": null,
      "created_at": "2026-02-15T10:00:00.000000Z"
    }
  ],
  "unread_count": 5
}
```

### Get Unread Count

**Endpoint:** `GET /api/notifications/unread-count`  
**Auth Required:** Yes

### Mark as Read

**Endpoint:** `POST /api/notifications/{id}/read`  
**Auth Required:** Yes

### Mark All as Read

**Endpoint:** `POST /api/notifications/read-all`  
**Auth Required:** Yes

---

## 📊 Dashboard & Analytics

### User Dashboard

**Endpoint:** `GET /api/dashboard/user`  
**Auth Required:** Yes

**Response (200):**
```json
{
  "summary": {
    "total_properties": 5,
    "active_bookings": 2,
    "pending_requests": 3,
    "total_spent": "1500000.00"
  },
  "recent_activities": [...],
  "upcoming_payments": [...]
}
```

### Admin Dashboard

**Endpoint:** `GET /api/dashboard/admin`  
**Auth Required:** Yes (Admin only)

**Response (200):**
```json
{
  "overview": {
    "total_users": 1250,
    "total_properties": 450,
    "active_bookings": 125,
    "total_revenue": "15000000.00"
  },
  "recent_signups": [...],
  "pending_verifications": 15,
  "revenue_this_month": "2500000.00"
}
```

### Property Statistics

**Endpoint:** `GET /api/dashboard/property-stats`  
**Auth Required:** Yes

### User Activity

**Endpoint:** `GET /api/dashboard/user-activity`  
**Auth Required:** Yes

---

## 🛠️ Support & Audit

### Get Audit Logs (Admin Actions)

**Endpoint:** `GET /api/audit-logs/admin-actions`  
**Auth Required:** Yes (Admin only)

### Get Verification Logs

**Endpoint:** `GET /api/audit-logs/verification`  
**Auth Required:** Yes (Admin only)

### Get Payment Logs

**Endpoint:** `GET /api/audit-logs/payment`  
**Auth Required:** Yes (Admin only)

### Export Logs

**Endpoint:** `POST /api/audit-logs/export`  
**Auth Required:** Yes (Admin only)

---

## ⚠️ Error Handling

### Standard Error Response

```json
{
  "message": "Error description",
  "errors": {
    "field_name": [
      "Validation error message"
    ]
  }
}
```

### HTTP Status Codes

- `200` - Success
- `201` - Created
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden
- `404` - Not Found
- `422` - Validation Error
- `500` - Server Error

### Common Error Examples

**401 Unauthorized:**
```json
{
  "message": "Unauthenticated."
}
```

**422 Validation Error:**
```json
{
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "The email field is required."
    ],
    "password": [
      "The password must be at least 8 characters."
    ]
  }
}
```

---

## 📝 Notes

- All timestamps are in UTC format
- Pagination uses `page` and `per_page` parameters
- Default `per_page` is 15, maximum is 100
- JWT tokens expire after 60 minutes
- File uploads have a maximum size of 5MB
- Image uploads support: jpg, jpeg, png, gif
- Document uploads support: pdf, doc, docx

---

**Last Updated:** February 15, 2026  
**API Version:** 1.0