API Documentation - AaoStays

#Api document for property entity

Base URL: [Link]

Authentication: JWT (required for Host, Employee, or Admin

operations)

Content-Type: application/json

Entity: PROPERTY

The Property API manages property listings on AaoStays.

It allows hosts and admins to create, update, and retrieve property

details, including location, amenities, pricing, and [Link]
Property API manages property listings on AaoStays.

It allows hosts and admins to create, update, and retrieve property

details, including location, amenities, pricing, and policies.

A Host (host_id) — the owner of the listing

Request Type: POST

controller method API: addProperty(PropertyDto propertyDto)

"hostId": 101,

"propertyName": "The South Villa",

"propertyType": "Entire Place",

"categoryType": "Luxury",

"description": "A stunning beachfront villa with private pool.",

"addressLine1": "Beach Road, Candolim",

"city": "Goa",

"state": "Goa",

"country": "India",

"postalCode": "403515",

"latitude": 15.5187,

"longitude": 73.7596,

"baseGuests": 2,

"maxGuests": 4,

"extraGuestAllowed": true,

"extraGuestFee": 500.00,

"bedrooms": 2,

"beds": 3,

"bathrooms": 2,

"kitchenType": "Full Kitchen",

"petsAllowed": false,

"smokingAllowed": false,
"eventsAllowed": true,

"pricePerNight": 8500.00,

"cleaningFee": 500.00,

"serviceFee": 200.00,

"currency": "INR",

"minimumStay": 2,

"maximumStay": 30,

"checkInTime": "14:00:00",

"checkOutTime": "11:00:00",

"cancellationPolicy": "MODERATE",

"instantBooking": false,

"propertyStatus": "PENDING_APPROVAL",

"approvalStatus": "PENDING",

"isActive": true,

"isFeatured": false

201 Created

When the property is successfully created and stored in the

database.

