{ "info": { "_postman_id": "ocs-collection-v1", "name": "One Click Spaces API", "description": "Complete API reference for One Click Spaces — a multi-vertical bookable spaces marketplace.\n\n**Base URL:** `https://api.oneclickspaces.com`\n\n**Docs:** `https://docs.oneclickspaces.com`\n\n## Authentication\nAll authenticated endpoints require:\n```\nAuthorization: Bearer {{access_token}}\n```\n\n## Response Envelope\nAll responses follow this shape:\n```json\n{\n \"success\": true,\n \"message\": \"Human-readable status\",\n \"data\": { ... },\n \"errors\": null\n}\n```\n\n## Roles\n| Role | Access |\n|------|--------|\n| `user` | Browse, book, and host (when approved) |\n| `admin` | Full platform management |\n| `superadmin` | All permissions + Django admin |\n\n## Rate Limits\n- Anonymous: 30 req/min\n- Authenticated: 200 req/min\n\n## Download\nGrab the latest collection + environment at https://docs.oneclickspaces.com/postman", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{access_token}}", "type": "string" } ] }, "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "" ] } } ], "variable": [ { "key": "base_url", "value": "https://api.oneclickspaces.com" } ], "item": [ { "name": "Authentication", "description": "User registration, login, OTP verification, password management, and profile.", "item": [ { "name": "Register", "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"email\": \"john@example.com\",\n \"password\": \"SecurePass@123\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"phone_number\": \"+255712345678\"\n}" }, "url": { "raw": "{{base_url}}/api/auth/register/", "host": [ "{{base_url}}" ], "path": [ "api", "auth", "register", "" ] }, "description": "Create a new user account. An OTP is sent to the provided email (and phone if supplied). `role` defaults to `user`." } }, { "name": "Login", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "var json = pm.response.json();", "if (json.success && json.data) {", " pm.environment.set('access_token', json.data.access);", " pm.environment.set('refresh_token', json.data.refresh);", "}" ] } } ], "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"email\": \"john@example.com\",\n \"password\": \"SecurePass@123\"\n}" }, "url": { "raw": "{{base_url}}/api/auth/login/", "host": [ "{{base_url}}" ], "path": [ "api", "auth", "login", "" ] }, "description": "Login with email or phone number. The test script auto-saves `access_token` and `refresh_token` to the environment." } }, { "name": "Logout", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"refresh\": \"{{refresh_token}}\"\n}" }, "url": { "raw": "{{base_url}}/api/auth/logout/", "host": [ "{{base_url}}" ], "path": [ "api", "auth", "logout", "" ] }, "description": "Blacklists the refresh token. Pass the refresh token in the body." } }, { "name": "Refresh Token", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "var json = pm.response.json();", "if (json.success && json.data) {", " pm.environment.set('access_token', json.data.access);", "}" ] } } ], "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"refresh\": \"{{refresh_token}}\"\n}" }, "url": { "raw": "{{base_url}}/api/auth/refresh/", "host": [ "{{base_url}}" ], "path": [ "api", "auth", "refresh", "" ] }, "description": "Exchange a valid refresh token for a new access token." } }, { "name": "Verify Email OTP", "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"email\": \"john@example.com\",\n \"otp_code\": \"123456\"\n}" }, "url": { "raw": "{{base_url}}/api/auth/verify-email/", "host": [ "{{base_url}}" ], "path": [ "api", "auth", "verify-email", "" ] }, "description": "Verify the 6-digit OTP sent to the user's email after registration." } }, { "name": "Verify Phone OTP", "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"phone_number\": \"+255712345678\",\n \"otp_code\": \"123456\"\n}" }, "url": { "raw": "{{base_url}}/api/auth/verify-phone/", "host": [ "{{base_url}}" ], "path": [ "api", "auth", "verify-phone", "" ] }, "description": "Verify the 6-digit OTP sent to the user's phone number via SMS." } }, { "name": "Resend OTP", "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"email\": \"john@example.com\",\n \"purpose\": \"email_verification\"\n}" }, "url": { "raw": "{{base_url}}/api/auth/resend-otp/", "host": [ "{{base_url}}" ], "path": [ "api", "auth", "resend-otp", "" ] }, "description": "Resend an OTP. `purpose` options: `email_verification`, `phone_verification`, `password_reset`." } }, { "name": "Forgot Password", "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"email\": \"john@example.com\"\n}" }, "url": { "raw": "{{base_url}}/api/auth/forgot-password/", "host": [ "{{base_url}}" ], "path": [ "api", "auth", "forgot-password", "" ] }, "description": "Sends a password reset OTP to the given email." } }, { "name": "Reset Password", "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"email\": \"john@example.com\",\n \"otp_code\": \"123456\",\n \"new_password\": \"NewSecurePass@123\"\n}" }, "url": { "raw": "{{base_url}}/api/auth/reset-password/", "host": [ "{{base_url}}" ], "path": [ "api", "auth", "reset-password", "" ] }, "description": "Reset password using the OTP received via email." } }, { "name": "Change Password", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"old_password\": \"OldPass@123\",\n \"new_password\": \"NewPass@123\"\n}" }, "url": { "raw": "{{base_url}}/api/auth/change-password/", "host": [ "{{base_url}}" ], "path": [ "api", "auth", "change-password", "" ] }, "description": "Change password for the authenticated user." } }, { "name": "Get Profile", "request": { "method": "GET", "url": { "raw": "{{base_url}}/api/auth/profile/", "host": [ "{{base_url}}" ], "path": [ "api", "auth", "profile", "" ] }, "description": "Returns the authenticated user's full profile including role, mode, verification stage, and host onboarding status." } }, { "name": "Update Profile", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"phone_number\": \"+255712345678\",\n \"bio\": \"Space enthusiast and Airbnb host.\"\n}" }, "url": { "raw": "{{base_url}}/api/auth/update-profile/", "host": [ "{{base_url}}" ], "path": [ "api", "auth", "update-profile", "" ] }, "description": "Update basic profile fields. Use PATCH for partial updates." } }, { "name": "Toggle Mode", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"mode\": \"hosting\"\n}" }, "url": { "raw": "{{base_url}}/api/auth/mode/", "host": [ "{{base_url}}" ], "path": [ "api", "auth", "mode", "" ] }, "description": "Switch between `hosting` and `booking` mode. This is a UI routing hint stored server-side — it does not affect API permissions." } }, { "name": "Verification Status", "request": { "method": "GET", "url": { "raw": "{{base_url}}/api/auth/verification-status/", "host": [ "{{base_url}}" ], "path": [ "api", "auth", "verification-status", "" ] }, "description": "Returns the current verification stage of the authenticated user." } }, { "name": "Deactivate Account", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"password\": \"CurrentPass@123\"\n}" }, "url": { "raw": "{{base_url}}/api/auth/deactivate-account/", "host": [ "{{base_url}}" ], "path": [ "api", "auth", "deactivate-account", "" ] }, "description": "Soft-deactivates the authenticated user's account. Requires password confirmation." } } ] }, { "name": "Host Onboarding", "description": "Step-by-step host profile completion and submission for admin review.", "item": [ { "name": "Host Onboarding Status", "request": { "method": "GET", "url": { "raw": "{{base_url}}/api/auth/host/status/", "host": [ "{{base_url}}" ], "path": [ "api", "auth", "host", "status", "" ] }, "description": "Returns a checklist of completed and pending steps in the host onboarding flow." } }, { "name": "Save Personal Info", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"phone_number\": \"+255712345678\",\n \"date_of_birth\": \"1990-05-15\",\n \"gender\": \"male\"\n}" }, "url": { "raw": "{{base_url}}/api/auth/host/personal/", "host": [ "{{base_url}}" ], "path": [ "api", "auth", "host", "personal", "" ] }, "description": "Step 1 of host onboarding — save personal information." } }, { "name": "Save Identity (NIDA)", "request": { "method": "PATCH", "header": [], "body": { "mode": "formdata", "formdata": [ { "key": "nida_number", "value": "19901234567890123456", "type": "text" }, { "key": "id_photo", "src": "", "type": "file", "description": "Photo of government-issued ID" } ] }, "url": { "raw": "{{base_url}}/api/auth/host/identity/", "host": [ "{{base_url}}" ], "path": [ "api", "auth", "host", "identity", "" ] }, "description": "Step 2 — upload NIDA number and a photo of the government-issued ID document." } }, { "name": "Complete Host Profile", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"profile_completed\": true\n}" }, "url": { "raw": "{{base_url}}/api/auth/complete-profile/", "host": [ "{{base_url}}" ], "path": [ "api", "auth", "complete-profile", "" ] }, "description": "Marks the host profile as complete. Required before listing creation is allowed." } }, { "name": "Submit Host Profile for Review", "request": { "method": "POST", "header": [], "body": { "mode": "raw", "raw": "{}" }, "url": { "raw": "{{base_url}}/api/auth/host/submit/", "host": [ "{{base_url}}" ], "path": [ "api", "auth", "host", "submit", "" ] }, "description": "Submits the host profile for admin review. Sets `verification_stage` to `pending_review`." } } ] }, { "name": "OAuth / Providers", "description": "Social login via Google OAuth2 and Apple Sign-In.", "item": [ { "name": "Google Login", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "var json = pm.response.json();", "if (json.success && json.data) {", " pm.environment.set('access_token', json.data.access);", " pm.environment.set('refresh_token', json.data.refresh);", "}" ] } } ], "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"id_token\": \"\"\n}" }, "url": { "raw": "{{base_url}}/api/auth/providers/google/", "host": [ "{{base_url}}" ], "path": [ "api", "auth", "providers", "google", "" ] }, "description": "Verify a Google ID token from the frontend. Creates a new user or logs in an existing one. Returns JWT tokens identical to the standard login response." } }, { "name": "Apple Sign-In (stub)", "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"id_token\": \"\"\n}" }, "url": { "raw": "{{base_url}}/api/auth/providers/apple/", "host": [ "{{base_url}}" ], "path": [ "api", "auth", "providers", "apple", "" ] }, "description": "Apple Sign-In — returns 501 Not Implemented. Coming soon." } } ] }, { "name": "Listings", "description": "Create, manage, and browse space listings. Hosts manage their own listings. Customers browse publicly available listings.", "item": [ { "name": "Browse Listings (Public)", "request": { "auth": { "type": "noauth" }, "method": "GET", "url": { "raw": "{{base_url}}/api/listings/?category=villa&min_price=50&max_price=500&guests=4&stay_type=short_stay", "host": [ "{{base_url}}" ], "path": [ "api", "listings", "" ], "query": [ { "key": "category", "value": "villa", "description": "Filter by category slug" }, { "key": "min_price", "value": "50" }, { "key": "max_price", "value": "500" }, { "key": "guests", "value": "4" }, { "key": "stay_type", "value": "short_stay", "description": "short_stay | long_stay | both" }, { "key": "check_in", "value": "", "disabled": true }, { "key": "check_out", "value": "", "disabled": true } ] }, "description": "Public endpoint. Returns all active listings. Supports filtering by category, price range, guest count, stay type, and date availability." } }, { "name": "Create Draft Listing", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"title\": \"Luxury Beach Villa\",\n \"property_type\": \"villa\",\n \"category\": \"beach-villa\",\n \"stay_type\": \"short_stay\",\n \"description\": \"Stunning 3-bedroom beach villa with private pool.\",\n \"address\": \"Msasani Peninsula, Dar es Salaam\",\n \"city\": \"Dar es Salaam\",\n \"country\": \"Tanzania\",\n \"price_per_night\": \"350.00\",\n \"max_guests\": 6,\n \"bedrooms\": 3,\n \"bathrooms\": 2\n}" }, "url": { "raw": "{{base_url}}/api/listings/", "host": [ "{{base_url}}" ], "path": [ "api", "listings", "" ] }, "description": "Create a new listing draft. Requires the user to be an approved host (`verification_stage=approved` and `profile_completed=true`). Returns the new listing ID — save it as `{{listing_id}}`." } }, { "name": "Get Listing Detail", "request": { "auth": { "type": "noauth" }, "method": "GET", "url": { "raw": "{{base_url}}/api/listings/{{listing_id}}/", "host": [ "{{base_url}}" ], "path": [ "api", "listings", "{{listing_id}}", "" ] }, "description": "Get full detail for a single listing including photos, amenities, extras, pricing, and reviews summary." } }, { "name": "Host's Own Listings", "request": { "method": "GET", "url": { "raw": "{{base_url}}/api/listings/host/", "host": [ "{{base_url}}" ], "path": [ "api", "listings", "host", "" ] }, "description": "Returns all listings belonging to the authenticated host, across all statuses (draft, pending, active, rejected)." } }, { "name": "Nearby Listings", "request": { "auth": { "type": "noauth" }, "method": "GET", "url": { "raw": "{{base_url}}/api/listings/nearby/?lat=-6.7924&lng=39.2083&radius=10", "host": [ "{{base_url}}" ], "path": [ "api", "listings", "nearby", "" ], "query": [ { "key": "lat", "value": "-6.7924" }, { "key": "lng", "value": "39.2083" }, { "key": "radius", "value": "10", "description": "Radius in km" } ] }, "description": "Returns active listings within a given radius (km) of the provided coordinates." } }, { "name": "Update Basic Info", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"title\": \"Updated Villa Name\",\n \"description\": \"Updated description.\",\n \"max_guests\": 8\n}" }, "url": { "raw": "{{base_url}}/api/listings/{{listing_id}}/basic-info/", "host": [ "{{base_url}}" ], "path": [ "api", "listings", "{{listing_id}}", "basic-info", "" ] }, "description": "Partial update of basic listing information (title, description, address, guests, etc.)." } }, { "name": "Update Amenities", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"amenities\": [\"wifi\", \"pool\", \"parking\"],\n \"extras\": [\n { \"extra_id\": \"airport-transfer\", \"price\": \"25.00\" },\n { \"extra_id\": \"breakfast\", \"price\": \"15.00\" }\n ]\n}" }, "url": { "raw": "{{base_url}}/api/listings/{{listing_id}}/amenities/", "host": [ "{{base_url}}" ], "path": [ "api", "listings", "{{listing_id}}", "amenities", "" ] }, "description": "Replace the listing's amenity set and optional paid extras." } }, { "name": "Update Pricing", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"price_per_night\": \"400.00\",\n \"cleaning_fee\": \"50.00\",\n \"security_deposit\": \"200.00\",\n \"min_stay_nights\": 2\n}" }, "url": { "raw": "{{base_url}}/api/listings/{{listing_id}}/pricing/", "host": [ "{{base_url}}" ], "path": [ "api", "listings", "{{listing_id}}", "pricing", "" ] }, "description": "Update pricing, cleaning fee, security deposit, and minimum stay." } }, { "name": "Upload Media", "request": { "method": "POST", "header": [], "body": { "mode": "formdata", "formdata": [ { "key": "images", "src": "", "type": "file", "description": "Upload one or more listing photos" }, { "key": "is_cover", "value": "true", "type": "text" } ] }, "url": { "raw": "{{base_url}}/api/listings/{{listing_id}}/media/", "host": [ "{{base_url}}" ], "path": [ "api", "listings", "{{listing_id}}", "media", "" ] }, "description": "Upload photos for the listing. Files are stored in MinIO/S3. Set `is_cover=true` to mark the cover image." } }, { "name": "Update Availability", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"check_in_time\": \"14:00\",\n \"check_out_time\": \"11:00\",\n \"blackout_dates\": [\"2026-12-25\", \"2026-12-26\"]\n}" }, "url": { "raw": "{{base_url}}/api/listings/{{listing_id}}/availability/", "host": [ "{{base_url}}" ], "path": [ "api", "listings", "{{listing_id}}", "availability", "" ] }, "description": "Set check-in/check-out times and manually block specific dates." } }, { "name": "Submit Listing for Review", "request": { "method": "POST", "body": { "mode": "raw", "raw": "{}" }, "url": { "raw": "{{base_url}}/api/listings/{{listing_id}}/submit/", "host": [ "{{base_url}}" ], "path": [ "api", "listings", "{{listing_id}}", "submit", "" ] }, "description": "Submit a completed draft for admin approval. Status changes from `draft` to `pending_review`." } }, { "name": "Delete Listing", "request": { "method": "DELETE", "url": { "raw": "{{base_url}}/api/listings/{{listing_id}}/delete/", "host": [ "{{base_url}}" ], "path": [ "api", "listings", "{{listing_id}}", "delete", "" ] }, "description": "Delete a listing. Only allowed when status is `draft` or `inactive`." } }, { "name": "List Amenities Catalog", "request": { "auth": { "type": "noauth" }, "method": "GET", "url": { "raw": "{{base_url}}/api/listings/amenities/", "host": [ "{{base_url}}" ], "path": [ "api", "listings", "amenities", "" ] }, "description": "Returns the full platform amenity catalog (WiFi, Pool, Parking, etc.)." } }, { "name": "List Extras Catalog", "request": { "auth": { "type": "noauth" }, "method": "GET", "url": { "raw": "{{base_url}}/api/listings/extras/", "host": [ "{{base_url}}" ], "path": [ "api", "listings", "extras", "" ] }, "description": "Returns all available paid extras that hosts can attach to their listings." } } ] }, { "name": "Bookings", "description": "Full booking lifecycle: intent creation (inventory hold) → confirmation → check-in → check-out.", "item": [ { "name": "Create Booking Intent", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "var json = pm.response.json();", "if (json.success && json.data) {", " pm.environment.set('intent_id', json.data.id);", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"listing_id\": \"{{listing_id}}\",\n \"check_in_date\": \"2026-09-01\",\n \"check_out_date\": \"2026-09-05\",\n \"guests\": 2,\n \"extras\": []\n}" }, "url": { "raw": "{{base_url}}/api/bookings/intents/", "host": [ "{{base_url}}" ], "path": [ "api", "bookings", "intents", "" ] }, "description": "Creates a booking intent and places a 15-minute hold on the requested dates. Returns a price snapshot and intent ID. Save the response `id` as `{{intent_id}}`." } }, { "name": "Get Booking Intent", "request": { "method": "GET", "url": { "raw": "{{base_url}}/api/bookings/intents/{{intent_id}}/", "host": [ "{{base_url}}" ], "path": [ "api", "bookings", "intents", "{{intent_id}}", "" ] }, "description": "Returns the intent details including `expires_at` timestamp showing when the hold expires." } }, { "name": "Confirm Booking", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "var json = pm.response.json();", "if (json.success && json.data) {", " pm.environment.set('booking_id', json.data.id);", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"intent_id\": \"{{intent_id}}\",\n \"special_requests\": \"Late check-in at 6pm please.\"\n}" }, "url": { "raw": "{{base_url}}/api/bookings/create/", "host": [ "{{base_url}}" ], "path": [ "api", "bookings", "create", "" ] }, "description": "Convert a valid (non-expired) intent into a confirmed booking. Dates are locked in `BookedDate` table to prevent double-booking." } }, { "name": "List My Bookings", "request": { "method": "GET", "url": { "raw": "{{base_url}}/api/bookings/", "host": [ "{{base_url}}" ], "path": [ "api", "bookings", "" ] }, "description": "Returns all bookings visible to the authenticated user. Guests see their own bookings. Hosts see bookings on their listings." } }, { "name": "Get Booking Detail", "request": { "method": "GET", "url": { "raw": "{{base_url}}/api/bookings/{{booking_id}}/", "host": [ "{{base_url}}" ], "path": [ "api", "bookings", "{{booking_id}}", "" ] }, "description": "Full booking detail including status history/events, listing snapshot, price breakdown, and payment status." } }, { "name": "Submit Payment Proof", "request": { "method": "PATCH", "header": [], "body": { "mode": "formdata", "formdata": [ { "key": "payment_proof", "src": "", "type": "file" }, { "key": "payment_method", "value": "bank_transfer", "type": "text" } ] }, "url": { "raw": "{{base_url}}/api/bookings/{{booking_id}}/submit-payment/", "host": [ "{{base_url}}" ], "path": [ "api", "bookings", "{{booking_id}}", "submit-payment", "" ] }, "description": "Upload payment receipt/screenshot. Changes booking status to `payment_submitted` for admin review." } }, { "name": "Cancel Booking", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"reason\": \"Change of plans.\"\n}" }, "url": { "raw": "{{base_url}}/api/bookings/{{booking_id}}/cancel/", "host": [ "{{base_url}}" ], "path": [ "api", "bookings", "{{booking_id}}", "cancel", "" ] }, "description": "Cancel a booking. Releases the held dates back to availability." } }, { "name": "Mark Check-In (Host)", "request": { "method": "PATCH", "body": { "mode": "raw", "raw": "{}" }, "url": { "raw": "{{base_url}}/api/bookings/{{booking_id}}/check-in/", "host": [ "{{base_url}}" ], "path": [ "api", "bookings", "{{booking_id}}", "check-in", "" ] }, "description": "Host confirms the guest has checked in. Changes status from `confirmed` to `checked_in`." } }, { "name": "Mark Check-Out (Host)", "request": { "method": "PATCH", "body": { "mode": "raw", "raw": "{}" }, "url": { "raw": "{{base_url}}/api/bookings/{{booking_id}}/check-out/", "host": [ "{{base_url}}" ], "path": [ "api", "bookings", "{{booking_id}}", "check-out", "" ] }, "description": "Host marks the stay as complete. Status moves to `completed`. Triggers a review request notification to the guest (24h delay)." } } ] }, { "name": "Categories", "description": "Hierarchical space type taxonomy (e.g. Villa > Beach Villa). Public read, admin write.", "item": [ { "name": "List Categories (Public)", "request": { "auth": { "type": "noauth" }, "method": "GET", "url": { "raw": "{{base_url}}/api/categories/", "host": [ "{{base_url}}" ], "path": [ "api", "categories", "" ] }, "description": "Returns all active parent categories with their subcategories nested." } }, { "name": "Get Category Detail", "request": { "auth": { "type": "noauth" }, "method": "GET", "url": { "raw": "{{base_url}}/api/categories/{{category_slug}}/", "host": [ "{{base_url}}" ], "path": [ "api", "categories", "{{category_slug}}", "" ] }, "description": "Returns a single category with all its children." } }, { "name": "Create Category (Admin)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Beach Villa\",\n \"parent\": \"villa\",\n \"icon\": \"beach\",\n \"description\": \"Luxury villas by the beach.\",\n \"sort_order\": 1\n}" }, "url": { "raw": "{{base_url}}/api/categories/", "host": [ "{{base_url}}" ], "path": [ "api", "categories", "" ] }, "description": "Admin only. Create a new category. `parent` is the slug of the parent category (omit for top-level)." } }, { "name": "Update Category (Admin)", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Updated Name\",\n \"is_active\": true\n}" }, "url": { "raw": "{{base_url}}/api/categories/{{category_slug}}/", "host": [ "{{base_url}}" ], "path": [ "api", "categories", "{{category_slug}}", "" ] }, "description": "Admin only. Partial update of a category." } }, { "name": "Delete Category (Admin)", "request": { "method": "DELETE", "url": { "raw": "{{base_url}}/api/categories/{{category_slug}}/", "host": [ "{{base_url}}" ], "path": [ "api", "categories", "{{category_slug}}", "" ] }, "description": "Admin only. Soft-deletes a category (sets `is_active=false`)." } }, { "name": "All Categories (Admin)", "request": { "method": "GET", "url": { "raw": "{{base_url}}/api/categories/all/", "host": [ "{{base_url}}" ], "path": [ "api", "categories", "all", "" ] }, "description": "Admin only. Returns all categories including inactive ones." } } ] }, { "name": "Amenities & Extras", "description": "Platform-wide amenity and paid extra catalog. Public read, admin write.", "item": [ { "name": "List Amenities", "request": { "auth": { "type": "noauth" }, "method": "GET", "url": { "raw": "{{base_url}}/api/amenities/", "host": [ "{{base_url}}" ], "path": [ "api", "amenities", "" ] } } }, { "name": "Create Amenity (Admin)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Swimming Pool\",\n \"icon\": \"pool\",\n \"category\": \"outdoor\"\n}" }, "url": { "raw": "{{base_url}}/api/amenities/", "host": [ "{{base_url}}" ], "path": [ "api", "amenities", "" ] } } }, { "name": "Get Amenity", "request": { "auth": { "type": "noauth" }, "method": "GET", "url": { "raw": "{{base_url}}/api/amenities/{{amenity_id}}/", "host": [ "{{base_url}}" ], "path": [ "api", "amenities", "{{amenity_id}}", "" ] } } }, { "name": "Update Amenity (Admin)", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Heated Pool\"\n}" }, "url": { "raw": "{{base_url}}/api/amenities/{{amenity_id}}/", "host": [ "{{base_url}}" ], "path": [ "api", "amenities", "{{amenity_id}}", "" ] } } }, { "name": "Delete Amenity (Admin)", "request": { "method": "DELETE", "url": { "raw": "{{base_url}}/api/amenities/{{amenity_id}}/", "host": [ "{{base_url}}" ], "path": [ "api", "amenities", "{{amenity_id}}", "" ] } } }, { "name": "List Extras", "request": { "auth": { "type": "noauth" }, "method": "GET", "url": { "raw": "{{base_url}}/api/amenities/extras/", "host": [ "{{base_url}}" ], "path": [ "api", "amenities", "extras", "" ] } } }, { "name": "Create Extra (Admin)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Airport Transfer\",\n \"icon\": \"car\",\n \"description\": \"One-way airport pickup\"\n}" }, "url": { "raw": "{{base_url}}/api/amenities/extras/", "host": [ "{{base_url}}" ], "path": [ "api", "amenities", "extras", "" ] } } }, { "name": "Update Extra (Admin)", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Airport Pickup & Drop\"\n}" }, "url": { "raw": "{{base_url}}/api/amenities/extras/{{extra_id}}/", "host": [ "{{base_url}}" ], "path": [ "api", "amenities", "extras", "{{extra_id}}", "" ] } } }, { "name": "Delete Extra (Admin)", "request": { "method": "DELETE", "url": { "raw": "{{base_url}}/api/amenities/extras/{{extra_id}}/", "host": [ "{{base_url}}" ], "path": [ "api", "amenities", "extras", "{{extra_id}}", "" ] } } } ] }, { "name": "Reviews", "description": "Listing reviews (one per completed booking) and platform app reviews.", "item": [ { "name": "Get Listing Reviews (Public)", "request": { "auth": { "type": "noauth" }, "method": "GET", "url": { "raw": "{{base_url}}/api/reviews/listings/{{listing_id}}/", "host": [ "{{base_url}}" ], "path": [ "api", "reviews", "listings", "{{listing_id}}", "" ] }, "description": "Returns all published reviews for a listing. Includes sub-ratings and host replies." } }, { "name": "Submit Listing Review", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"booking_id\": \"{{booking_id}}\",\n \"rating\": 5,\n \"cleanliness\": 5,\n \"communication\": 5,\n \"location\": 4,\n \"value\": 4,\n \"accuracy\": 5,\n \"comment\": \"Absolutely stunning villa. Would book again!\"\n}" }, "url": { "raw": "{{base_url}}/api/reviews/listings/{{listing_id}}/", "host": [ "{{base_url}}" ], "path": [ "api", "reviews", "listings", "{{listing_id}}", "" ] }, "description": "Submit a review for a completed booking. One review per booking. Must be the customer on that booking." } }, { "name": "Host Reply to Review", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"host_reply\": \"Thank you so much! We loved having you. Come back anytime!\"\n}" }, "url": { "raw": "{{base_url}}/api/reviews/{{review_id}}/reply/", "host": [ "{{base_url}}" ], "path": [ "api", "reviews", "{{review_id}}", "reply", "" ] }, "description": "Host posts a one-time reply to a review on their listing." } }, { "name": "Submit App Review", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"rating\": 5,\n \"comment\": \"Seamless experience, love the booking flow!\",\n \"platform\": \"web\"\n}" }, "url": { "raw": "{{base_url}}/api/reviews/app/", "host": [ "{{base_url}}" ], "path": [ "api", "reviews", "app", "" ] }, "description": "Submit a platform feedback review. One per user (updating your existing review is allowed). Not shown publicly — only visible to admin." } } ] }, { "name": "Saved Searches", "description": "Save and manage listing search filters for quick re-use.", "item": [ { "name": "List Saved Searches", "request": { "method": "GET", "url": { "raw": "{{base_url}}/api/filters/saved/", "host": [ "{{base_url}}" ], "path": [ "api", "filters", "saved", "" ] } } }, { "name": "Save a Search", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Dar Beach Getaway\",\n \"category\": \"beach-villa\",\n \"min_price\": 100,\n \"max_price\": 400,\n \"min_guests\": 2,\n \"stay_type\": \"short_stay\"\n}" }, "url": { "raw": "{{base_url}}/api/filters/saved/", "host": [ "{{base_url}}" ], "path": [ "api", "filters", "saved", "" ] } } }, { "name": "Delete Saved Search", "request": { "method": "DELETE", "url": { "raw": "{{base_url}}/api/filters/saved/{{search_id}}/", "host": [ "{{base_url}}" ], "path": [ "api", "filters", "saved", "{{search_id}}", "" ] } } } ] }, { "name": "FAQ", "description": "Frequently asked questions, grouped by category.", "item": [ { "name": "Get FAQs (Public)", "request": { "auth": { "type": "noauth" }, "method": "GET", "url": { "raw": "{{base_url}}/api/faq/", "host": [ "{{base_url}}" ], "path": [ "api", "faq", "" ] }, "description": "Returns all active FAQs grouped by category. No authentication required." } } ] }, { "name": "Admin Portal", "description": "Admin and superadmin only. Platform management: listings, users, bookings, reviews, and dashboard stats.\n\nAll endpoints require `role=admin` or `is_superuser=true`.", "item": [ { "name": "Dashboard Stats", "request": { "method": "GET", "url": { "raw": "{{base_url}}/api/admin/stats/", "host": [ "{{base_url}}" ], "path": [ "api", "admin", "stats", "" ] }, "description": "Returns counts: total users, active listings, total bookings, bookings this month, pending host applications, pending listings." } }, { "name": "List All Listings", "request": { "method": "GET", "url": { "raw": "{{base_url}}/api/admin/listings/?status=pending_review", "host": [ "{{base_url}}" ], "path": [ "api", "admin", "listings", "" ], "query": [ { "key": "status", "value": "pending_review", "description": "Filter: draft | pending_review | active | rejected | inactive" } ] }, "description": "All listings across all hosts and all statuses. Filterable by `status`." } }, { "name": "Create Listing as Admin", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"title\": \"Admin-Managed Penthouse\",\n \"property_type\": \"apartment\",\n \"category\": \"short-stay\",\n \"description\": \"Platform-owned premium penthouse.\",\n \"address\": \"Oyster Bay, Dar es Salaam\",\n \"city\": \"Dar es Salaam\",\n \"country\": \"Tanzania\",\n \"price_per_night\": \"250.00\",\n \"max_guests\": 4,\n \"bedrooms\": 2,\n \"bathrooms\": 1\n}" }, "url": { "raw": "{{base_url}}/api/admin/listings/", "host": [ "{{base_url}}" ], "path": [ "api", "admin", "listings", "" ] }, "description": "Admin creates a listing on behalf of the platform. Auto-assigns host as the admin user. Bypasses the host eligibility gate." } }, { "name": "Get Listing (Admin View)", "request": { "method": "GET", "url": { "raw": "{{base_url}}/api/admin/listings/{{listing_id}}/", "host": [ "{{base_url}}" ], "path": [ "api", "admin", "listings", "{{listing_id}}", "" ] }, "description": "Full listing detail with admin action history (who approved/rejected, when, with what reason)." } }, { "name": "Approve Listing", "request": { "method": "PATCH", "body": { "mode": "raw", "raw": "{}" }, "url": { "raw": "{{base_url}}/api/admin/listings/{{listing_id}}/approve/", "host": [ "{{base_url}}" ], "path": [ "api", "admin", "listings", "{{listing_id}}", "approve", "" ] }, "description": "Approve a `pending_review` listing. Sets status to `active` and makes it visible in browse. Notifies the host." } }, { "name": "Reject Listing", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"rejection_reason\": \"Photos are too low quality. Please re-upload with better lighting.\"\n}" }, "url": { "raw": "{{base_url}}/api/admin/listings/{{listing_id}}/reject/", "host": [ "{{base_url}}" ], "path": [ "api", "admin", "listings", "{{listing_id}}", "reject", "" ] }, "description": "Reject a listing with a required reason. Notifies the host with the rejection reason." } }, { "name": "List All Users", "request": { "method": "GET", "url": { "raw": "{{base_url}}/api/admin/users/?role=user&verification_stage=pending_review", "host": [ "{{base_url}}" ], "path": [ "api", "admin", "users", "" ], "query": [ { "key": "role", "value": "user" }, { "key": "verification_stage", "value": "pending_review" } ] }, "description": "All users. Filter by `role` (user/admin/superadmin) or `verification_stage`." } }, { "name": "Get User Detail", "request": { "method": "GET", "url": { "raw": "{{base_url}}/api/admin/users/{{user_id}}/", "host": [ "{{base_url}}" ], "path": [ "api", "admin", "users", "{{user_id}}", "" ] } } }, { "name": "Update User", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"is_active\": true,\n \"role\": \"user\"\n}" }, "url": { "raw": "{{base_url}}/api/admin/users/{{user_id}}/", "host": [ "{{base_url}}" ], "path": [ "api", "admin", "users", "{{user_id}}", "" ] } } }, { "name": "Approve Host", "request": { "method": "POST", "body": { "mode": "raw", "raw": "{}" }, "url": { "raw": "{{base_url}}/api/admin/users/{{user_id}}/approve-host/", "host": [ "{{base_url}}" ], "path": [ "api", "admin", "users", "{{user_id}}", "approve-host", "" ] }, "description": "Approve a host application. Sets `verification_stage=approved`. The user can now create listings." } }, { "name": "Reject Host", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"rejection_reason\": \"ID document is not legible.\"\n}" }, "url": { "raw": "{{base_url}}/api/admin/users/{{user_id}}/reject-host/", "host": [ "{{base_url}}" ], "path": [ "api", "admin", "users", "{{user_id}}", "reject-host", "" ] } } }, { "name": "List All Bookings", "request": { "method": "GET", "url": { "raw": "{{base_url}}/api/admin/bookings/?status=payment_submitted", "host": [ "{{base_url}}" ], "path": [ "api", "admin", "bookings", "" ], "query": [ { "key": "status", "value": "payment_submitted" } ] } } }, { "name": "Confirm Payment", "request": { "method": "PATCH", "body": { "mode": "raw", "raw": "{}" }, "url": { "raw": "{{base_url}}/api/admin/bookings/{{booking_id}}/confirm-payment/", "host": [ "{{base_url}}" ], "path": [ "api", "admin", "bookings", "{{booking_id}}", "confirm-payment", "" ] }, "description": "Admin confirms payment receipt. Status moves to `confirmed`. Notifies host and guest." } }, { "name": "Unpublish Review", "request": { "method": "PATCH", "body": { "mode": "raw", "raw": "{}" }, "url": { "raw": "{{base_url}}/api/admin/reviews/{{review_id}}/unpublish/", "host": [ "{{base_url}}" ], "path": [ "api", "admin", "reviews", "{{review_id}}", "unpublish", "" ] }, "description": "Hide a review from public view. Listing's `rating_avg` and `rating_count` are recalculated." } }, { "name": "SMS Credit Balance", "request": { "method": "GET", "url": { "raw": "{{base_url}}/api/admin/sms/balance/", "host": [ "{{base_url}}" ], "path": [ "api", "admin", "sms", "balance", "" ] }, "description": "Returns current SendAfrica SMS credit balance." } } ] } ] }