Whimstay Cozycozy API Documentation

⚙

Authentication & Common Response

Request Headers

Every request must include a valid Authorization header with a JWT token (Bearer <token>). POST requests also require Content-Type: application/json.

Response Envelope Fields

Field	Type	Description
time	string	Server timestamp (ISO-8601)
status	integer	HTTP-style status code
message	string	Short human-readable message
errorCode	long \| null	Internal error code on failure; `null` on success
errorMessage	string \| null	Detailed error description on failure
data	object \| null	Endpoint-specific payload

1

Search API

Search for properties by location, dates, guest count, and filters.

POST /v1/cozycozy/search

Note: If locationName is given then data will be returned based on that location. If not present then bounds(viewport bounds) will be required to search properties.

Request — Location

Field	Type	Description
locationName	string	Location name (e.g. "Destin, Florida, US") Note: For city this pattern should follow. For state search it should be Florida, US and for country it should be country only.
bounds	string	8-coordinate map bounds: seLat, seLng, nwLat, nwLng, swLat, swLng, neLat, neLng
lat	double	Latitude of search center Range: [-90, 90]
lng	double	Longitude of search center Range: [-180, 180]
startDate	string	Check-in date of stay Format: yyyy-MM-dd
endDate	string	Check-out date of stay Format: yyyy-MM-dd
adults	int	Number of adults
children	int	Number of children
minBedrooms	int	Minimum bedrooms
minBathrooms	int	Minimum bathrooms
minRating	int	Minimum rating
amenities	list<string>	Filter for amenities (e.g. "WiFi", "Pool")
petsAllowed	boolean	Filter for pet-friendly listings
partiesAllowed	boolean	Filter for party-allowed listings
smokingAllowed	boolean	Filter for smoking-allowed listings
childFriendly	boolean	Filter for child-suitable listings
wheelchairAccessible	boolean	Filter for wheelchair-accessible listings
minPrice	int	Minimum nightly price
maxPrice	int	Maximum nightly price
page	int	Page number
limit	int	Results per page

Response — data

Field	Type	Description
properties	array	List of properties data
propertyCount	string \| null	Total number of properties matching the query.

Response — Property Object (properties[])

Field	Type	Description
propertyId	string	Whimstay property ID
propertyName	string	Property display name
propertyType	string	Property type
city	string	City
state	string	State
country	string	Country
latitude	double	Latitude
longitude	double	Longitude
maxGuests	int	Maximum guest capacity
bedrooms	short	Number of bedrooms
bathrooms	float	Number of bathrooms
beds	int	Number of beds
hasKitchen	boolean	Has kitchen
hasWifi	boolean	Has wifi
petsAllowed	boolean	Pets allowed
childFriendly	boolean	Child friendly
rating	double	Average rating
reviewCount	long	Number of reviews
images	array	List of image URLs
total	double	Total price

2

Calendar Availability API

Returns day-by-day availability and for a property over a date range.

GET /v1/cozycozy/calendar-availability

Request — Query Parameters

Validation: startDate must be today or later · endDate must be ≥ startDate

Parameter	Type	Required	Description
propertyId	string	Yes	Whimstay property ID
startDate	string	No	Inclusive range start Format: yyyy-MM-dd · Default: today
endDate	string	No	Inclusive range end Format: yyyy-MM-dd

Response — data

Field	Type	Description
propertyId	string	Whimstay property ID
days	array	One entry per day in the requested range (see Day Object below)
errorMessage	string \| null	Error message if any or null

Response — Day Object (days[])

Field	Type	Description
date	string	Calendar date Format: yyyy-MM-dd
arrival	boolean	Guest may check in on this date
departure	boolean	Guest may check out on this date
available	boolean	Date is open (not blocked or booked)
minStay	int	Minimum nights from this date
maxStay	int	Maximum nights from this date

3

Quote API

Returns a real-time price quote for a stay.

POST /v1/cozycozy/quote

Request

Validation: checkIn must be today or later · checkOut must be after checkIn · Stay length must not exceed property's maxStay

Field	Type	Required	Description
propertyId	string	Yes	Whimstay property ID
checkIn	string	Yes	Check-in date Format: yyyy-MM-dd
checkOut	string	Yes	Check-out date Format: yyyy-MM-dd
adults	int	Yes	Number of adults, ≥ 1
children	int	No	Number of children
pets	int	No	Number of pets

Response — data

Field	Type	Description
propertyId	string	Whimstay property ID
currency	string	Currency code (USD only)
total	double	Final total amount payable for the stay
errorMessage	string \| null	Populated on validation or availability errors

4

Property Detail Page (PDP) API

Returns the full dataset for a single property — descriptions, images, amenities info.

GET /v1/cozycozy/property/{propertyId}

Request — Path Parameter

Parameter	Type	Required	Description
propertyId	string	Yes	Whimstay property ID (e.g. 6f15e9964d13cca9a68a8965c7dbca2h)

Response — Identity

Field	Type	Description
propertyId	string	Whimstay property ID
propertyName	string	Property display name
propertyType	string	Property type (e.g. House, Apartment)
maxGuests	int	Maximum guest capacity
bedrooms	int	Number of bedrooms
bathrooms	float	Number of bathrooms
beds	int	Number of beds
checkInTime	string	Check-in time
checkOutTime	string	Check-out time
description	string	Full property description
images	list<string>	List of image URLs
amenities	list<string>	List of feature names (e.g. "WiFi", "Kitchen")
petsAllowed	boolean	If property is pet-friendly or not
partiesAllowed	boolean	If parties are allowed or not
smokingAllowed	boolean	If smoking is allowed or not
childFriendly	boolean	If children are allowed or not
wheelchairAccessible	boolean	If wheelchair access is available or not

Whimstay CozycozyIntegration APIs

Authentication & Common Response

Request Headers

Search API

Calendar Availability API

Quote API

Property Detail Page (PDP) API

Whimstay Cozycozy
Integration APIs