Example Response:
{

"status": 201,

"message": "Property created successfully",

"data": {

"propertyId": 501,

"propertyName": "The South Villa",

"propertyStatus": "PENDING_APPROVAL",

"approvalStatus": "PENDING",

"createdAt": "2025-11-10T14:12:45Z"

Meaning:

The property was added correctly.

Initial status is usually PENDING_APPROVAL or DRAFT.

propertyId is returned for reference.

400 Bad Request

Returned when mandatory fields are missing, validation fails, or

invalid data type.

"status": 400,
"message": "Validation failed: propertyName must not be blank"

401 Unauthorized

Returned when the request is made without a valid JWT token.

"status": 401,

"message": "Unauthorized access. Please login to continue."

Meaning:

User must be logged in and token must be sent in Authorization

header.

403 Forbidden

Returned when a user tries to add a property but doesn’t have

permission (e.g. a normal guest).

"status": 403,

"message": "Access denied. Only hosts or admins can create

properties."

409 Conflict
Returned when a duplicate property (same name + address) already
exists.

"status": 409,

"message": "Property already exists with the same name and

address."

500 Internal Server Error

Returned for any unhandled error while saving to the database.

"status": 500,

"message": "An unexpected error occurred while saving property.

Please try again later."

Meaning:

Database issue, null pointer, or unexpected backend failure.

503 Service Unavailable

If your backend service (e.g. image upload, location service) is

down temporarily.

"status": 503,
"message": "Service temporarily unavailable. Please try again
later."

------------------------------------------------------------------------------

getAllProperties()

Request Type: GET

Controller Method: getAllProperties()

Endpoint: /api/v1/properties

Description:

Fetches a list of all active properties. Supports filters (city,

category, price range, etc.) via query parameters.

200 OK

When properties are successfully fetched.

Example Response:

"status": 200,

"message": "Properties retrieved successfully",

"data": [

"propertyId": 501,
"propertyName": "The South Villa",

"city": "Goa",

"pricePerNight": 8500.00,

"currency": "INR",

"propertyStatus": "ACTIVE",

"ratingAverage": 4.9

},

"propertyId": 502,

"propertyName": "Hilltop Cottage",

"city": "Ooty",

"pricePerNight": 4500.00,

"currency": "INR",

"propertyStatus": "ACTIVE",

"ratingAverage": 4.7

Meaning:
All available properties were fetched successfully from the
database.

204 No Content

Returned if no properties exist or match the filters.

"status": 204,

"message": "No properties found"

500 Internal Server Error

If something goes wrong while retrieving data.

"status": 500,

"message": "An unexpected error occurred while fetching

properties."

getPropertyById(Long propertyId)

Request Type: GET

Controller Method: getPropertyById(Long propertyId)

Endpoint: /api/v1/properties/{propertyId}

Description:
Fetches the details of a single property by its ID.

200 OK

When the property exists.

Example Response:

"status": 200,

"message": "Property details retrieved successfully",

"data": {

"propertyId": 501,

"propertyName": "The South Villa",

"propertyType": "Entire Place",

"categoryType": "Luxury",

"description": "A stunning beachfront villa with private pool.",

"city": "Goa",

"state": "Goa",

"pricePerNight": 8500.00,

"currency": "INR",

"ratingAverage": 4.9,

"approvalStatus": "APPROVED",
"propertyStatus": "ACTIVE"

Meaning:

Property found and returned successfully.

404 Not Found

Returned if the property ID doesn’t exist.

"status": 404,

"message": "Property not found with ID: 501"

400 Bad Request

If the property ID is invalid (e.g., null or non-numeric).

"status": 400,

"message": "Invalid property ID provided"

500 Internal Server Error

If something fails during lookup.

{

"status": 500,

"message": "An unexpected error occurred while retrieving

property details."

updateProperty(Long propertyId, PropertyDto propertyDto)

Request Type: PUT

Controller Method: updateProperty(Long propertyId, PropertyDto

propertyDto)

Endpoint: /api/v1/properties/{propertyId}

Description:

Updates an existing property’s details by its ID (Host or Admin

only).

200 OK

When the property is successfully updated.

Example Request:

"pricePerNight": 9000.00,

"maxGuests": 5,

"description": "Updated: Includes free breakfast."

}
Example Response:

"status": 200,

"message": "Property updated successfully",

"data": {

"propertyId": 501,

"propertyName": "The South Villa",

"pricePerNight": 9000.00,

"maxGuests": 5,

"updatedAt": "2025-11-10T15:12:00Z"

Meaning:

The specified property details were successfully modified.

400 Bad Request

If validation fails or invalid fields are passed.

"status": 400,

"message": "Invalid request: pricePerNight must be greater than 0"

}

401 Unauthorized

If user is not logged in.

"status": 401,

"message": "Unauthorized access. Please login to update

properties."

403 Forbidden

If the logged-in user is not the property owner or admin.

"status": 403,

"message": "Access denied. You do not have permission to update

this property."

404 Not Found

If the property ID doesn’t exist.

"status": 404,

"message": "Property not found with ID: 501"

}

500 Internal Server Error

If there’s an unexpected database or server issue.

"status": 500,

"message": "An unexpected error occurred while updating

property."

deleteProperty(Long propertyId)

Request Type: DELETE

Controller Method: deleteProperty(Long propertyId)

Endpoint: /api/v1/properties/{propertyId}

Description:

Deletes (or deactivates) a property from the system (Admin or

Host only).

200 OK

When the property is deleted successfully.

Example Response:

"status": 200,
"message": "Property deleted successfully",

"data": {

"propertyId": 501,

"deletedAt": "2025-11-10T15:30:00Z"

Meaning:

The property was successfully deleted or marked inactive.

401 Unauthorized

If no valid token provided.

"status": 401,

"message": "Unauthorized access. Please login to delete

properties."

403 Forbidden

If the user does not have permission (e.g., trying to delete another
host’s property).

"status": 403,
"message": "Access denied. Only admins or property owners can
delete properties."

404 Not Found

If the property ID does not exist.

"status": 404,

"message": "Property not found with ID: 501"

500 Internal Server Error

If deletion fails due to server or database issues.

"status": 500,

"message": "An unexpected error occurred while deleting

property."

PROPERTY SEARCH AND FILTER API

DOCUMENTATION
Base URL: /api/v1/properties

Entity: PROPERTY
Description:

Handles property search and filtering based on city, state, type,

category, and price range.

1. Search Properties

Request Type: GET

Endpoint: /api/v1/properties/search

Description:

Searches properties dynamically using multiple optional filters

(city, state, property type, category, and price range).

Example Request

GET /api/v1/properties/search?
city=Goa&state=Goa&propertyType=Entire
%20Place&categoryType=Luxury&minPrice=3000&maxPrice=10
000

Request Parameters

Parameter Type Required Description

city String No Filter by city name

state String No Filter by state

propertyType String No e.g., Entire Place, Private Room

categoryType String No e.g., Luxury, Budget, Family

minPrice DoubleNo Minimum price per night

maxPrice DoubleNo Maximum price per night

200 OK

"status": 200,

"message": "Properties fetched successfully",

"data": [

"propertyId": 501,

"propertyName": "The South Villa",

"city": "Goa",

"state": "Goa",

"propertyType": "Entire Place",

"categoryType": "Luxury",

"pricePerNight": 8500.00,

"ratingAverage": 4.6

},

"propertyId": 502,

"propertyName": "Palm Beach House",

"city": "Goa",

"state": "Goa",

"propertyType": "Private Room",

"categoryType": "Luxury",

"pricePerNight": 6000.00,

"ratingAverage": 4.2

404 Not Found

"status": 404,

"message": "No properties found matching search criteria"

500 Internal Server Error

"status": 500,

"message": "Error occurred while fetching properties"

}
2. Filter by City

Request Type: GET

Endpoint: /api/v1/properties/filter/city/{city}

Description:

Fetches all properties in a specific city.

Example Request

GET /api/v1/properties/filter/city/Goa

200 OK

"status": 200,

"message": "Properties retrieved successfully for city: Goa",

"data": [

"propertyId": 501,

"propertyName": "The South Villa",

"propertyType": "Entire Place",

"pricePerNight": 8500.00,

"ratingAverage": 4.6

},
{

"propertyId": 503,

"propertyName": "Sunset Retreat",

"propertyType": "Private Room",

"pricePerNight": 5500.00,

"ratingAverage": 4.4

404 Not Found

"status": 404,

"message": "No properties found in city: Goa"

500 Internal Server Error

"status": 500,

"message": "Error occurred while filtering properties by city"

}
3. Filter by Price Range

Request Type: GET

Endpoint: /api/v1/properties/filter/price

Description:

Retrieves properties within a specific price range.

Example Request

GET /api/v1/properties/filter/price?
minPrice=3000&maxPrice=8000

Request Parameters

Parameter Type Required Description

minPrice DoubleNo Minimum price per night

maxPrice DoubleNo Maximum price per night

200 OK

"status": 200,

"message": "Properties filtered successfully by price range",

"data": [

"propertyId": 504,

"propertyName": "Urban Comfort Inn",

"pricePerNight": 3500.00,

"city": "Bangalore",

"propertyType": "Private Room"

},

"propertyId": 505,

"propertyName": "Blue Lagoon",

"pricePerNight": 7500.00,

"city": "Goa",

"propertyType": "Entire Place"

404 Not Found

"status": 404,

"message": "No properties found in the given price range"

500 Internal Server Error

{

"status": 500,

"message": "Error occurred while filtering properties by price

range"

NOMINATIM (OPENSTREETMAP) API DOCUMENTATION

Overview

Nominatim is a free, open-source geocoding service based on

OpenStreetMap (OSM) data.

It converts addresses → coordinates (latitude/longitude) and vice

versa (reverse geocoding).

It is completely free, requires no API key, and is perfect for small

to medium workloads.

API Base URL

[Link]

Endpoints

Type Endpoint Description

Forward Geocoding /search?q=<address>&format=json

Converts an address into latitude & longitude

Reverse Geocoding /reverse?lat=<lat>&lon=<lon>&format=json

Converts coordinates into a readable address

Example 1: Forward Geocoding

Request:

GET [Link]
q=Candolim,Goa,India&format=json

Response:

"place_id": 235405672,

"licence": "Data © OpenStreetMap contributors",

"lat": "15.5187111",

"lon": "73.7596",

"display_name": "Candolim, North Goa, Goa, India",

"type": "village",

"importance": 0.8175

Example 2: Reverse Geocoding

Request:

GET [Link]
lat=15.5187&lon=73.7596&format=json

Response:
{

"place_id": 287295616,

"lat": "15.5187",

"lon": "73.7596",

"display_name": "Candolim, North Goa, Goa, India",

"address": {

"village": "Candolim",

"county": "North Goa",

"state": "Goa",

"country": "India",

"country_code": "in"

Usage Policy (Important)

100% free and public

Limit: 1 request per second per IP (strict)

Must include a User-Agent header (identifies your app)

Example:

[Link]("User-Agent", "AaoStaysApp/1.0
(contact@[Link])");
If you need higher throughput later, you can self-host Nominatim
using OSM data.

AaoStays External API Integration

Category: Property Support Services

Includes: Map Display, Email Notifications, SMS Notifications,

Image Storage

Purpose:

These external APIs enhance property features with maps,

notifications, and media storage.

All listed services use free tiers suitable for MVP and low-budget
deployment.

1 MAP DISPLAY API (OpenStreetMap + Leaflet)

API Type: Open Public API

Description:

Displays property locations on interactive maps using latitude and

longitude values from the AaoStays backend.

Base URL:

[Link]

Frontend Library:

[Link]

Purpose:
Render map tiles and show property markers using the coordinates
provided by the backend.

Example Usage

Request:

The frontend uses property coordinates from your

/api/v1/properties/{id}/location endpoint.

Example Input Data:

"latitude": 15.5187,

"longitude": 73.7596,

"propertyName": "The South Villa"

Example Map Tile Request:

[Link]

Response:

Tile image for that section of the map (used by Leaflet to render
dynamically).

200 OK

Map tiles load correctly; markers display based on latitude and

longitude.

400 Bad Request

Invalid coordinates or missing lat/lon.

503 Service Unavailable

OpenStreetMap servers are temporarily down.

Notes:

Free and open; no API key required.

Usage attribution: “© OpenStreetMap contributors.”

Rate-limit safe for up to ~2 map loads per second (per client).

2️EMAIL NOTIFICATION API (Mailtrap / Gmail SMTP)

API Type: SMTP-based (Free Tier)

Base URL:

[Link] (development)

[Link] (production)

Purpose:

Sends property-related email notifications (e.g., approval, booking

confirmation, updates).

Example Use Cases

Property approval notification to host

Booking confirmation to customer

Password reset or verification mail

Example Request (SMTP Payload)

{

"to": "host@[Link]",

"subject": "Your property has been approved!",

"message": "Congratulations! Your property 'The South Villa' is

now live on AaoStays."

Example Response

"status": 200,

"message": "Email sent successfully",

"recipient": "host@[Link]"

200 OK

Email successfully delivered to SMTP server.

400 Bad Request

Missing recipient or message body.

401 Unauthorized

Invalid SMTP credentials.

503 Service Unavailable

Email service (Mailtrap or Gmail) temporarily down.

Notes:

Free for up to 100 emails/day (Mailtrap).

Gmail SMTP works for low-volume transactional mail.

For production: upgrade to SendGrid / AWS SES.

3 SMS / PHONE NOTIFICATION API (Twilio / Fast2SMS)

API Type: REST

Purpose:

Send SMS alerts to hosts or guests for property updates, booking

confirmations, and OTPs.

Twilio Base URL:

[Link]
[Link]

Fast2SMS Base URL:

[Link]

Example Request (Twilio)

"to": "+919876543210",

"from": "+12025550123",

"body": "Your booking for The South Villa is confirmed!"

}
Example Response

"status": 200,

"message": "SMS sent successfully",

"sid": "SM9b8b1b8c1a8a1e1d2c3"

Status Codes

Code Meaning

200 SMS sent successfully

400 Invalid phone number or missing message

401 Unauthorized / Invalid API key

429 Too many requests (rate limit exceeded)

503 SMS gateway unavailable

Notes:

Free trial credits with Twilio.

Fast2SMS free sandbox available for testing.

Paid plan starts when sending real messages to production users.

Keep message length under 160 characters for single SMS cost.

4 IMAGE STORAGE API (Cloudinary)

API Type: REST (File Upload and Delivery)

Base URL:

[Link]

Purpose:

Handles property image uploads, optimization, and delivery via

CDN.

Stores image URLs in your PROPERTY_IMAGE table for later

retrieval.

Example Request

Endpoint:

POST [Link]

Request Body:

file: (binary image file)

upload_preset: aaostays_upload

Example Response

"asset_id": "a3b4d2b1cd5",

"public_id": "rooms/the_south_villa_front",

"version": 1731254321,
"url":
"[Link]
[Link]",

"secure_url":
"[Link]
[Link]"

201 Created

Image uploaded successfully.

400 Bad Request

Invalid image file or upload preset missing.

401 Unauthorized

Invalid Cloudinary API key or preset.

503 Service Unavailable

Cloudinary service temporarily down.

Notes:

Free tier includes 25 GB storage and bandwidth.

Automatically compresses and optimizes images.

URLs are globally CDN-accessible.

Ideal for hosting property and room images.

Summary of External APIs

Feature Service Base URL Free Tier Usage

Map Display OpenStreetMap + Leaflet

[Link] ✅
Display map and markers

Email Notifications Mailtrap / Gmail SMTP

[Link] / [Link] ✅ Send property
and booking emails

Phone Notifications Twilio / Fast2SMS

[Link] ✅ Send SMS alerts

Image Storage Cloudinary

[Link]
✅ Upload & host property images

Example AaoStays Integration Summary

Internal Endpoint External API Used Description

/api/v1/properties/{id}/location OpenStreetMap Fetch

map data and coordinates

/api/v1/notifications/email Mailtrap / Gmail Send approval

or booking mail

/api/v1/notifications/sms Twilio / Fast2SMS Send SMS

confirmation

/api/v1/properties/{id}/images Cloudinary Upload

property photos
---------------------------------------------------------------------------------
------------------------------------

PropertyImage

PROPERTY IMAGE API Documentation

Base URL: /api/v1/properties

Entity: PROPERTY_IMAGE

Description:

Manages property images — upload, view, update, delete images

for each property.

Each property can have multiple images and one primary image.

Add Property Image

Request Type: POST

Endpoint: /api/v1/properties/{propertyId}/images

Description: Uploads or adds an image for a specific property.

Request Body:

"imageUrl":
"[Link]
[Link]",

"imageCaption": "Ocean view from balcony",

"displayOrder": 1,
"isPrimary": true

201 Created

When the image is successfully added for the property.

Example Response:

"status": 201,

"message": "Property image added successfully",

"data": {

"imageId": 1001,

"propertyId": 501,

"imageUrl":
"[Link]
[Link]",

"isPrimary": true

Meaning:

The image was linked to the property and stored successfully.

Bad Request
If required fields are missing or image URL is invalid.

"status": 400,

"message": "Validation failed: imageUrl must not be empty"

Not Found

If the property ID does not exist.

"status": 404,

"message": "Property not found with ID: 501"

Internal Server Error

If something goes wrong during image saving.

"status": 500,

"message": "An unexpected error occurred while saving property

image."

Get All Images for a Property

Request Type: GET

Endpoint: /api/v1/properties/{propertyId}/images

Description: Fetch all images linked to a specific property.

200 OK

When images are found for the property.

Example Response:

"status": 200,

"message": "Property images retrieved successfully",

"data": [

"imageId": 1001,

"imageUrl":
"[Link]
[Link]",

"imageCaption": "Ocean view",

"isPrimary": true,

"displayOrder": 1

},

"imageId": 1002,
"imageUrl":
"[Link]
[Link]",

"imageCaption": "Living room",

"isPrimary": false,

"displayOrder": 2

404 Not Found

If no images exist for the property.

"status": 404,

"message": "No images found for property ID: 501"

500 Internal Server Error

If any issue occurs while retrieving images.

"status": 500,

"message": "Error occurred while fetching property images."

}

Get Primary Image for a Property

Request Type: GET

Endpoint: /api/v1/properties/{propertyId}/images/primary

Description: Fetch the primary image (main display photo) for a

property.

200 OK

Example Response:

"status": 200,

"message": "Primary image retrieved successfully",

"data": {

"imageId": 1001,

"imageUrl":
"[Link]
[Link]",

"isPrimary": true

404 Not Found

If no primary image is marked.

{

"status": 404,

"message": "No primary image found for property ID: 501"

Update Property Image Details

Request Type: PUT

Endpoint: /api/v1/properties/images/{imageId}

Description: Update caption, display order, or primary flag of an

image.

Request Body:

"imageCaption": "Updated: Sunset view",

"displayOrder": 2,

"isPrimary": false

200 OK

Example Response:

"status": 200,

"message": "Property image updated successfully",

"data": {

"imageId": 1001,

"imageCaption": "Updated: Sunset view",

"displayOrder": 2

404 Not Found

If the image ID doesn’t exist.

"status": 404,

"message": "Image not found with ID: 1001"

500 Internal Server Error

If something fails while updating.

"status": 500,

"message": "Error occurred while updating image."

Delete Property Image

Request Type: DELETE

Endpoint: /api/v1/properties/images/{imageId}

Description: Delete a specific image by its ID.

200 OK

Example Response:

"status": 200,

"message": "Property image deleted successfully"

404 Not Found

If the image ID doesn’t exist.

"status": 404,

"message": "Property image not found with ID: 1001"

500 Internal Server Error

If deletion fails due to backend issue.

"status": 500,
"message": "Error occurred while deleting property image."

PATCH /api/v1/properties/images/{imageId}/setPrimary

Purpose:

Sets a specific image as the primary (cover) image for a property.

This will automatically unmark any other image for that property
that was previously primary.

Request Type: PATCH

Endpoint Example:

/api/v1/properties/images/502/setPrimary

Request Body (optional):

"isPrimary": true

Success Response (200 OK):

"status": 200,

"message": "Image set as primary successfully",

"data": {

"imageId": 502,
"propertyId": 101,

"isPrimary": true

Error Responses:

Status Message

400 Invalid image ID or request

404 Image not found

409 Another image already marked as primary

500 Internal server error while updating

DELETE /api/v1/properties/{propertyId}/images

Purpose:

Deletes all images associated with a specific property.

Used when a property is removed or images need to be reset.

Request Type: DELETE

Endpoint Example:

/api/v1/properties/101/images

Success Response (200 OK):

{
"status": 200,

"message": "All images deleted successfully for property ID 101",

"deletedCount": 6

Error Responses:

Status Message

404 Property not found or no images exist

500 Internal server error while deleting images

PUT /api/v1/properties/{propertyId}/images/reorder

Purpose:

Updates the display order of multiple images for a property.

Used for rearranging the gallery display sequence on the website or

app.

Request Type: PUT

Endpoint Example:

/api/v1/properties/101/images/reorder

Request Body:

"imageOrder": [

{ "imageId": 501, "displayOrder": 1 },

{ "imageId": 502, "displayOrder": 2 },

{ "imageId": 503, "displayOrder": 3 }

Success Response (200 OK):

"status": 200,

"message": "Image order updated successfully",

"updatedCount": 3

Error Responses:

Status Message

400 Invalid or duplicate display order values

404 Property or image not found

500 Internal server error while updating order

---------------------------------------------------------------------------------
---------------------------------------------------------

CONTACT DETAILS API DOCUMENTATION

Base URL: /api/v1/contact-details

Entity: CONTACT_DETAILS
Description:

Manages the contact details of each property. Each property has

exactly one contact detail record that contains name, email, phone
numbers, and preferred contact method.

1. Add Contact Details

Request Type: POST

Endpoint: /api/v1/contact-details/{propertyId}

Description: Adds contact details for a specific property. Only one

contact record is allowed per property.

Request Body

"contactName": "Rishi Kumar",

"email": "[Link]@[Link]",

"primaryMobile": "+919876543210",

"alternateMobile": "+918765432101",

"preferredContactMethod": "PHONE"

201 Created

"status": 201,

"message": "Contact details added successfully",

"data": {

"contactId": 1001,

"propertyId": 501,

"contactName": "Rishi Kumar",

"email": "[Link]@[Link]",

"primaryMobile": "+919876543210",

"preferredContactMethod": "PHONE",

"createdAt": "2025-11-10T15:40:00Z"

Meaning: Contact details were successfully added and linked to the

property.

400 Bad Request

"status": 400,

"message": "Validation failed: primaryMobile must not be empty"

409 Conflict

"status": 409,
"message": "Contact details already exist for this property."

404 Not Found

"status": 404,

"message": "Property not found with ID: 501"

500 Internal Server Error

"status": 500,

"message": "An unexpected error occurred while saving contact

details."

2. Get Contact Details by Property ID

Request Type: GET

Endpoint: /api/v1/contact-details/{propertyId}

Description: Retrieves the contact details for a specific property.

200 OK

"status": 200,
"message": "Contact details retrieved successfully",

"data": {

"contactId": 1001,

"propertyId": 501,

"contactName": "Rishi Kumar",

"email": "[Link]@[Link]",

"primaryMobile": "+919876543210",

"alternateMobile": "+918765432101",

"preferredContactMethod": "PHONE"

404 Not Found

"status": 404,

"message": "Contact details not found for property ID: 501"

500 Internal Server Error

"status": 500,
"message": "Error occurred while retrieving contact details."

3. Update Contact Details

Request Type: PUT

Endpoint: /api/v1/contact-details/{propertyId}

Description: Updates contact details for a specific property.

Request Body

"contactName": "Rishi K",

"email": "[Link]@[Link]",

"primaryMobile": "+919812345678",

"alternateMobile": "+918700123456",

"preferredContactMethod": "EMAIL"

200 OK

"status": 200,

"message": "Contact details updated successfully",

"data": {
"contactId": 1001,

"propertyId": 501,

"email": "[Link]@[Link]",

"preferredContactMethod": "EMAIL",

"updatedAt": "2025-11-10T16:05:00Z"

404 Not Found

"status": 404,

"message": "Contact details not found for property ID: 501"

400 Bad Request

"status": 400,

"message": "Invalid email format"

500 Internal Server Error

{
"status": 500,

"message": "Error occurred while updating contact details."

4. Delete Contact Details

Request Type: DELETE

Endpoint: /api/v1/contact-details/{propertyId}

Description: Deletes the contact details of a specific property.

200 OK

"status": 200,

"message": "Contact details deleted successfully"

404 Not Found

"status": 404,

"message": "Contact details not found for property ID: 501"

500 Internal Server Error

{
"status": 500,

"message": "An unexpected error occurred while deleting contact

details."

5 PATCH /api/v1/properties/{propertyId}/contact/email

Purpose:

Update only the email field of a property’s contact.

Request Body:

"email": "[Link]@[Link]"

Success Response (200 OK):

"status": 200,

"message": "Contact email updated successfully"

Error Codes:

Code Meaning

400 Invalid email

404 Contact not found

500 Internal server error

6 PATCH /api/v1/properties/{propertyId}/contact/phone

Purpose:

Update only phone numbers of a contact.

Request Body:

"primaryMobile": "+919998887776",

"alternateMobile": "+919111223344"

Success Response (200 OK):

"status": 200,

"message": "Phone numbers updated successfully"

Error Codes:

Code Meaning

400 Invalid phone number format

404 Contact not found

7 PATCH /api/v1/properties/{propertyId}/contact/preferred-
method
Purpose:

Change the preferred contact method (PHONE, EMAIL, or

WHATSAPP).

Request Body:

"preferredContactMethod": "EMAIL"

Success Response (200 OK):

"status": 200,

"message": "Preferred contact method updated successfully"

Error Codes:

Code Meaning

400 Invalid contact method

404 Contact not found

---------------------------------------------------------------------------------
---------------------------------------------------

PROPERTY CATEGORY API DOCUMENTATION

Base URL: /api/v1/property-categories
Entity: PROPERTY_CATEGORY

Description:

This API manages the association between properties and

categories. Each property can belong to multiple categories, and
each category can be linked to multiple properties (many-to-many
relationship).

1. Add Property Category Link

Request Type: POST

Endpoint: /api/v1/property-categories

Description:

Creates a new link between a property and a category.

Request Body

"propertyId": 501,

"categoryId": 10

201 Created

"status": 201,

"message": "Property successfully linked to category",

"data": {
"propertyCategoryId": 1001,

"propertyId": 501,

"categoryId": 10,

"assignedAt": "2025-11-10T17:30:00Z"

Meaning:

The property has been assigned to the given category.

400 Bad Request

"status": 400,

"message": "Validation failed: propertyId and categoryId are

required"

404 Not Found

"status": 404,

"message": "Property or Category not found"

409 Conflict
{

"status": 409,

"message": "This property is already linked to the specified

category"

500 Internal Server Error

"status": 500,

"message": "Error occurred while linking property to category"

2. Get Categories by Property ID

Request Type: GET

Endpoint: /api/v1/property-categories/property/{propertyId}

Description:

Fetches all categories assigned to a specific property.

200 OK

"status": 200,

"message": "Categories retrieved successfully for property",

"data": [
{ "categoryId": 10, "categoryName": "Luxury" },

{ "categoryId": 11, "categoryName": "Beachfront" },

{ "categoryId": 12, "categoryName": "Family Stay" }

404 Not Found

"status": 404,

"message": "No categories found for property ID: 501"

500 Internal Server Error

"status": 500,

"message": "Error occurred while retrieving categories for

property"

3. Get Properties by Category ID

Request Type: GET

Endpoint: /api/v1/property-categories/category/{categoryId}

Description:
Fetches all properties linked to a specific category.

200 OK

"status": 200,

"message": "Properties retrieved successfully for category",

"data": [

{ "propertyId": 501, "propertyName": "The South Villa" },

{ "propertyId": 502, "propertyName": "Hilltop Cottage" }

404 Not Found

"status": 404,

"message": "No properties found for category ID: 10"

500 Internal Server Error

"status": 500,

"message": "Error occurred while retrieving properties for

category"
}

4. Delete Property Category Link

Request Type: DELETE

Endpoint: /api/v1/property-categories/{propertyCategoryId}

Description:

Removes the link between a property and a category.

200 OK

"status": 200,

"message": "Property successfully unlinked from category"

404 Not Found

"status": 404,

"message": "Property category link not found with ID: 1001"

500 Internal Server Error

"status": 500,
"message": "Error occurred while deleting property-category link"

5. Remove Category from Property

Request Type: DELETE

Endpoint:
/api/v1/property-categories/property/{propertyId}/category/{categ
oryId}

Description:

Deletes a specific property-category relationship using property

and category IDs.

200 OK

"status": 200,

"message": "Category removed from property successfully"

404 Not Found

"status": 404,

"message": "No link found between property ID 501 and category

ID 10"

}
500 Internal Server Error

"status": 500,

"message": "Error occurred while removing category from

property"

POST /api/v1/properties/{propertyId}/categories

Purpose:

Assign multiple categories to a property in a single request.

Used when a host or admin links multiple category types (e.g.,

Luxury, Beachfront, Family) to one property.

Request Type: POST

Endpoint Example:

/api/v1/properties/101/categories

Request Body:

"categoryIds": [1, 3, 5]

1 → “Luxury”

3 → “Family”
5 → “Beachfront”

Success Response (201 Created):

"status": 201,

"message": "Categories assigned successfully to property ID 101",

"data": {

"propertyId": 101,

"assignedCategories": [

{ "categoryId": 1, "categoryName": "Luxury" },

{ "categoryId": 3, "categoryName": "Family" },

{ "categoryId": 5, "categoryName": "Beachfront" }

],

"totalAssigned": 3

Error Responses:

Status Message

400 Invalid or empty category list

404 Property or one of the category IDs not found

409 Category already linked to property

500 Internal server error while assigning

DELETE /api/v1/properties/{propertyId}/categories

Purpose:

Remove all category associations for a specific property.

Used during property deletion or when resetting category

assignments.

Request Type: DELETE

Endpoint Example:

/api/v1/properties/101/categories

Success Response (200 OK):

"status": 200,

"message": "All category links removed successfully for property

ID 101",

"deletedCount": 3

Error Responses:

Status Message

404 Property not found or no categories linked

500 Internal server error while deleting mappings

---------------------------------------------------------------------------------
---------------------------------------

PROPERTY AMENITY API DOCUMENTATION

Base URL: /api/v1/property-amenities

Entity: PROPERTY_AMENITY

Description:

Manages property–amenity relationships, allowing you to assign,

update, or remove amenities for a given property.

1. Add Property Amenity

Request Type: POST

Endpoint: /api/v1/property-amenities

Description:

Links a property with an amenity. Each property–amenity pair is

unique.

Request Body

"propertyId": 501,

"amenityId": 20,

"isAvailable": true,

"notes": "Available in all rooms"

}

201 Created

"status": 201,

"message": "Property successfully linked to amenity",

"data": {

"propertyAmenityId": 3001,

"propertyId": 501,

"amenityId": 20,

"isAvailable": true,

"notes": "Available in all rooms",

"assignedAt": "2025-11-10T17:55:00Z"

Meaning:

The property was successfully assigned the given amenity.

400 Bad Request

"status": 400,
"message": "Validation failed: propertyId and amenityId are
required"

404 Not Found

"status": 404,

"message": "Property or Amenity not found"

409 Conflict

"status": 409,

"message": "This amenity is already assigned to the property"

500 Internal Server Error

"status": 500,

"message": "Error occurred while linking property to amenity"

2. Get Amenities by Property ID

Request Type: GET

Endpoint: /api/v1/property-amenities/property/{propertyId}

Description:

Retrieves all amenities assigned to a particular property.

200 OK

"status": 200,

"message": "Amenities retrieved successfully for property",

"data": [

{ "amenityId": 20, "amenityName": "WiFi", "isAvailable": true },

{ "amenityId": 21, "amenityName": "Air Conditioning",

"isAvailable": true },

{ "amenityId": 22, "amenityName": "Private Parking",

"isAvailable": false }

404 Not Found

"status": 404,

"message": "No amenities found for property ID: 501"

}
500 Internal Server Error

"status": 500,

"message": "Error occurred while retrieving amenities for

property"

3. Get Properties by Amenity ID

Request Type: GET

Endpoint: /api/v1/property-amenities/amenity/{amenityId}

Description:

Retrieves all properties that have a particular amenity assigned.

200 OK

"status": 200,

"message": "Properties retrieved successfully for amenity",

"data": [

{ "propertyId": 501, "propertyName": "The South Villa",

"isAvailable": true },

{ "propertyId": 502, "propertyName": "Hilltop Cottage",

"isAvailable": true }

]
}

404 Not Found

"status": 404,

"message": "No properties found with amenity ID: 20"

500 Internal Server Error

"status": 500,

"message": "Error occurred while retrieving properties for

amenity"

4. Update Amenity Availability or Notes

Request Type: PUT

Endpoint: /api/v1/property-amenities/{propertyAmenityId}

Description:

Updates the availability or notes for a property–amenity link.

Request Body

"isAvailable": false,
"notes": "Under maintenance for now"

200 OK

"status": 200,

"message": "Property amenity updated successfully",

"data": {

"propertyAmenityId": 3001,

"propertyId": 501,

"amenityId": 20,

"isAvailable": false,

"notes": "Under maintenance for now"

404 Not Found

"status": 404,

"message": "Property amenity link not found with ID: 3001"

}
500 Internal Server Error

"status": 500,

"message": "Error occurred while updating property amenity"

5. Delete Property Amenity Link

Request Type: DELETE

Endpoint: /api/v1/property-amenities/{propertyAmenityId}

Description:

Removes the link between a property and an amenity.

200 OK

"status": 200,

"message": "Amenity successfully removed from property"

404 Not Found

"status": 404,

"message": "Property amenity link not found with ID: 3001"

}

500 Internal Server Error

"status": 500,

"message": "Error occurred while deleting property amenity link"

Get Missing Amenities for a Property

Request Type: GET

Endpoint:

/api/v1/property-amenities/property/{propertyId}/missing

Description:

Fetches a list of amenities that are not yet assigned to a given

property.

Useful for suggesting missing amenities when editing a property

listing.

Example:

/api/v1/property-amenities/property/501/missing

Success Response (200 OK):

"status": 200,
"message": "Missing amenities retrieved successfully for property
ID 501",

"data": [

{ "amenityId": 25, "amenityName": "Gym Access" },

{ "amenityId": 26, "amenityName": "Mini Bar" },

{ "amenityId": 27, "amenityName": "Jacuzzi" }

],

"missingCount": 3

Error Responses:

Status Message

404 Property not found

204 All amenities are already assigned to this property

500 Error occurred while retrieving missing amenities

7. Add Multiple Amenities (Bulk Assign)

Request Type: POST

Endpoint:

/api/v1/property-amenities/property/{propertyId}/bulk

Description:

Assigns multiple amenities to a property in one request.

Used during property setup or when applying a default amenity
package.

Request Body:

"amenities": [

{ "amenityId": 20, "isAvailable": true, "notes": "Available in all

rooms" },

{ "amenityId": 22, "isAvailable": false, "notes": "Under

renovation" },

{ "amenityId": 23, "isAvailable": true, "notes": "Extra charge

applicable" }

Success Response (201 Created):

"status": 201,

"message": "3 amenities assigned successfully to property ID 501",

"data": {

"assignedCount": 3,

"propertyId": 501

}
}

Error Responses:

Status Message

400 Invalid or empty amenities list

404 Property or one of the amenities not found

409 Duplicate amenities detected for property

500 Internal server error while assigning amenities

8. Bulk Update Amenities for a Property

Request Type: PUT

Endpoint:

/api/v1/property-amenities/property/{propertyId}/bulk-update

Description:

Updates multiple amenities’ isAvailable and/or notes fields in one

go.

Ideal for seasonal updates or maintenance changes.

Request Body:

"amenities": [

{ "amenityId": 20, "isAvailable": false, "notes": "Temporarily

closed for service" },
{ "amenityId": 23, "isAvailable": true, "notes": "Now available for
guests" }

Success Response (200 OK):

"status": 200,

"message": "Property amenities updated successfully for property

ID 501",

"data": {

"updatedCount": 2

Error Responses:

Status Message

400 Invalid data or missing amenity IDs

404 Property or amenity links not found

500 Error occurred while updating property amenities

---------------------------------------------------------------------------------
----

ROOM API DOCUMENTATION

Base URL: /api/v1/rooms

Entity: ROOM

Description:

Manages individual room data under a property, including pricing,

capacity, and status.

Each property can contain multiple rooms, each with its own
details and availability status.

1. Add Room

Request Type: POST

Endpoint: /api/v1/rooms/{propertyId}

Description:

Adds a new room under a specific property.

Request Body

"roomNumber": "A101",

"roomType": "Deluxe",

"roomName": "Ocean View Suite",

"roomDescription": "Spacious suite with sea view, balcony, and

modern amenities.",

"baseGuests": 2,

"maxGuests": 4,
"extraGuestAllowed": true,

"extraGuestFee": 500.00,

"pricePerNight": 8000.00,

"bedType": "King",

"bedCount": 1,

"roomSizeSqft": 350,

"hasBalcony": true,

"hasWindow": true,

"floorNumber": 1

201 Created

"status": 201,

"message": "Room added successfully",

"data": {

"roomId": 101,

"propertyId": 501,

"roomNumber": "A101",

"roomType": "Deluxe",
"roomStatus": "AVAILABLE",

"pricePerNight": 8000.00,

"createdAt": "2025-11-10T18:10:00Z"

400 Bad Request

"status": 400,

"message": "Validation failed: pricePerNight must be greater than

0"

404 Not Found

"status": 404,

"message": "Property not found with ID: 501"

500 Internal Server Error

"status": 500,
"message": "An unexpected error occurred while saving room
details"

2. Get All Rooms by Property ID

Request Type: GET

Endpoint: /api/v1/rooms/property/{propertyId}

Description:

Fetches all rooms associated with a specific property.

200 OK

"status": 200,

"message": "Rooms retrieved successfully",

"data": [

"roomId": 101,

"roomName": "Ocean View Suite",

"roomType": "Deluxe",

"pricePerNight": 8000.00,

"roomStatus": "AVAILABLE"

},
{

"roomId": 102,

"roomName": "Standard Room",

"roomType": "Standard",

"pricePerNight": 4500.00,

"roomStatus": "OCCUPIED"

404 Not Found

"status": 404,

"message": "No rooms found for property ID: 501"

500 Internal Server Error

"status": 500,

"message": "Error occurred while fetching room list"

}
3. Get Room by ID

Request Type: GET

Endpoint: /api/v1/rooms/{roomId}

Description:

Retrieves full details of a specific room by room ID.

200 OK

"status": 200,

"message": "Room details retrieved successfully",

"data": {

"roomId": 101,

"roomName": "Ocean View Suite",

"roomType": "Deluxe",

"pricePerNight": 8000.00,

"baseGuests": 2,

"maxGuests": 4,

"extraGuestFee": 500.00,

"roomStatus": "AVAILABLE",

"bedType": "King",
"roomSizeSqft": 350,

"hasBalcony": true,

"floorNumber": 1

404 Not Found

"status": 404,

"message": "Room not found with ID: 101"

4. Update Room Details

Request Type: PUT

Endpoint: /api/v1/rooms/{roomId}

Description:

Updates the details of an existing room.

Request Body

"pricePerNight": 8500.00,

"roomStatus": "MAINTENANCE",
"maxGuests": 3

200 OK

"status": 200,

"message": "Room updated successfully",

"data": {

"roomId": 101,

"pricePerNight": 8500.00,

"roomStatus": "MAINTENANCE",

"updatedAt": "2025-11-10T18:15:00Z"

404 Not Found

"status": 404,

"message": "Room not found with ID: 101"

500 Internal Server Error

{

"status": 500,

"message": "Error occurred while updating room details"

5. Delete Room

Request Type: DELETE

Endpoint: /api/v1/rooms/{roomId}

Description:

Deletes a room (soft delete or cascade based on implementation).

200 OK

"status": 200,

"message": "Room deleted successfully"

404 Not Found

"status": 404,

"message": "Room not found with ID: 101"

}
500 Internal Server Error

"status": 500,

"message": "Error occurred while deleting room"

6. Update Room Status

Request Type: PATCH

Endpoint: /api/v1/rooms/{roomId}/status

Description:

Updates the availability status of a room.

Request Body

"roomStatus": "BLOCKED"

200 OK

"status": 200,

"message": "Room status updated successfully",

"data": {
"roomId": 101,

"roomStatus": "BLOCKED"

404 Not Found

"status": 404,

"message": "Room not found with ID: 101"

Get All Rooms by Property ID

Request Type: GET

Endpoint:

/api/v1/rooms/property/{propertyId}

Description:

Fetches all rooms under a specific property, including their type,

price, and current status.

Used in property detail pages and host dashboards.

Example:

/api/v1/rooms/property/501

Success Response (200 OK):

{

"status": 200,

"message": "Rooms retrieved successfully for property ID 501",

"data": [

"roomId": 101,

"roomName": "Deluxe Suite",

"roomType": "Deluxe",

"pricePerNight": 8500.00,

"roomStatus": "AVAILABLE"

},

"roomId": 102,

"roomName": "Standard Room",

"roomType": "Standard",

"pricePerNight": 5500.00,

"roomStatus": "OCCUPIED"

],
"totalRooms": 2

Error Responses:

Status Message

404 No rooms found for property ID: 501

500 Internal server error while retrieving rooms

2. Get Available Rooms for a Property

Request Type: GET

Endpoint:

/api/v1/rooms/property/{propertyId}/available

Description:

Returns only rooms that are currently marked as AVAILABLE

under the specified property.

Used by frontend and booking modules.

Example:

/api/v1/rooms/property/501/available

Success Response (200 OK):

"status": 200,

"message": "Available rooms retrieved successfully",

"data": [

"roomId": 101,

"roomName": "Deluxe Suite",

"pricePerNight": 8500.00,

"baseGuests": 2,

"maxGuests": 4

},

"roomId": 103,

"roomName": "Garden View Room",

"pricePerNight": 6000.00,

"baseGuests": 2,

"maxGuests": 3

],

"availableCount": 2

Error Responses:
Status Message

404 No available rooms found for property ID: 501

500 Error occurred while fetching available rooms

3. Search or Filter Rooms

Request Type: GET

Endpoint:

/api/v1/rooms/search

Description:

Search and filter rooms by multiple parameters such as room type,

price range, or status.

Supports query parameters for flexibility.

Query Parameters:

Parameter Type Description

type String Filter by room type (e.g., Deluxe, Standard)

minPrice DoubleMinimum room price

maxPrice DoubleMaximum room price

status String Filter by status (AVAILABLE, OCCUPIED,

MAINTENANCE)

Example:
/api/v1/rooms/search?
type=Deluxe&minPrice=5000&maxPrice=10000&status=AVAIL
ABLE

Success Response (200 OK):

"status": 200,

"message": "Filtered room list retrieved successfully",

"data": [

"roomId": 101,

"propertyId": 501,

"roomName": "Deluxe Suite",

"pricePerNight": 8500.00,

"status": "AVAILABLE"

],

"filters": {

"type": "Deluxe",

"minPrice": 5000,

"maxPrice": 10000,
"status": "AVAILABLE"

},

"totalResults": 1

Error Responses:

Status Message

204 No rooms match the given filter criteria

500 Internal server error during search

4. Get Property Room Price Range

Request Type: GET

Endpoint:

/api/v1/rooms/property/{propertyId}/price-range

Description:

Retrieves the minimum and maximum room prices for a specific

property.

Used for displaying filters or price sliders in the frontend.

Example:

/api/v1/rooms/property/501/price-range

Success Response (200 OK):

{
"status": 200,

"message": "Price range retrieved successfully for property ID

501",

"data": {

"minPrice": 4500.00,

"maxPrice": 9000.00

Error Responses:

Status Message

404 No room data found for property ID: 501

500 Internal server error while calculating price range

---------------------------------------------------------------------------------
--------------------------------------------

ROOM IMAGE API DOCUMENTATION

Base URL: /api/v1/rooms/images

Entity: ROOM_IMAGE

Description:

Manages room images (multiple per room), including upload,

retrieval, and deletion.

1. Add Room Image

Request Type: POST

Endpoint: /api/v1/rooms/{roomId}/images

Description: Adds an image to a specific room.

Request Body

"imageUrl":
"[Link]
[Link]",

"imageCaption": "Balcony view",

"displayOrder": 1,

"isPrimary": true

201 Created

"status": 201,

"message": "Room image added successfully",

"data": {

"imageId": 501,

"roomId": 101,
"imageUrl":
"[Link]
[Link]",

"isPrimary": true

404 Not Found

"status": 404,

"message": "Room not found with ID: 101"

500 Internal Server Error

"status": 500,

"message": "Error occurred while saving room image"

2. Get All Images for a Room

Request Type: GET

Endpoint: /api/v1/rooms/{roomId}/images

Description: Fetches all images linked to a specific room.

200 OK

"status": 200,

"message": "Room images retrieved successfully",

"data": [

"imageId": 501,

"imageUrl":
"[Link]
[Link]",

"isPrimary": true

},

"imageId": 502,

"imageUrl":
"[Link]
[Link]",

"isPrimary": false

}
3. Delete Room Image

Request Type: DELETE

Endpoint: /api/v1/rooms/images/{imageId}

Description: Deletes a room image by its ID.

200 OK

"status": 200,

"message": "Room image deleted successfully"

404 Not Found

"status": 404,

"message": "Room image not found with ID: 501"

---------------------------------------------------------------------------------
---------------------------------------------------

COUPON API DOCUMENTATION

Base URL: /api/v1/coupons

Entity: COUPON

Description:
Handles the creation, retrieval, update, and deletion of discount
coupons.

Each coupon can offer a percentage or fixed discount, may be

limited by usage, validity dates, and applicable user types or
booking conditions.

1. Add Coupon

Request Type: POST

Endpoint: /api/v1/coupons

Description:

Creates a new discount coupon. Only admins can add coupons.

Request Body

"couponCode": "AAO2025",

"couponName": "AaoStays Launch Offer",

"description": "Flat 20% discount for new users on first booking",

"discountType": "PERCENTAGE",

"discountValue": 20.00,

"maxDiscountAmount": 1000.00,

"minBookingAmount": 2000.00,

"validFrom": "2025-11-01",

"validUntil": "2025-12-31",
"usageLimit": 500,

"usageLimitPerUser": 1,

"applicableTo": "FIRST_BOOKING",

"applicableUserType": "NEW_USER",

"isActive": true,

"createdByAdminId": 1

201 Created

"status": 201,

"message": "Coupon created successfully",

"data": {

"couponId": 101,

"couponCode": "AAO2025",

"discountType": "PERCENTAGE",

"discountValue": 20.00,

"validFrom": "2025-11-01",

"validUntil": "2025-12-31",

"isActive": true
}

400 Bad Request

"status": 400,

"message": "Validation failed: discountValue must be greater than

0"

409 Conflict

"status": 409,

"message": "Coupon code already exists"

500 Internal Server Error

"status": 500,

"message": "Error occurred while creating coupon"

2. Get All Coupons

Request Type: GET

Endpoint: /api/v1/coupons

Description:

Fetches all available coupons (active and inactive).

200 OK

"status": 200,

"message": "Coupons retrieved successfully",

"data": [

"couponId": 101,

"couponCode": "AAO2025",

"couponName": "AaoStays Launch Offer",

"discountType": "PERCENTAGE",

"discountValue": 20.00,

"validUntil": "2025-12-31",

"isActive": true

},

"couponId": 102,
"couponCode": "WELCOME500",

"couponName": "Welcome Bonus",

"discountType": "FIXED_AMOUNT",

"discountValue": 500.00,

"validUntil": "2025-11-30",

"isActive": false

404 Not Found

"status": 404,

"message": "No coupons found"

500 Internal Server Error

"status": 500,

"message": "Error occurred while fetching coupons"

}
3. Get Coupon by Code

Request Type: GET

Endpoint: /api/v1/coupons/{couponCode}

Description:

Retrieves coupon details by coupon code.

200 OK

"status": 200,

"message": "Coupon details retrieved successfully",

"data": {

"couponId": 101,

"couponCode": "AAO2025",

"couponName": "AaoStays Launch Offer",

"discountType": "PERCENTAGE",

"discountValue": 20.00,

"maxDiscountAmount": 1000.00,

"minBookingAmount": 2000.00,

"validFrom": "2025-11-01",

"validUntil": "2025-12-31",
"usageLimit": 500,

"usedCount": 100,

"applicableUserType": "NEW_USER",

"isActive": true

404 Not Found

"status": 404,

"message": "Coupon not found with code: AAO2025"

4. Update Coupon

Request Type: PUT

Endpoint: /api/v1/coupons/{couponId}

Description:

Updates an existing coupon’s details.

Request Body

"couponName": "Updated Launch Offer",

"discountValue": 25.00,

"validUntil": "2026-01-15",

"isActive": true

200 OK

"status": 200,

"message": "Coupon updated successfully",

"data": {

"couponId": 101,

"couponCode": "AAO2025",

"discountValue": 25.00,

"validUntil": "2026-01-15",

"updatedAt": "2025-11-10T18:45:00Z"

404 Not Found

"status": 404,
"message": "Coupon not found with ID: 101"

500 Internal Server Error

"status": 500,

"message": "Error occurred while updating coupon"

5. Deactivate Coupon

Request Type: PATCH

Endpoint: /api/v1/coupons/{couponId}/deactivate

Description:

Deactivates a coupon (sets isActive = false).

200 OK

"status": 200,

"message": "Coupon deactivated successfully",

"data": {

"couponId": 101,

"couponCode": "AAO2025",
"isActive": false

404 Not Found

"status": 404,

"message": "Coupon not found with ID: 101"

6. Delete Coupon

Request Type: DELETE

Endpoint: /api/v1/coupons/{couponId}

Description:

Deletes a coupon permanently from the system.

200 OK

"status": 200,

"message": "Coupon deleted successfully"

404 Not Found

{

"status": 404,

"message": "Coupon not found with ID: 101"

500 Internal Server Error

"status": 500,

"message": "Error occurred while deleting coupon"

7. Validate Coupon (Apply During Booking)

Request Type: POST

Endpoint: /api/v1/coupons/validate

Description:

Validates if a coupon can be applied for a given booking (based on

amount, user type, validity, etc.).

Request Body

"couponCode": "AAO2025",

"userId": 2001,

"bookingAmount": 5000.00
}

200 OK

"status": 200,

"message": "Coupon applied successfully",

"data": {

"couponCode": "AAO2025",

"discountAmount": 1000.00,

"finalAmount": 4000.00

400 Bad Request

"status": 400,

"message": "Coupon is not valid for this booking or has expired"

404 Not Found

"status": 404,
"message": "Coupon not found or inactive"

----------------------------------------------------

NOTIFICATION API DOCUMENTATION

Base URL: /api/v1/notifications

Entity: NOTIFICATION

Description:

Handles creation, retrieval, update, and management of user

notifications.

Each notification belongs to a specific user and may relate to a

booking, payment, or other entity.

1. Create Notification

Request Type: POST

Endpoint: /api/v1/notifications

Description:

Creates and sends a notification to a user through one or more

channels (in-app, email, SMS, push).

Request Body

"userId": 1001,

"notificationType": "BOOKING_CONFIRMED",
"notificationChannel": "IN_APP",

"title": "Booking Confirmed!",

"message": "Your booking #BKG12345 has been confirmed

successfully.",

"actionUrl": "[Link]

"relatedEntityType": "BOOKING",

"relatedEntityId": 501,

"priority": "NORMAL"

201 Created

"status": 201,

"message": "Notification created successfully",

"data": {

"notificationId": 2001,

"userId": 1001,

"title": "Booking Confirmed!",

"notificationType": "BOOKING_CONFIRMED",

"isRead": false,

"createdAt": "2025-11-10T19:05:00Z"
}

400 Bad Request

"status": 400,

"message": "Validation failed: userId and message are required"

404 Not Found

"status": 404,

"message": "User not found with ID: 1001"

500 Internal Server Error

"status": 500,

"message": "Error occurred while sending notification"

2. Get All Notifications by User

Request Type: GET

Endpoint: /api/v1/notifications/user/{userId}

Description:

Retrieves all notifications for a specific user, optionally filtered by

read/unread status.

Example Query Parameters

/api/v1/notifications/user/1001?isRead=false

200 OK

"status": 200,

"message": "Notifications retrieved successfully",

"data": [

"notificationId": 2001,

"title": "Booking Confirmed!",

"message": "Your booking #BKG12345 has been confirmed

successfully.",

"isRead": false,

"notificationType": "BOOKING_CONFIRMED",

"priority": "NORMAL",

"createdAt": "2025-11-10T19:05:00Z"
},

"notificationId": 2002,

"title": "Payment Received",

"message": "Your payment of ₹8500 has been successfully

processed.",

"isRead": true,

"notificationType": "PAYMENT_SUCCESS",

"priority": "NORMAL",

"createdAt": "2025-11-09T11:32:00Z"

404 Not Found

"status": 404,

"message": "No notifications found for user ID: 1001"

500 Internal Server Error

{
"status": 500,

"message": "Error occurred while fetching user notifications"

3. Get Notification by ID

Request Type: GET

Endpoint: /api/v1/notifications/{notificationId}

Description:

Fetches detailed information for a specific notification.

200 OK

"status": 200,

"message": "Notification details retrieved successfully",

"data": {

"notificationId": 2001,

"userId": 1001,

"title": "Booking Confirmed!",

"message": "Your booking #BKG12345 has been confirmed

successfully.",

"notificationType": "BOOKING_CONFIRMED",

"relatedEntityType": "BOOKING",
"relatedEntityId": 501,

"isRead": false,

"priority": "NORMAL",

"createdAt": "2025-11-10T19:05:00Z"

404 Not Found

"status": 404,

"message": "Notification not found with ID: 2001"

4. Mark Notification as Read

Request Type: PATCH

Endpoint: /api/v1/notifications/{notificationId}/read

Description:

Marks a single notification as read.

200 OK

"status": 200,
"message": "Notification marked as read successfully",

"data": {

"notificationId": 2001,

"isRead": true,

"readAt": "2025-11-10T19:15:00Z"

404 Not Found

"status": 404,

"message": "Notification not found with ID: 2001"

5. Mark All Notifications as Read (for a User)

Request Type: PATCH

Endpoint: /api/v1/notifications/user/{userId}/read-all

Description:

Marks all notifications for a user as read.

200 OK

{
"status": 200,

"message": "All notifications marked as read for user ID: 1001"

404 Not Found

"status": 404,

"message": "No unread notifications found for user ID: 1001"

6. Delete Notification

Request Type: DELETE

Endpoint: /api/v1/notifications/{notificationId}

Description:

Deletes a notification by ID.

200 OK

"status": 200,

"message": "Notification deleted successfully"

404 Not Found

{

"status": 404,

"message": "Notification not found with ID: 2001"

500 Internal Server Error

"status": 500,

"message": "Error occurred while deleting notification"

7. Filter Notifications by Type or Priority

Request Type: GET

Endpoint: /api/v1/notifications/user/{userId}/filter

Description:

Fetches notifications by type or priority using query parameters.

Example Query Parameters

/api/v1/notifications/user/1001/filter?
type=PAYMENT_SUCCESS&priority=HIGH

200 OK

"status": 200,
"message": "Filtered notifications retrieved successfully",

"data": [

"notificationId": 2020,

"title": "Payment Success",

"message": "Your payment of ₹12,000 was successful.",

"priority": "HIGH",

"isRead": false