# Authentication API Documentation Base URL: `/api/auth` ## 1. Register User Create a new user account with profile details. - **Endpoint:** `POST /register` - **Auth Required:** No **Request Body:** ```json { "name": "John Doe", "email": "john@example.com", "password": "Password123!", "password_confirmation": "Password123!", "role": "user", // Options: admin, superadmin, agent, user "phone": "+1234567890", "address": "123 Main St", "city": "New York", "state": "NY", "zip_code": "10001", "country": "USA", "gender": "male", // Options: male, female, other "nin": "AB123456C", "avatar": "https://example.com/avatar.jpg" // Optional } ``` **Success Response (201):** ```json { "status": "success", "message": "Registration successful", "data": { "user": { "id": "...", "name": "John Doe", "email": "john@example.com", "role": "user", "agent_id": "AGT1234", // Auto-generated if role is agent ... }, "token": "eyJ0eXAiOiJKV1QiLC..." } } ``` --- ## 2. Login Authenticate a user and receive a JWT token. - **Endpoint:** `POST /login` - **Auth Required:** No **Request Body:** ```json { "login": "john@example.com", // Email or Admin ID "password": "Password123!" } ``` **Success Response (200):** ```json { "status": "success", "message": "Login successfull", "data": { "id": "...", "name": "John Doe", "email": "john@example.com", "token": "eyJ0eXAiOiJKV1QiLC..." } } ``` --- ## 3. Get Profile (Me) Get the currently authenticated user's details including their profile. - **Endpoint:** `GET /profile` - **Auth Required:** Yes (Bearer Token) **Headers:** ``` Authorization: Bearer Accept: application/json ``` **Success Response (200):** ```json { "status": "success", "message": "Success", "data": { "id": "...", "name": "John Doe", "email": "john@example.com", "profile": { "phone": "+1234567890", "address": "123 Main St", ... } } } ``` --- ## 4. Refresh Token Refresh an expired token to get a new one. - **Endpoint:** `POST /refresh` - **Auth Required:** Yes (Bearer Token) **Headers:** ``` Authorization: Bearer ``` **Success Response (200):** ```json { "status": "success", "message": "Success", "data": { "token": "eyJ0eXAiOiJKV1QiLC..." } } ``` --- ## 5. Logout Invalidate the current token. - **Endpoint:** `POST /logout` - **Auth Required:** Yes (Bearer Token) **Headers:** ``` Authorization: Bearer ``` **Success Response (200):** ```json { "status": "success", "message": "Logout successful", "data": [] } ``` --- # Cart API Documentation Base URL: `/api` ## 1. Create Cart Create a new cart with property items. - **Endpoint:** `POST /carts` - **Auth Required:** No **Request Body:**/ ```json { "session_id": "guest-uuid-123", "items": [ { "property_id": "abc123", "title": "Luxury 4 Bedroom Duplex", "price": 25000000, "location": "Lekki Phase 1", "image": "https://example.com/property.jpg", "bedrooms": 4, "bathrooms": 3 } ] // Exactly one item required } ``` > [!IMPORTANT] > The `items` array must contain exactly one property. Carts are restricted to single-item bookings. **Success Response (201):** ```json { "status": "success", "message": "Cart created successfully", "data": { "id": "695bb015b6bfdaa4d1090842", "session_id": "guest-uuid-123", "items": [...], "total": 25000000, "status": "active", "expires_at": "2026-01-06T12:35:32.251Z" } } ``` --- ## 2. Get Cart Retrieve a cart by ID. - **Endpoint:** `GET /carts/{id}` - **Auth Required:** No **Success Response (200):** ```json { "status": "success", "message": "Cart retrieved successfully", "data": { "id": "...", "items": [...], "total": 25000000, "status": "active", "inspection": null } } ``` --- ## 3. Update Cart Update cart items or status. - **Endpoint:** `PUT /carts/{id}` - **Auth Required:** No **Request Body:** ```json { "items": [...], // Exactly one item if provided "status": "active" } ``` --- ## 4. Add Item to Cart Add a new property to an existing cart. - **Endpoint:** `POST /carts/{id}/items` - **Auth Required:** No **Request Body:** ```json { "property_id": "xyz789", "title": "3 Bedroom Apartment", "price": 15000000, "location": "Ikoyi", "bedrooms": 3, "bathrooms": 2 } ``` > [!NOTE] > This endpoint will **replace** any existing item in the cart with the new property provided. --- --- ## 6. Clear Current Cart Clear the cart for the current session or authenticated user. - **Endpoint:** `DELETE /carts/current` - **Auth Required:** No (if guest, provides session_id) **Request Headers (Optional):** - `X-Session-ID`: ID of the guest session **Request Body (Optional):** ```json { "session_id": "guest-uuid-123" } ``` --- ## 7. Delete Cart by ID Delete a specific cart using its ID. - **Endpoint:** `DELETE /carts/{id}` - **Auth Required:** No --- # Payment API Documentation Base URL: `/api/payments` ## 1. Initialize Partial Payment (10%) Initialize the 10% payment and get virtual account details for manual transfer. Note: A fixed **N5,000 inspection fee** is added to the 10% partial amount. - **Endpoint:** `POST /initialize-partial` - **Auth Required:** No **Request Body:** ```json { "cart_id": "695bb015b6bfdaa4d1090842", "customer_name": "John Doe", "customer_email": "john@example.com", "redirect_url": "https://example.com/payment-success" // Optional } ``` **Success Response (200):** ```json { "status": "success", "message": "Payment details generated successfully...", "data": { "paymentReference": "PAY-ABC123XYZ", "amountToPay": 2500000, "accountNumber": "0123456789", "bankName": "Wema Bank", "accountName": "PROPERTY HUB - JOHN DOE", "bankCode": "035" } } ``` --- ## 2. Verify Payment Verify a payment status using the reference provided during initialization. - **Endpoint:** `GET /verify/{reference}` - **Auth Required:** No **Success Response (200):** ```json { "status": "success", "message": "Payment verified successfully", "data": { "status": "successful", "payment_reference": "PAY-ABC123XYZ", ... } } ``` --- # Inspection API Documentation Base URL: `/api` ## 1. Book Inspection Book a property inspection for a cart. - **Endpoint:** `POST /inspections` - **Auth Required:** No **Request Body:** ```json { "cart_id": "695bb015b6bfdaa4d1090842", "full_name": "John Doe", "email": "john@example.com", "phone": "+234 812 345 6789", "address": "123 Victoria Island, Lagos", "preferred_date": "2026-01-10", "preferred_time": "10:30", "notes": "I would like to see the backyard" } ``` **Success Response (201):** ```json { "status": "success", "message": "Inspection booked successfully", "data": { "id": "695bb04ab6bfdaa4d1090843", "cart_id": "695bb015b6bfdaa4d1090842", "full_name": "John Doe", "email": "john@example.com", "phone": "+234 812 345 6789", "preferred_date": "2026-01-10", "preferred_time": "10:30", "status": "pending", "cart": { "items": [...], "total": 25000000, "status": "converted" } } } ``` --- ## 2. List Inspections (Admin) Get all inspections with filters. - **Endpoint:** `GET /inspections` - **Auth Required:** Yes (Bearer Token) - **Role Required:** `superadmin` **Query Parameters:** - `status` - Filter by status (pending, confirmed, completed, cancelled) - `start_date` - Filter by date range start - `end_date` - Filter by date range end - `per_page` - Pagination (default: 15) --- ## 3. Get Inspection (Admin) Get inspection details by ID. - **Endpoint:** `GET /inspections/{id}` - **Auth Required:** Yes (Bearer Token) - **Role Required:** `superadmin` --- ## 4. Update Inspection (Admin) Update inspection status or reschedule. - **Endpoint:** `PUT /inspections/{id}` - **Auth Required:** Yes (Bearer Token) - **Role Required:** `superadmin` **Request Body:** ```json { "status": "booked", // Options: pending, booked, confirmed, completed, cancelled "preferred_date": "2026-01-12", "preferred_time": "14:00", "notes": "Approved by admin" } ``` > [!TIP] > Use `status: booked` to officially accept an inspection request. --- ## 5. Cancel Inspection (Admin) Cancel and delete an inspection. - **Endpoint:** `DELETE /inspections/{id}` - **Auth Required:** Yes (Bearer Token) - **Role Required:** `superadmin`